3.6. واجهة OGC API Features

OGC API Features (OAPIF) هو أول تطبيق للجيل الجديد من بروتوكولات OGC، وهو موصوف في المستند OGC API - Features - Part 1: Core.

يمكن الوصول إلى الواجهة البرمجية في التثبيتات المعتادة عبر http://localhost/qgisserver/wfs3.

فيما يلي ملخص سريع غير رسمي لأهم الفروق بين بروتوكول WFS المعروف و OAPIF:

  • يعتمد OAPIF على واجهة برمجية REST

  • يجب أن يتبع OAPIF مواصفات OPENAPI

  • يدعم OAPIF صيغ مخرجات متعددة لكنه لا يفرض أيًا منها (المتاح حاليًا في OAPIF الخاص بـ QGIS هو GeoJSON و HTML فقط)، ويستخدم التفاوض على المحتوى لتحديد الصيغة التي تُقدَّم للعميل

  • تحظى JSON و HTML بدعم من الدرجة الأولى في OAPIF

  • OAPIF ذاتي التوثيق (عبر نقطة النهاية /api)

  • OAPIF قابل للتنقل والتصفح بالكامل (عبر الروابط)

مهم

رغم أن تطبيق OGC API Features في QGIS يمكنه استخدام المعامل MAP لتحديد ملف المشروع، فإن مواصفات OPENAPI لا تسمح بأي معاملات استعلام إضافية. لهذا يُوصى بشدة بعدم إظهار MAP في عنوان URL، وتحديد ملف المشروع في البيئة بوسائل أخرى (مثلًا بضبط QGIS_PROJECT_FILE في البيئة عبر قاعدة إعادة كتابة في خادم الويب).

ملاحظة

توفر نقطة النهاية API توثيقًا شاملًا لجميع المعاملات المدعومة وصيغ المخرجات في خدمتك. ستصف الفقرات التالية أهمها فقط.

3.6.1. تمثيل الموارد

يدعم تطبيق OGC API Features في QGIS Server حاليًا صيغ تمثيل الموارد (المخرجات) التالية:

  • HTML

  • JSON

تعتمد الصيغة المقدَّمة فعليًا على التفاوض على المحتوى، لكن يمكن طلب صيغة محددة صراحةً بإلحاق محدِّد الصيغة بنقاط النهاية.

امتدادات محدِّدات الصيغة المدعومة هي:

  • .json

  • .html

قد تعرِّف نقاط نهاية معينة أسماء بديلة إضافية لمحدِّدات الصيغة:

  • .openapi: اسم بديل لـ .json تدعمه نقطة النهاية API

  • .geojson: اسم بديل لـ .json تدعمه نقطتا النهاية Features و Feature

3.6.2. نقاط النهاية

توفر الواجهة البرمجية قائمة بنقاط النهاية التي يمكن للعملاء استرجاعها. صُمم النظام بحيث توفر كل استجابة مجموعة من الروابط للتنقل بين جميع الموارد المتاحة.

نقاط النهاية التي يوفرها تطبيق QGIS هي:

اﻷسم

المسار

وصف

الصفحة الرئيسية (Landing Page)

/

معلومات عامة عن الخدمة، وروابط إلى جميع نقاط النهاية المتاحة

المطابقة (Conformance)

/conformance

معلومات عن مدى مطابقة الخدمة للمعايير

API

/api

وصف كامل لنقاط النهاية التي توفرها الخدمة ولبنية المستندات المُرجَعة

المجموعات (Collections)

/collections

قائمة بجميع المجموعات (أي الطبقات المتجهية) التي توفرها الخدمة

المجموعة (Collection)

/collections/{collectionId}

معلومات عن مجموعة (الاسم، البيانات الوصفية، الامتداد، إلخ)

المعالم (Features)

/collections/{collectionId}/items

قائمة المعالم التي توفرها المجموعة

المعلم (Feature)

/collections/{collectionId}/items/{featureId}

معلومات عن معلم واحد

