20. خادم QGIS ولغة Python

20.1. المقدمة

لمعرفة المزيد عن QGIS Server، اقرأ دليل QGIS Server.

يتكون QGIS Server من ثلاثة أشياء مختلفة:

1. مكتبة QGIS Server: مكتبة توفر واجهة API لإنشاء خدمات ويب OGC

2. QGIS Server FCGI: تطبيق ثنائي FCGI هو qgis_mapserv.fcgi يُنفّذ مع خادم ويب مجموعة من خدمات OGC (مثل WMS وWFS وWCS) وواجهات OGC API (WFS3/OAPIF)

3. خادم التطوير QGIS Development Server: تطبيق ثنائي لخادم تطوير هو qgis_mapserver يُنفّذ مجموعة من خدمات OGC (مثل WMS وWFS وWCS) وواجهات OGC API (WFS3/OAPIF)

يركّز هذا الفصل من الدليل على الموضوع الأول، ومن خلال شرح استخدام QGIS Server API يبيّن كيف يمكن استخدام Python لتوسيع سلوك الخادم أو تحسينه أو تخصيصه، أو كيف تُستخدم QGIS Server API لتضمين خادم QGIS في تطبيق آخر.

هناك عدة طرق مختلفة يمكنك من خلالها تغيير سلوك QGIS Server أو توسيع قدراته لتقديم خدمات أو واجهات API مخصصة جديدة، وهذه هي السيناريوهات الرئيسية التي قد تواجهها:

• EMBEDDING ► استخدام QGIS Server API من تطبيق Python آخر

• STANDALONE ► تشغيل QGIS Server كخدمة WSGI/HTTP مستقلة

• FILTERS ► تحسين QGIS Server أو تخصيصه بإضافات المرشِّحات (filter plugins)

• SERVICES ► إضافة خدمة جديدة SERVICE

• OGC APIs ► إضافة واجهة OGC API جديدة

يتطلب التضمين والتطبيقات المستقلة استخدام QGIS Server Python API مباشرةً من سكربت أو تطبيق Python آخر. أما الخيارات المتبقية فهي أنسب عندما تريد إضافة ميزات مخصصة إلى تطبيق QGIS Server ثنائي قياسي (FCGI أو خادم التطوير): وفي هذه الحالة ستحتاج إلى كتابة إضافة Python لتطبيق الخادم وتسجيل المرشِّحات أو الخدمات أو واجهات API المخصصة الخاصة بك.

20.2. أساسيات Server API

الأصناف الأساسية المشاركة في تطبيق QGIS Server نموذجي هي:

• QgsServer نسخة الخادم (عادةً نسخة واحدة طوال عمر التطبيق)

• QgsServerRequest كائن الطلب (يُعاد إنشاؤه عادةً مع كل طلب)

• QgsServer.handleRequest(request, response) تعالج الطلب وتملأ الاستجابة

يمكن تلخيص سير عمل QGIS Server FCGI أو خادم التطوير على النحو الآتي:

initialize the QgsApplication
create the QgsServer
the main server loop waits forever for client requests:
    for each incoming request:
        create a QgsServerRequest request
        create a QgsServerResponse response
        call QgsServer.handleRequest(request, response)
            filter plugins may be executed
        send the output to the client

داخل الدالة QgsServer.handleRequest(request, response) تُستدعى دوال الاستدعاء الراجع (callbacks) الخاصة بإضافات المرشِّحات، ويُتاح QgsServerRequest و QgsServerResponse للإضافات عبر الصنف QgsServerInterface.

تحذير

أصناف خادم QGIS ليست آمنة للاستخدام مع الخيوط المتعددة (thread safe)، لذا يجب عليك دائمًا استخدام نموذج المعالجة المتعددة (multiprocessing) أو الحاويات عند بناء تطبيقات قابلة للتوسع مبنية على QGIS Server API.

20.3. التطبيقات المستقلة أو التضمين

