Svarbu

Vertimas yra bendruomenės pastangos, prie kurių jūs galite prisijungti. Šis puslapis šiuo metu išverstas 100.00%.

3.6. OGC API Features (Geoobjektai)

OGC API Features (OAPIF) yra pirmas naujos OGC protokolų kartos įgyvendinimas. Jį aprašo dokumentas OGC API - Geoobjektai - 1 dalis: Pagrindas.

Tipiniuose diegimuose šį API galima pasiekti adresu http://localhost/qgisserver/wfs3.

Čia yra greitas neformalus svarbiausių skirtumų tarp gerai žinomo WFS protokolo ir OAPIF apibendrinimas:

OAPIF remiasi REST API
OAPIF turi atitikti OPENAPI specifikacijas
OAPIF palaiko kelis išvesties formatus, bet nei vieno iš jų nediktuoja (QGIS OAPIF šiuo metu teikia tik GeoJSON ir HTML) ir naudoja turinio derybas, kad nustatytų, kurį formatą pateikti klientui
Pirmos klasės OAPIF piliečiai yra JSON ir HTML
OAPIF yra save-aprašantis (per prieigos tašką /api)
OAPIF yra pilnai naviguojamas (per nuorodas) ir naršomas

Svarbu

Nors QGIS OGC API Geoobjektų įgyvendinimas leidžia naudoti MAP parametrą nurodant projekto failą, jokie papildomi parametrai neleidžiami pagal OPENAPI specifikaciją. Dėl šios priežasties stipriai rekomenduojama, kad MAP nebūtų išleidžiamas į URL ir projekto failas nurodomas aplinkoje kitomis priemonėmis (pvz. nustatant aplinkoje QGIS_PROJECT_FILE žiniatinklio serverio perrašymo taisyklių pagalba).

Pastaba

API prieigos taškas teikia visų jūsų paslaugos palaikomų parametrų ir išvesties formatų pilną dokumentaciją. Žemiau pateikiamose pastraipose bus aprašome tik patys svarbiausi.

3.6.1. Resursų reprezentacija

QGIS Serverio OGC API Features įgyvendinimas šiuo metu palaiko šiuos resursų reprezentacijos (pateikties) formatus:

HTML
JSON

Realiai pateikiamas formatas priklauso nuo turinio derybų, bet galima paprašyti konkretaus formato prieigos taškui perduodant formato specifikaciją.

Palaikomi formatų plėtiniai yra:

.json
.html

Papildomi formatų specifikavimo pseudonimai gali būti apibrėžti konkretiems prieigos taškams:

.openapi: .json pseudonimas palaikomas API prieigos taške
.geojson: .json pseudonimas palaikomas Features ir Feature prieigos taškuose

3.6.2. Prieigos taškai

API teikia sąrašą prieigos taškų, kuriuos klientai gali gauti. Sistema sukurta tokiu būdu, kad kiekvienas atsakas teikia aibę nuorodų, leidžiančių naviguoti per visus teikiamus resursus.

QGIS įgyvendinimo teikiami prieigos taškai yra:

Pavadinimas	Kelias	Aprašymas
Pradinis puslapis	`/`	Bendra informacija apie paslaugą, kurioje teikiamos nuorodos į visus prieigos taškus
Atitikimas	`/conformance`	Informacija apie paslaugos atitikimą standartams
API	`/api`	Pilnas paslaugos teikiamų prieigos taškų aprašymas ir grąžinamų duomenų struktūra
Rinkiniai	`/collections`	Sąrašas visų paslaugos teikiamų rinkinių (pvz. „vektorinių sluoksnių“)
Rinkinys	`/collections/{collectionId}`	Informacija apie rinkinį (pavadinimas, metaduomenys, apimtis ir pan.)
Savybės	`/collections/{collectionId}/items`	Sąrašas rinkinio teikiamų geoobjektų
Geoobjektas	`/collections/{collectionId}/items/{featureId}`	Informacija apie vieną geoobjektą

Kaip ir WFS-T (transakcinio žiniatinklio geoobjektų paslaugos) atveju, galima pridėti, pakeisti ir trinti geoobjektus (CRUD). Atitinkamos užklausos aprašomos „/api“.

Pradinis puslapis

Pagrindinis prieigos taškas yra Pradinis puslapis. Iš šio puslapio galima patekti į visus prieinamus paslaugos prieigos taškus. Pradinis puslapis privalo teikti nuorodas į:

API apibrėžimą (kelias /api nuorodos service-desc ir service-doc),
atitikimo deklaracija (kelias /conformance, nuoroda conformance), ir
rinkiniai (kelias /collections, nuoroda data).

../../../_images/server_wfs3_landing_page.png — Fig. 3.25 Serverio OAPIF pradinis puslapis

API apibrėžimas

API apibrėžimas yra su OPENAPI suderinamas API apibrėžimas, kurį teikia paslauga. Jo HTML reprezentacijoje tai naršomas puslapis, kuriame yra visi prieigos taškai, kur jų atsakymų formatai aiškiai išvardinti ir dokumentuoti. Šio prieigos taško kelias yra /api.

API apibrėžimas teikia išsamią ir autoritetingą paslaugos dokumentaciją, įskaitant visus palaikomus parametrus ir grąžinamus formatus.

Pastaba

Šis prieigos taškas yra analogiškas WFS GetCapabilities

Rinkinių sąrašas

Rinkinių prieigos taškai teikia sąrašą visų paslaugoje prieinamų rinkinių. Kadangi paslauga „teikia“ vieną QGIS projektą, rinkiniai yra dabartinio projekto vektoriniai sluoksniai (jei jie publikuojami kaip WFS projekto savybėse). Šio prieigos taško kelias yra /collections/.

../../../_images/server_wfs3_collections.png — Fig. 3.26 Serverio OAPIF rinkinių sąrašo puslapis

Rinkinio detalės

Nors rinkinių prieigos taškas ir neteikia detalios informacijos apie kiekvieną rinkinį, tokią informaciją galite rasti prieigos taškuose /collections/{rinkinioId}. Tipinėje informacijoje bus apimtis, aprašymas, CRS ir kiti metaduomenys.

HTML pateiktyje taipogi yra naršomas žemėlapis su galimais geoobjektais.

../../../_images/server_wfs3_collection.png — Fig. 3.27 Serverio OAPIF rinkinio detalių puslapis

Geoobjektų sąrašas

Šis prieigos taškas pagal rinkinio ID teikia visų rinkinio geoobjektų sąrašą. Šio prieigos taško kelias yra /collections/{rinkinioId}/items.

HTML pateiktyje taipogi yra naršomas žemėlapis su galimais geoobjektais.

Pastaba

Šis prieigos taškas yra analogiškas WFS 1 ir WFS 2 metodui GetFeature.

../../../_images/server_wfs3_features.png — Fig. 3.28 Serverio OAPIF geoobjektų sąrašo puslapis

Geoobjekto detalės

Šis prieigos taškas teikia visą turimą informaciją apie vieną geoobjektą, įskaitant geoobjekto atributus ir jo geometriją. Šios prieigos taško adresas yra /collections/{rinkinioId}/items/{elementoId}.

HTML pateiktyje taipogi yra naršomas žemėlapis su geoobjekto geometrija.

../../../_images/server_wfs3_feature.png — Fig. 3.29 Serverio OAPIF geoobjekto detalių puslapis

3.6.3. Puslapiavimas

Ilgo geoobjektų sąrašo puslapiavimas OGC API įgyvendintas per nuorodas kitas ir ankstesnis, QGIS serveris sukuria šias nuorodas pridedant limit ir offset kaip užklausos teksto parametrus.

URL pavyzdys:

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

Pastaba

Maksimalią leidžiamą limit reikšmę galima konfigūruoti naudojant serverio konfigūracijos nustatymą QGIS_SERVER_API_WFS3_MAX_LIMIT (žr.: Environment variables).

3.6.4. Geoobjektų filtravimas

Rinkinyje esančius geoobjektus galima filtruoti ir jų ieškoti nurodant vieną ar daugiau filtrų.

Datos ir laiko filtro

Rinkinius su datos ir/ar datos ir laiko atributais galima filtruoti nurodant datetime argumentą užklausos eilutėje. Pagal nutylėjimą pirmas datos/datoslaiko laukas naudojamas filtravimui. Šią elgseną galima konfigūruoti nustatant „Datos“ ar „Laiko“ dimensiją sluoksnio savybių dialogo skiltyje QGIS Serveris ► Dimensija.

Datos ir laiko filtravimo sintaksė pilnai aprašyta skyriuje API apibrėžimas ir taipogi be atskirų reikšmių palaiko diapazonus (įskaitant pradžios ir pabaigos reikšmes).

URL pavyzdžiai:

Grąžina tik geoobjektus, kurių datos dimensija atitinka 2019-01-01

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

Grąžina tik geoobjektus, kurių datos ir laiko dimensija atitinka 2019-01-01T01:01:01

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