على غرار WFS-T (خدمة المعالم على الويب التبادلية)، يمكن إضافة المعالم وتحديثها وحذفها (CRUD). الطلبات المعنية موصوفة في "/api".

الصفحة الرئيسية (Landing Page)

نقطة النهاية الرئيسية هي Landing Page. ومن هذه الصفحة يمكن التنقل إلى جميع نقاط نهاية الخدمة المتاحة. يجب أن توفر Landing Page روابط إلى

  • تعريف الواجهة البرمجية (المسار /api وعلاقتا الرابط service-desc و service-doc)،

  • إعلان المطابقة (المسار /conformance، وعلاقة الرابط conformance)، و

  • المجموعات (المسار /collections، وعلاقة الرابط data).

../../../_images/server_wfs3_landing_page.png

شكل 3.25 الصفحة الرئيسية لخدمة OAPIF على الخادم

تعريف الواجهة البرمجية

API Definition وصف متوافق مع OPENAPI للواجهة البرمجية التي توفرها الخدمة. وفي تمثيلها بصيغة HTML تكون صفحة قابلة للتصفح تُسرد فيها جميع نقاط النهاية وصيغ استجاباتها وتوثَّق بدقة. مسار نقطة النهاية هذه هو /api.

يوفر تعريف الواجهة البرمجية توثيقًا شاملًا وموثوقًا للخدمة، بما في ذلك جميع المعاملات المدعومة والصيغ المُرجَعة.

ملاحظة

نقطة النهاية هذه مناظرة لـ GetCapabilities في WFS

قائمة المجموعات

توفر نقطة نهاية المجموعات قائمة بجميع المجموعات المتاحة في الخدمة. وبما أن الخدمة "تقدّم" مشروع QGIS واحدًا، فإن المجموعات هي الطبقات المتجهية في المشروع الحالي (إذا نُشرت بصيغة WFS في خصائص المشروع). مسار نقطة النهاية هذه هو /collections/.

../../../_images/server_wfs3_collections.png

شكل 3.26 صفحة قائمة المجموعات لخدمة OAPIF على الخادم

تفاصيل المجموعة

بينما لا توفر نقطة نهاية المجموعات معلومات تفصيلية عن كل مجموعة متاحة، فإن هذه المعلومات متاحة في نقاط النهاية /collections/{collectionId}. وتشمل المعلومات المعتادة الامتداد والوصف وأنظمة الإحداثيات المرجعية وبيانات وصفية أخرى.

يوفر تمثيل HTML أيضًا خريطة قابلة للتصفح تعرض المعالم المتاحة.

../../../_images/server_wfs3_collection.png

شكل 3.27 صفحة تفاصيل المجموعة لخدمة OAPIF على الخادم

قائمة المعالم

توفر نقطة النهاية هذه قائمة بجميع المعالم في مجموعة بمعرفة معرّف المجموعة. مسار نقطة النهاية هذه هو /collections/{collectionId}/items.

يوفر تمثيل HTML أيضًا خريطة قابلة للتصفح تعرض المعالم المتاحة.

ملاحظة

نقطة النهاية هذه مناظرة لـ GetFeature في WFS 1 و WFS 2.

../../../_images/server_wfs3_features.png

شكل 3.28 صفحة قائمة المعالم لخدمة OAPIF على الخادم

تفاصيل المعلم

توفر نقطة النهاية هذه جميع المعلومات المتاحة عن معلم واحد، بما في ذلك سمات المعلم وشكله الهندسي. مسار نقطة النهاية هذه هو /collections/{collectionId}/items/{itemId}.

يوفر تمثيل HTML أيضًا خريطة قابلة للتصفح تعرض الشكل الهندسي للمعلم.

../../../_images/server_wfs3_feature.png

شكل 3.29 صفحة تفاصيل المعلم لخدمة OAPIF على الخادم

3.6.3. ترقيم الصفحات

يُنفَّذ ترقيم صفحات قائمة طويلة من المعالم في OGC API عبر الرابطين next و prev، ويبني QGIS Server هذين الرابطين بإلحاق limit و offset كمعاملات في سلسلة الاستعلام.