في تطبيقات الخادم المستقلة أو التضمين، ستحتاج إلى استخدام أصناف الخادم المذكورة أعلاه مباشرةً، وتغليفها ضمن تنفيذ لخادم ويب يدير جميع تفاعلات بروتوكول HTTP مع العميل.

فيما يلي مثال بسيط على استخدام QGIS Server API (من دون جزء HTTP):

from qgis.core import QgsApplication
from qgis.server import *
app = QgsApplication([], False)

# Create the server instance, it may be a single one that
# is reused on multiple requests
server = QgsServer()

# Create the request by specifying the full URL and an optional body
# (for example for POST requests)
request = QgsBufferServerRequest(
    'http://localhost:8081/?MAP=/qgis-server/projects/helloworld.qgs' +
    '&SERVICE=WMS&REQUEST=GetCapabilities')

# Create a response objects
response = QgsBufferServerResponse()

# Handle the request
server.handleRequest(request, response)

print(response.headers())
print(response.body().data().decode('utf8'))

app.exitQgis()

إليك مثالًا كاملًا على تطبيق مستقل طُوِّر لاختبارات التكامل المستمر في مستودع الشيفرة المصدرية لـ QGIS، وهو يعرض مجموعة واسعة من مرشِّحات الإضافات وأنظمة المصادقة المختلفة (غير مخصص لبيئة الإنتاج لأنه طُوِّر لأغراض الاختبار فقط، لكنه يبقى مفيدًا للتعلم): qgis_wrapped_server.py

20.4. إضافات الخادم

تُحمَّل إضافات Python الخاصة بالخادم مرة واحدة عند بدء تشغيل تطبيق QGIS Server، ويمكن استخدامها لتسجيل المرشِّحات أو الخدمات أو واجهات API.

بنية إضافة الخادم مشابهة جدًا لنظيرتها في تطبيق سطح المكتب؛ إذ يُتاح للإضافات كائن من نوع QgsServerInterface، ويمكن للإضافات تسجيل مرشِّح أو خدمة أو واجهة API مخصصة أو أكثر في السجل المقابل باستخدام إحدى الدوال التي تتيحها واجهة الخادم.

20.4.1. إضافات المرشِّحات للخادم

تأتي المرشِّحات بثلاثة أنواع مختلفة، ويمكن إنشاء نسخة منها بالاشتقاق من أحد الأصناف أدناه واستدعاء الدالة المقابلة من QgsServerInterface:

نوع المرشِّح	الصنف الأساسي	التسجيل في QgsServerInterface
I/O	QgsServerFilter	registerFilter()
التحكم في الوصول	QgsAccessControlFilter	registerAccessControl()
التخزين المؤقت (Cache)	QgsServerCacheFilter	registerServerCache()

20.4.1.1. مرشِّحات الإدخال/الإخراج

يمكن لمرشِّحات الإدخال/الإخراج تعديل مدخلات الخادم ومخرجاته (الطلب والاستجابة) للخدمات الأساسية (مثل WMS وWFS)، مما يتيح إجراء أي نوع من المعالجة على سير عمل الخدمات. فمن الممكن مثلًا تقييد الوصول إلى طبقات محددة، أو حقن ورقة أنماط XSL في استجابة XML، أو إضافة علامة مائية إلى صورة WMS مُولَّدة، وهكذا.

من هذه النقطة، قد تجد من المفيد إلقاء نظرة سريعة على server plugins API docs.

يجب أن يُنفّذ كل مرشِّح واحدة على الأقل من دوال الاستدعاء الراجع الثلاث:

• onRequestReady()

• onResponseComplete()

• onSendResponse()

تملك جميع المرشِّحات وصولًا إلى كائن الطلب/الاستجابة (QgsRequestHandler)، ويمكنها التعامل مع جميع خصائصه (الإدخال/الإخراج) وإطلاق الاستثناءات (وإن كان ذلك بطريقة خاصة نوعًا ما كما سنرى أدناه).

تُعيد جميع هذه الدوال قيمة منطقية تشير إلى ما إذا كان يجب تمرير الاستدعاء إلى المرشِّحات اللاحقة. فإذا أعادت إحدى هذه الدوال False تتوقف السلسلة، وإلا فسينتقل الاستدعاء إلى المرشِّح التالي.