Grąžina tik geoobjektus, kurių datos ir laiko dimensija patenka į diapazoną 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

Apimties stačiakampio filtras

Apimties stačiakampio erdvinį filtrą galima nurodyti su parametru bbox:

Kableliais atskirtų elementų rikiuotė yra:

Apatinis kairys kampas, WGS 84 ilguma
Apatinis dešinys kampas, WGS 84 platuma
Viršutinis dešinys kampas, WGS 84 ilguma
Viršutinis dešinys kampas, WGS 84 platuma

Pastaba

OGC specifikacija taipogi leidžia 6 elementų apimties stačiakampio nurodymą, kur trečias ir šeštas elementai yra Z komponentai, šito QGIS serveris dar nepalaiko.

URL pavyzdys:

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

Jei apimties stačiakampio CRS yra ne WGS 84, galima nurodyti kitą CRS naudojant neprivalomą parametrą bbox-crs. CRS formato identifikatorius turi būti OGC URI formato:

URL pavyzdys:

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

3.6.5. Geoobjektų rikiavimas

Galima rikiuoti rezultato aibę pagal lauko reikšmę naudojant užklausos parametrą sortby.

Rezultatai pagal nutylėjimą rikiuojami didėjančia tvarka. Norėdami rikiuoti rezultatus mažėjančiai, galite nurodyti loginę žymą (sortdesc):

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

3.6.6. Atributų parinkimas

Geoobjektų atributus, kuriuos grąžina Geoobjektų sąrašas kvietimas, galima riboti pridedant kableliais atskirtų atributų sąrašą neprivalomame užklausos teksto argumente properties.

URL pavyzdys:

grąžina tik atributą name

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

3.6.7. Tinkinti HTML puslapius

HTML reprezentacija kuriant atsaką naudoja aibę HTML šablonų. Šablonus nagrinėja šablonų variklis, vardu inja. Šablonus galima tinkinti juos permušant (žr.: Šablono perrašymai). Šablonas turi prieigą prie tų pačių duomenų, kuriuos mato ir JSON reprezentacija bei prie kelių papildomų funkcijų, kurios prieinamos šablonui:

Savos šablonų funkcijos

path_append( path ): prideda prie dabartinio url aplanko kelią
path_chomp( n ): išima iš dabartinio url kelio nurodytą skaičių „n“ aplankų komponentų
json_dump( ): spausdina JSON duomenis, perduotus šablonui
static( path ): grąžina pilną URL iki nurodyto statinio kelio. Pavyzdžiui: „static( „/style/black.css“ )“ su šakniniu keliu „http://localhost/qgisserver/wfs3“ grąžins „http://localhost/qgisserver/wfs3/static/style/black.css“.
links_filter( links, key, value ): Grąžina filtruotas nuorodas iš nuorodų sąrašo
content_type_name( content_type ): Grąžina trumpą turinio tipo pavadinimą, pavyzdžiui „text/html“ grąžins „HTML“
nl2br( text ): Grąžina įvesties tekstą su visais naujos eilutės simboliais pakeistais į žymas „<br>“
starts_with( string, prefix ): grąžina true, jei tekstas prasideda nurodytu teksto priešdėliu, priešingu atveju grąžina false

Šablono perrašymai

Šablonai ir statiniai failai saugomi QGIS serverio numatyto API resursų aplanko poaplankiuose (/usr/share/qgis/resources/server/api/ Linux sistemose), bazinį aplanką galima keisti nurodant aplinkos kintamąjį QGIS_SERVER_API_RESOURCES_DIRECTORY.

Tipinė Linux sistema turės tokį aplankų medį:

/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

Norėdami permušti šablonus, jūs galite kopijuoti visą medį į kitą vietą ir į ją nukreipti QGIS_SERVER_API_RESOURCES_DIRECTORY.

3.6. OGC API Features (Geoobjektai)

3.6.1. Resursų reprezentacija

3.6.2. Prieigos taškai

Pradinis puslapis

API apibrėžimas

Rinkinių sąrašas

Rinkinio detalės

Geoobjektų sąrašas

Geoobjekto detalės

3.6.3. Puslapiavimas

3.6.4. Geoobjektų filtravimas

Datos ir laiko filtro

Apimties stačiakampio filtras

Atributų filtrai

3.6.5. Geoobjektų rikiavimas

3.6.6. Atributų parinkimas

3.6.7. Tinkinti HTML puslapius

Savos šablonų funkcijos

Šablono perrašymai