مثال على عنوان URL:

http://localhost/qgisserver/wfs3/collection_one/items.json?offset=10&limit=10

ملاحظة

يمكن ضبط القيمة القصوى المقبولة لـ limit عبر إعداد الخادم QGIS_SERVER_API_WFS3_MAX_LIMIT (انظر: متغيرات البيئة).

3.6.4. تصفية المعالم

يمكن تصفية المعالم المتاحة في مجموعة أو البحث فيها بتحديد مرشِّح واحد أو أكثر.

مرشِّح التاريخ والوقت

يمكن تصفية المجموعات التي تحتوي على سمات تاريخ و/أو تاريخ ووقت بتحديد الوسيط datetime في سلسلة الاستعلام. افتراضيًا يُستخدم أول حقل تاريخ/تاريخ ووقت للتصفية. ويمكن تغيير هذا السلوك بضبط بُعد "Date" أو "Time" في القسم QGIS Server ► Dimension من نافذة حوار خصائص الطبقة.

صيغة تصفية التاريخ والوقت موصوفة بالكامل في تعريف الواجهة البرمجية، وهي تدعم النطاقات (مع تضمين قيمتي البداية والنهاية) إضافة إلى القيم المفردة.

أمثلة على عناوين URL:

يُرجع فقط المعالم التي يطابق بُعدها التاريخي 2019-01-01

http://localhost/qgisserver/wfs3/collection_one/items.json?datetime=2019-01-01

يُرجع فقط المعالم التي يطابق بُعد التاريخ والوقت فيها 2019-01-01T01:01:01

http://localhost/qgisserver/wfs3/collection_one/items.json?datetime=2019-01-01T01:01:01

يُرجع فقط المعالم التي يقع بُعد التاريخ والوقت فيها ضمن النطاق 2019-01-01T01:01:01 - 2019-01-01T12:00:00

http://localhost/qgisserver/wfs3/collection_one/items.json?datetime=2019-01-01T01:01:01/2019-01-01T12:00:00

مرشِّح المستطيل المحيط

يمكن تحديد مرشِّح مكاني بالمستطيل المحيط باستخدام المعامل bbox:

ترتيب العناصر المفصولة بفواصل هو:

  • الزاوية السفلية اليسرى، خط الطول وفق WGS 84

  • الزاوية السفلية اليسرى، دائرة العرض وفق WGS 84

  • الزاوية العلوية اليمنى، خط الطول وفق WGS 84

  • الزاوية العلوية اليمنى، دائرة العرض وفق WGS 84

ملاحظة

تسمح مواصفات OGC أيضًا بمحدِّد bbox من 6 عناصر يكون فيه العنصران الثالث والسادس مكوِّنَي Z، وهذا غير مدعوم بعدُ في QGIS Server.

مثال على عنوان URL:

http://localhost/qgisserver/wfs3/collection_one/items.json?bbox=-180,-90,180,90

إذا لم يكن نظام الإحداثيات المرجعي للمستطيل المحيط هو WGS 84، فيمكن تحديد نظام آخر باستخدام المعامل الاختياري bbox-crs. ويجب أن يكون معرّف صيغة نظام الإحداثيات بصيغة OGC URI:

مثال على عنوان URL:

http://localhost/qgisserver/wfs3/collection_one/items.json?bbox=913191,5606014,913234,5606029&bbox-crs=http://www.opengis.net/def/crs/EPSG/9.6.2/3857

مرشِّحات السمات

يمكن دمج مرشِّحات السمات مع مرشِّح المستطيل المحيط، وصيغتها العامة: <attribute name>=<attribute value>. ويمكن دمج عدة مرشِّحات باستخدام المعامل AND.

مثال على عنوان URL:

يرشّح جميع المعالم التي تساوي فيها السمة name القيمة "my value"

http://localhost/qgisserver/wfs3/collection_one/items.json?attribute_one=my%20value