فيما يلي شيفرة زائفة توضّح كيف يعالج الخادم طلبًا نموذجيًا ومتى تُستدعى دوال الاستدعاء الراجع الخاصة بالمرشِّح:

for each incoming request:
    create GET/POST request handler
    pass request to an instance of QgsServerInterface
    call onRequestReady filters

    if there is not a response:
        if SERVICE is WMS/WFS/WCS:
            create WMS/WFS/WCS service
            call service’s executeRequest
                possibly call onSendResponse for each chunk of bytes
                sent to the client by a streaming services (WFS)
        call onResponseComplete
    request handler sends the response to the client

تصف الفقرات التالية دوال الاستدعاء الراجع المتاحة بالتفصيل.

20.4.1.1.1. onRequestReady

تُستدعى هذه الدالة عندما يكون الطلب جاهزًا: أي بعد تحليل عنوان URL الوارد والبيانات وقبل الدخول إلى مُبدِّل الخدمات الأساسية (مثل WMS وWFS)، وهذه هي النقطة التي يمكنك فيها التعامل مع المدخلات وتنفيذ إجراءات مثل:

• المصادقة/التفويض

• إعادة التوجيه

• إضافة معاملات معينة أو إزالتها (مثل typenames)

• إطلاق الاستثناءات

بل يمكنك استبدال خدمة أساسية بالكامل بتغيير المعامل SERVICE، وبالتالي تجاوز الخدمة الأساسية كليًا (وإن لم يكن لذلك معنى كبير).

20.4.1.1.2. onSendResponse

تُستدعى هذه الدالة كلما أُفرغ أي مخرج جزئي من مخزن الاستجابة المؤقت (أي إلى stdout الخاص بـ FCGI إذا كان خادم fcgi مستخدمًا) ومن هناك إلى العميل. ويحدث ذلك عند بث محتوى ضخم (مثل WFS GetFeature). وفي هذه الحالة قد تُستدعى onSendResponse() عدة مرات.

لاحظ أنه إذا لم تكن الاستجابة مبثوثة، فلن تُستدعى onSendResponse() إطلاقًا.

وفي جميع الأحوال، سيُرسل الجزء الأخير (أو الوحيد) إلى العميل بعد استدعاء onResponseComplete().

إعادة False ستمنع إفراغ البيانات إلى العميل. وهذا مرغوب فيه عندما تريد إضافةٌ جمع كل أجزاء الاستجابة وفحصها أو تغيير الاستجابة في onResponseComplete().

20.4.1.1.3. onResponseComplete

تُستدعى هذه الدالة مرة واحدة عندما تنهي الخدمات الأساسية (إن طُلبت) معالجتها ويصبح الطلب جاهزًا للإرسال إلى العميل. وكما ذُكر أعلاه، ستُستدعى هذه الدالة قبل إرسال الجزء الأخير (أو الوحيد) من البيانات إلى العميل. وفي خدمات البث، قد تكون onSendResponse() قد استُدعيت عدة مرات.

onResponseComplete() هي المكان المثالي لتقديم تنفيذ لخدمات جديدة (WPS أو خدمات مخصصة) وللتعامل المباشر مع المخرجات القادمة من الخدمات الأساسية (مثل إضافة علامة مائية فوق صورة WMS).

لاحظ أن إعادة False ستمنع الإضافات التالية من تنفيذ onResponseComplete()، لكنها ستمنع في كل الأحوال إرسال الاستجابة إلى العميل.

20.4.1.1.4. إطلاق الاستثناءات من إضافة

لا يزال هناك عمل ينبغي إنجازه في هذا الموضوع: يستطيع التنفيذ الحالي التمييز بين الاستثناءات المعالَجة وغير المعالَجة بتعيين خاصية في QgsRequestHandler إلى نسخة من QgsMapServiceException، وبهذه الطريقة تستطيع شيفرة C++ الرئيسية التقاط استثناءات Python المعالَجة وتجاهل الاستثناءات غير المعالَجة (أو الأفضل: تسجيلها في السجل).

يعمل هذا الأسلوب في الأساس، لكنه ليس "بأسلوب Python" تمامًا: فالأسلوب الأفضل هو إطلاق الاستثناءات من شيفرة Python ورؤيتها تتصاعد إلى حلقة C++ لتُعالَج هناك.

20.4.1.1.5. كتابة إضافة للخادم

إضافة الخادم هي إضافة Python قياسية لـ QGIS كما هو موضح في تطوير إضافات Python، لكنها توفر واجهة إضافية (أو بديلة) فحسب: فإضافة QGIS النموذجية لسطح المكتب تصل إلى تطبيق QGIS عبر نسخة QgisInterface، أما إضافة الخادم فلا تصل إلا إلى QgsServerInterface عند تنفيذها ضمن سياق تطبيق QGIS Server.

لكي يعرف QGIS Server أن الإضافة تملك واجهة خادم، يلزم إدخال بيانات وصفية خاص (في metadata.txt):

server=True

مهم

لن يُحمّل QGIS Server ولن يُنفّذ إلا الإضافات التي عُيِّنت فيها البيانات الوصفية server=True.

الإضافة المثال qgis3-server-vagrant التي نناقشها هنا (مع إضافات أخرى كثيرة) متاحة على github، كما نُشرت بعض إضافات الخادم في مستودع إضافات QGIS الرسمي.

20.4.1.1.5.1. ملفات الإضافة

إليك بنية المجلدات لإضافة الخادم المثال الخاصة بنا.

PYTHON_PLUGINS_PATH/
  HelloServer/
    __init__.py    --> *required*
    HelloServer.py  --> *required*
    metadata.txt   --> *required*

20.4.1.1.5.1.1. __init__.py

هذا الملف مطلوب لنظام الاستيراد في Python. كما يتطلب QGIS Server أن يحتوي هذا الملف على الدالة serverClassFactory()، التي تُستدعى عند تحميل الإضافة في QGIS Server عند بدء تشغيل الخادم. وتتلقى مرجعًا إلى نسخة من QgsServerInterface، ويجب أن تُعيد نسخة من صنف إضافتك. هكذا يبدو الملف __init__.py للإضافة المثال:

def serverClassFactory(serverIface):
    from .HelloServer import HelloServerServer
    return HelloServerServer(serverIface)

20.4.1.1.5.1.2. HelloServer.py

هنا يحدث السحر، وهكذا يبدو السحر: (مثلًا HelloServer.py)

تتكون إضافة الخادم عادةً من دالة استدعاء راجع واحدة أو أكثر مُغلَّفة في نسخ من QgsServerFilter.

يُنفّذ كل QgsServerFilter واحدة أو أكثر من دوال الاستدعاء الراجع التالية:

• onRequestReady()

• onResponseComplete()

• onSendResponse()

ينفّذ المثال التالي مرشِّحًا بسيطًا يطبع HelloServer! في حال كان المعامل SERVICE يساوي “HELLO”:

class HelloFilter(QgsServerFilter):

    def __init__(self, serverIface):
        super().__init__(serverIface)

    def onRequestReady(self) -> bool:
        QgsMessageLog.logMessage("HelloFilter.onRequestReady")
        return True

    def onSendResponse(self) -> bool:
        QgsMessageLog.logMessage("HelloFilter.onSendResponse")
        return True

    def onResponseComplete(self) -> bool:
        QgsMessageLog.logMessage("HelloFilter.onResponseComplete")
        request = self.serverInterface().requestHandler()
        params = request.parameterMap()
        if params.get('SERVICE', '').upper() == 'HELLO':
            request.clear()
            request.setResponseHeader('Content-type', 'text/plain')
            # Note that the content is of type "bytes"
            request.appendBody(b'HelloServer!')
        return True

يجب تسجيل المرشِّحات في serverIface كما في المثال التالي:

class HelloServerServer:
    def __init__(self, serverIface):
        serverIface.registerFilter(HelloFilter(serverIface), 100)