المطابقات الجزئية مدعومة أيضًا باستخدام المعامل * ("النجمة"):

مثال على عنوان URL:

يرشّح جميع المعالم التي تنتهي فيها قيمة السمة name بـ "value"

http://localhost/qgisserver/wfs3/collection_one/items.json?attribute_one=*value

3.6.5. ترتيب المعالم

يمكن ترتيب مجموعة النتائج حسب قيمة حقل باستخدام معامل الاستعلام sortby.

تُرتَّب النتائج تصاعديًا افتراضيًا. ولترتيبها تنازليًا يمكن ضبط علَم منطقي (sortdesc):

http://localhost/qgisserver/wfs3/collection_one/items.json?sortby=name&sortdesc=1

3.6.6. تحديد السمات

يمكن تقييد سمات المعالم التي يُرجعها استدعاء قائمة المعالم بإضافة قائمة بأسماء السمات مفصولة بفواصل في وسيط سلسلة الاستعلام الاختياري properties.

مثال على عنوان URL:

يُرجع السمة name فقط

http://localhost/qgisserver/wfs3/collection_one/items.json?properties=name

3.6.7. تخصيص صفحات HTML

يستخدم تمثيل HTML مجموعة من قوالب HTML لتوليد الاستجابة. يُحلَّل القالب بواسطة محرك قوالب يسمى inja. ويمكن تخصيص القوالب بتجاوزها (انظر: تجاوز القوالب). يصل القالب إلى البيانات نفسها المتاحة لتمثيل JSON، وتتوفر له بضع دوال إضافية:

دوال القوالب المخصصة

  • escape( string ): تهرّب أقواس الزاوية في وسوم XHTML

  • path_append( path ): تُلحق مسار مجلد بعنوان URL الحالي

  • path_chomp( n ): تحذف العدد المحدد "n" من مكونات المجلدات من مسار عنوان URL الحالي

  • json_dump( ): تطبع بيانات JSON الممررة إلى القالب

  • static( path ): تُرجع عنوان URL الكامل للمسار الثابت المحدد. على سبيل المثال: "static( "/style/black.css" )" مع المسار الجذر "http://localhost/qgisserver/wfs3" ستُرجع "http://localhost/qgisserver/wfs3/static/style/black.css".

  • links_filter( links, key, value ): تُرجع الروابط المرشَّحة من قائمة روابط

  • content_type_name( content_type ): تُرجع اسمًا مختصرًا لنوع المحتوى، فمثلًا "text/html" تُرجع "HTML"

  • nl2br( text ): تُرجع النص المُدخل بعد استبدال جميع أسطره الجديدة بوسوم "<br>"

  • starts_with( string, prefix ): تُرجع true إذا بدأت السلسلة بالبادئة المحددة، و false خلاف ذلك

تجاوز القوالب

تُخزَّن القوالب والملفات الثابتة في مجلدات فرعية من مجلد موارد الواجهة البرمجية الافتراضي في QGIS Server (/usr/share/qgis/resources/server/api/ على نظام Linux)، ويمكن تخصيص المجلد الأساسي بتغيير متغير البيئة QGIS_SERVER_API_RESOURCES_DIRECTORY.

يكون لتثبيت Linux نموذجي شجرة المجلدات التالية:

/usr/share/qgis/resources/server/api/
└── ogc
    ├── schema.json
    ├── static
    │   ├── jsonFormatter.min.css
    │   ├── jsonFormatter.min.js
    │   └── style.css
    └── templates
        └── wfs3
            ├── describeCollection.html
            ├── describeCollections.html
            ├── footer.html
            ├── getApiDescription.html
            ├── getFeature.html
            ├── getFeatures.html
            ├── getLandingPage.html
            ├── getRequirementClasses.html
            ├── header.html
            ├── leaflet_map.html
            └── links.html

لتجاوز القوالب، يمكنك نسخ الشجرة كاملة إلى موقع آخر وتوجيه QGIS_SERVER_API_RESOURCES_DIRECTORY إلى الموقع الجديد.