يحدد المعامل الثاني للدالة registerFilter() أولوية تحدد ترتيب دوال الاستدعاء الراجع التي تحمل الاسم نفسه (الأولوية الأدنى تُستدعى أولًا).

باستخدام دوال الاستدعاء الراجع الثلاث، تستطيع الإضافات التعامل مع مدخلات الخادم و/أو مخرجاته بطرق مختلفة كثيرة. وفي كل لحظة، تملك نسخة الإضافة وصولًا إلى QgsRequestHandler عبر QgsServerInterface. ويملك الصنف QgsRequestHandler الكثير من الدوال التي يمكن استخدامها لتعديل معاملات الإدخال قبل الدخول إلى المعالجة الأساسية للخادم (باستخدام requestReady()) أو بعد معالجة الطلب من قِبل الخدمات الأساسية (باستخدام sendResponse()).

تغطي الأمثلة التالية بعض حالات الاستخدام الشائعة:

20.4.1.1.5.2. تعديل المدخلات

تحتوي الإضافة المثال على مثال اختباري يغيّر معاملات الإدخال القادمة من سلسلة الاستعلام؛ ففي هذا المثال يُحقن معامل جديد في parameterMap (المحلَّلة مسبقًا)، ويصبح هذا المعامل مرئيًا للخدمات الأساسية (مثل WMS)، وفي نهاية معالجة الخدمات الأساسية نتحقق من أن المعامل لا يزال موجودًا:

class ParamsFilter(QgsServerFilter):

    def __init__(self, serverIface):
        super(ParamsFilter, self).__init__(serverIface)

    def onRequestReady(self) -> bool:
        request = self.serverInterface().requestHandler()
        params = request.parameterMap( )
        request.setParameter('TEST_NEW_PARAM', 'ParamsFilter')
        return True

    def onResponseComplete(self) -> bool:
        request = self.serverInterface().requestHandler()
        params = request.parameterMap( )
        if params.get('TEST_NEW_PARAM') == 'ParamsFilter':
            QgsMessageLog.logMessage("SUCCESS - ParamsFilter.onResponseComplete")
        else:
            QgsMessageLog.logMessage("FAIL    - ParamsFilter.onResponseComplete")
        return True

هذا مقتطف مما تراه في ملف السجل:

src/core/qgsmessagelog.cpp: 45: (logMessage) [0ms] 2014-12-12T12:39:29 plugin[0] HelloServerServer - loading filter ParamsFilter
src/core/qgsmessagelog.cpp: 45: (logMessage) [1ms] 2014-12-12T12:39:29 Server[0] Server plugin HelloServer loaded!
src/core/qgsmessagelog.cpp: 45: (logMessage) [0ms] 2014-12-12T12:39:29 Server[0] Server python plugins loaded
src/mapserver/qgshttprequesthandler.cpp: 547: (requestStringToParameterMap) [1ms] inserting pair SERVICE // HELLO into the parameter map
src/mapserver/qgsserverfilter.cpp: 42: (onRequestReady) [0ms] QgsServerFilter plugin default onRequestReady called
src/core/qgsmessagelog.cpp: 45: (logMessage) [0ms] 2014-12-12T12:39:29 plugin[0] SUCCESS - ParamsFilter.onResponseComplete

في السطر المميَّز، تشير السلسلة “SUCCESS” إلى أن الإضافة اجتازت الاختبار.

يمكن استغلال الأسلوب نفسه لاستخدام خدمة مخصصة بدلًا من خدمة أساسية: فيمكنك مثلًا تخطي طلب SERVICE من نوع WFS أو أي طلب أساسي آخر بمجرد تغيير المعامل SERVICE إلى شيء مختلف، فتُتخطّى الخدمة الأساسية. ثم يمكنك حقن نتائجك المخصصة في المخرجات وإرسالها إلى العميل (وهذا موضح أدناه).

نصيحة

إذا كنت تريد فعلًا تنفيذ خدمة مخصصة، فمن المستحسن الاشتقاق من QgsService وتسجيل خدمتك في registerFilter() باستدعاء الدالة registerService(service) الخاصة به

20.4.1.1.5.3. تعديل المخرجات أو استبدالها

يوضّح مثال مرشِّح العلامة المائية كيفية استبدال مخرجات WMS بصورة جديدة ناتجة عن إضافة صورة علامة مائية فوق صورة WMS التي أنشأتها خدمة WMS الأساسية:

from qgis.server import *
from qgis.PyQt.QtCore import *
from qgis.PyQt.QtGui import *

class WatermarkFilter(QgsServerFilter):

    def __init__(self, serverIface):
        super().__init__(serverIface)

    def onResponseComplete(self) -> bool:
        request = self.serverInterface().requestHandler()
        params = request.parameterMap( )
        # Do some checks
        if (params.get('SERVICE').upper() == 'WMS' \
                and params.get('REQUEST').upper() == 'GETMAP' \
                and not request.exceptionRaised() ):
            QgsMessageLog.logMessage("WatermarkFilter.onResponseComplete: image ready %s" % request.parameter("FORMAT"))
            # Get the image
            img = QImage()
            img.loadFromData(request.body())
            # Adds the watermark
            watermark = QImage(os.path.join(os.path.dirname(__file__), 'media/watermark.png'))
            p = QPainter(img)
            p.drawImage(QRect( 20, 20, 40, 40), watermark)
            p.end()
            ba = QByteArray()
            buffer = QBuffer(ba)
            buffer.open(QIODevice.WriteOnly)
            img.save(buffer, "PNG" if "png" in request.parameter("FORMAT") else "JPG")
            # Set the body
            request.clearBody()
            request.appendBody(ba)
        return True

في هذا المثال تُفحص قيمة المعامل SERVICE، فإذا كان الطلب الوارد من نوع WMS GETMAP ولم تُعيَّن أي استثناءات من قِبل إضافة نُفِّذت سابقًا أو من قِبل الخدمة الأساسية (WMS في هذه الحالة)، تُسترجع الصورة التي أنشأتها WMS من مخزن المخرجات المؤقت وتُضاف إليها صورة العلامة المائية. والخطوة الأخيرة هي مسح مخزن المخرجات المؤقت واستبداله بالصورة المُنشأة حديثًا. لاحظ أنه في الحالات الواقعية ينبغي أيضًا التحقق من نوع الصورة المطلوب بدلًا من دعم PNG أو JPG فقط.

20.4.1.2. مرشِّحات التحكم في الوصول

تمنح مرشِّحات التحكم في الوصول المطوّرَ تحكمًا دقيقًا في الطبقات والمعالم والبيانات الوصفية التي يمكن الوصول إليها، ويمكن تنفيذ دوال الاستدعاء الراجع التالية في مرشِّح التحكم في الوصول:

• layerFilterExpression(layer)

• layerFilterSubsetString(layer)

• layerPermissions(layer)

• authorizedLayerAttributes(layer, attributes)

• allowToEdit(layer, feature)

• cacheKey()

20.4.1.2.1. ملفات الإضافة

إليك بنية المجلدات للإضافة المثال الخاصة بنا:

PYTHON_PLUGINS_PATH/
  MyAccessControl/
    __init__.py    --> *required*
    AccessControl.py  --> *required*
    metadata.txt   --> *required*

20.4.1.2.1.1. __init__.py

هذا الملف مطلوب لنظام الاستيراد في Python. وكما هو الحال في جميع إضافات خادم QGIS، يحتوي هذا الملف على الدالة serverClassFactory()، التي تُستدعى عند تحميل الإضافة في QGIS Server عند بدء التشغيل. وتتلقى مرجعًا إلى نسخة من QgsServerInterface، ويجب أن تُعيد نسخة من صنف إضافتك. هكذا يبدو الملف __init__.py للإضافة المثال:

def serverClassFactory(serverIface):
    from MyAccessControl.AccessControl import AccessControlServer
    return AccessControlServer(serverIface)

20.4.1.2.1.2. AccessControl.py

class AccessControlFilter(QgsAccessControlFilter):

    def __init__(self, server_iface):
        super().__init__(server_iface)

    def layerFilterExpression(self, layer):
        """ Return an additional expression filter """
        return super().layerFilterExpression(layer)

    def layerFilterSubsetString(self, layer):
        """ Return an additional subset string (typically SQL) filter """
        return super().layerFilterSubsetString(layer)

    def layerPermissions(self, layer):
        """ Return the layer rights """
        return super().layerPermissions(layer)

    def authorizedLayerAttributes(self, layer, attributes):
        """ Return the authorised layer attributes """
        return super().authorizedLayerAttributes(layer, attributes)

    def allowToEdit(self, layer, feature):
        """ Are we authorised to modify the following geometry """
        return super().allowToEdit(layer, feature)

    def cacheKey(self):
        return super().cacheKey()

class AccessControlServer:

   def __init__(self, serverIface):
      """ Register AccessControlFilter """
      serverIface.registerAccessControl(AccessControlFilter(serverIface), 100)

يمنح هذا المثال وصولًا كاملًا للجميع.

من مهام الإضافة أن تعرف من الذي سجّل الدخول.

في جميع هذه الدوال، نتلقى الطبقة كوسيط لنتمكن من تخصيص القيود لكل طبقة.

20.4.1.2.2. layerFilterExpression

تُستخدم لإضافة تعبير لتقييد النتائج.

على سبيل المثال، لتقييد النتائج بالمعالم التي تساوي فيها السمة role القيمة user.

def layerFilterExpression(self, layer):
    return "$role = 'user'"

20.4.1.2.3. layerFilterSubsetString

مثل السابقة لكنها تستخدم SubsetString (التي تُنفَّذ في قاعدة البيانات)

على سبيل المثال، لتقييد النتائج بالمعالم التي تساوي فيها السمة role القيمة user.

def layerFilterSubsetString(self, layer):
    return "role = 'user'"

20.4.1.2.4. layerPermissions

تقييد الوصول إلى الطبقة.

تُعيد كائنًا من نوع LayerPermissions()، يملك الخصائص التالية:

• canRead لرؤيتها في GetCapabilities والحصول على صلاحية القراءة.

• canInsert للتمكن من إدراج معلم جديد.

• canUpdate للتمكن من تحديث معلم.

• canDelete للتمكن من حذف معلم.

على سبيل المثال، لقصر كل شيء على صلاحية القراءة فقط:

def layerPermissions(self, layer):
    rights = QgsAccessControlFilter.LayerPermissions()
    rights.canRead = True
    rights.canInsert = rights.canUpdate = rights.canDelete = False
    return rights

20.4.1.2.5. authorizedLayerAttributes

تُستخدم لتقييد ظهور مجموعة فرعية محددة من البيانات الوصفية.

يُعيد الوسيط attribute المجموعة الحالية من البيانات الوصفية الظاهرة.

على سبيل المثال، لإخفاء السمة role:

def authorizedLayerAttributes(self, layer, attributes):
    return [a for a in attributes if a != "role"]

20.4.1.2.6. allowToEdit

تُستخدم لتقييد التحرير على مجموعة فرعية من المعالم.

تُستخدم في بروتوكول WFS-Transaction.

على سبيل المثال، للتمكن من تحرير المعالم التي تحمل فيها السمة role القيمة user فقط:

def allowToEdit(self, layer, feature):
    return feature.attribute('role') == 'user'

20.4.1.2.7. cacheKey

يحتفظ QGIS Server بذاكرة تخزين مؤقت للقدرات (capabilities)، لذا للحصول على ذاكرة تخزين مؤقت لكل دور يمكنك إعادة الدور في هذه الدالة. أو أعِد None لتعطيل التخزين المؤقت تمامًا.

20.4.2. الخدمات المخصصة

في QGIS Server، تُنفَّذ الخدمات الأساسية مثل WMS وWFS وWCS كأصناف فرعية من QgsService.

لتنفيذ خدمة جديدة تُنفَّذ عندما يطابق معامل سلسلة الاستعلام SERVICE اسم الخدمة، يمكنك تنفيذ QgsService خاص بك وتسجيل خدمتك في serviceRegistry() باستدعاء الدالة registerService(service) الخاصة به.

إليك مثالًا على خدمة مخصصة باسم CUSTOM:

from qgis.server import QgsService
from qgis.core import QgsMessageLog

class CustomServiceService(QgsService):

    def __init__(self):
        QgsService.__init__(self)

    def name(self):
        return "CUSTOM"

    def version(self):
        return "1.0.0"

    def executeRequest(self, request, response, project):
        response.setStatusCode(200)
        QgsMessageLog.logMessage('Custom service executeRequest')
        response.write("Custom service executeRequest")


class CustomService():

    def __init__(self, serverIface):
        serverIface.serviceRegistry().registerService(CustomServiceService())

20.4.3. واجهات API المخصصة

في QGIS Server، تُنفَّذ واجهات OGC API الأساسية مثل OAPIF (المعروفة أيضًا باسم WFS3) كمجموعات من الأصناف الفرعية لـ QgsServerOgcApiHandler المسجلة في نسخة من QgsServerOgcApi (أو صنفها الأب QgsServerApi).

لتنفيذ واجهة API جديدة تُنفَّذ عندما يطابق مسار URL عنوانًا معينًا، يمكنك تنفيذ نسخ QgsServerOgcApiHandler خاصة بك، وإضافتها إلى QgsServerOgcApi، ثم تسجيل الواجهة في serviceRegistry() باستدعاء الدالة registerApi(api) الخاصة به.

إليك مثالًا على واجهة API مخصصة تُنفَّذ عندما يحتوي عنوان URL على /customapi:

import json
import os

from qgis.PyQt.QtCore import QBuffer, QIODevice, QTextStream, QRegularExpression
from qgis.server import (
    QgsServiceRegistry,
    QgsService,
    QgsServerFilter,
    QgsServerOgcApi,
    QgsServerQueryStringParameter,
    QgsServerOgcApiHandler,
)

from qgis.core import (
    QgsMessageLog,
    QgsJsonExporter,
    QgsCircle,
    QgsFeature,
    QgsPoint,
    QgsGeometry,
)


class CustomApiHandler(QgsServerOgcApiHandler):

    def __init__(self):
        super(CustomApiHandler, self).__init__()
        self.setContentTypes([QgsServerOgcApi.HTML, QgsServerOgcApi.JSON])

    def path(self):
        return QRegularExpression("/customapi")

    def operationId(self):
        return "CustomApiXYCircle"

    def summary(self):
        return "Creates a circle around a point"

    def description(self):
        return "Creates a circle around a point"

    def linkTitle(self):
        return "Custom Api XY Circle"

    def linkType(self):
        return QgsServerOgcApi.data

    def handleRequest(self, context):
        """Simple Circle"""

        values = self.values(context)
        x = values['x']
        y = values['y']
        r = values['r']
        f = QgsFeature()
        f.setAttributes([x, y, r])
        f.setGeometry(QgsCircle(QgsPoint(x, y), r).toCircularString())
        exporter = QgsJsonExporter()
        self.write(json.loads(exporter.exportFeature(f)), context)

    def templatePath(self, context):
        # The template path is used to serve HTML content
        return os.path.join(os.path.dirname(__file__), 'circle.html')

    def parameters(self, context):
        return [QgsServerQueryStringParameter('x', True, QgsServerQueryStringParameter.Type.Double, 'X coordinate'),
                QgsServerQueryStringParameter(
                    'y', True, QgsServerQueryStringParameter.Type.Double, 'Y coordinate'),
                QgsServerQueryStringParameter('r', True, QgsServerQueryStringParameter.Type.Double, 'radius')]


class CustomApi():

    def __init__(self, serverIface):
        api = QgsServerOgcApi(serverIface, '/customapi',
                            'custom api', 'a custom api', '1.1')
        handler = CustomApiHandler()
        api.registerHandler(handler)
        serverIface.serviceRegistry().registerApi(api)