Viktigt

Översättning är en gemenskapsinsats du kan gå med i. Den här sidan är för närvarande översatt till 100.00%.

3.6. Funktioner i OGC API

OGC API Features (OAPIF) är den första implementeringen av den nya generationen OGC-protokoll. Det beskrivs av dokumentet OGC API - Funktioner - Del 1: Core dokument.

API:et kan nås på vanliga installationer via http://localhost/qgisserver/wfs3.

Här följer en snabb informell sammanfattning av de viktigaste skillnaderna mellan det välkända WFS-protokollet och OAPIF:

  • OAPIF är baserat på ett REST API

  • OAPIF måste följa specifikationerna för OPENAPI

  • OAPIF stöder flera utdataformat, men det dikterar inte något (endast GeoJSON och HTML är för närvarande tillgängliga i QGIS OAPIF) och det använder innehållsförhandling för att avgöra vilket format som ska serveras till klienten

  • JSON och HTML är förstklassiga medborgare i OAPIF

  • OAPIF är självdokumenterande (genom slutpunkten /api)

  • OAPIF är fullt navigerbar (via länkar) och bläddringsbar

Viktigt

Även om implementeringen av OGC API Features i QGIS kan använda parametern MAP för att ange projektfilen, tillåts inga extra frågeparametrar enligt OPENAPI-specifikationen. Av detta skäl rekommenderas starkt att MAP inte exponeras i URL:en och att projektfilen anges i miljön på annat sätt (dvs. genom att ställa in QGIS_PROJECT_FILE i miljön via en omskrivningsregel på webbservern).

Observera

Slutpunkten API ger omfattande dokumentation av alla parametrar och utdataformat som stöds av din tjänst. I följande stycken beskrivs endast de viktigaste.

3.6.1. Representation av resurser

Implementeringen av OGC API-funktioner i QGIS Server stöder för närvarande följande format för resursrepresentation (utdata):

  • HTML

  • JSON

Det format som faktiskt levereras beror på innehållsförhandlingen, men ett specifikt format kan uttryckligen begäras genom att en formatspecifikator läggs till i ändpunkterna.

Formatspecifikationstillägg som stöds är:

  • .json

  • .html

Ytterligare alias för formatspecificerare kan definieras av specifika ändpunkter:

  • .openapi: alias för .json som stöds av ändpunkten API

  • .geojson: alias för .json som stöds av ändpunkterna Features och Feature

3.6.2. Endpoints

API:et tillhandahåller en lista med slutpunkter som klienterna kan hämta. Systemet är utformat på ett sådant sätt att varje svar innehåller en uppsättning länkar för att navigera genom alla de resurser som tillhandahålls.

Slutpunkterna som tillhandahålls av QGIS-implementeringen är:

Namn

Sökväg

Beskrivning

Landningssida

/

Allmän information om tjänsten och länkar till alla tillgängliga endpoints

Överensstämmelse

/conformance

Information om tjänstens överensstämmelse med standarderna

API

/api

Fullständig beskrivning av de slutpunkter som tillhandahålls av tjänsten och strukturen för de returnerade dokumenten

Samlingar

/collections

Lista över alla samlingar (dvs. ”vektorlager”) som tillhandahålls av tjänsten

Samling

/collections/{collectionId}

Information om en samling (namn, metadata, omfattning etc.)

Funktioner

/collections/{collectionId}/items

Lista över de funktioner som tillhandahålls av samlingen

Funktion

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

Information om en enskild funktion

I likhet med WFS-T (transactional Web Feature Service) är det möjligt att lägga till, uppdatera och ta bort funktioner (CRUD). Respektive begäran beskrivs på ”/api”.

Landningssida

Den huvudsakliga slutpunkten är Landningssidan. Från den sidan är det möjligt att navigera till alla tillgängliga tjänsteändpunkter. Landningssidan måste innehålla länkar till

  • aPI-definitionen (sökväg /api länkrelationer service-desc och service-doc),

  • conformance-deklarationen (sökväg /conformance, länkrelation conformance), och

  • samlingarna (sökväg /collections, länkrelation data).

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

Fig. 3.25 Server OAPIF landningssida

API-definition

API-definitionen** är en OPENAPI-kompatibel beskrivning av det API som tillhandahålls av tjänsten. I sin HTML-representation är det en bläddringsbar sida där alla endpoints och deras svarsformat är noggrant listade och dokumenterade. Sökvägen till denna endpoint är /api.

API-definitionen ger en omfattande och auktoritativ dokumentation av tjänsten, inklusive alla parametrar som stöds och returformat.

Observera

Denna ändpunkt är analog med WFS GetCapabilities

Samlingslista

Slutpunkten för samlingar ger en lista över alla samlingar som finns tillgängliga i tjänsten. Eftersom tjänsten ”betjänar” ett enda QGIS-projekt är samlingarna vektorlagren från det aktuella projektet (om de publicerades som WFS i projektegenskaperna). Sökvägen till den här ändpunkten är /collections/.

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

Fig. 3.26 Server OAPIF samlingar lista sida

Kollektionsdetaljer

Slutpunkten collections ger inte detaljerad information om varje tillgänglig samling, men den informationen finns i slutpunkterna /collections/{collectionId}. Typisk information omfattar omfattning, beskrivning, CRS och andra metadata.

HTML-representationen ger också en bläddringsbar karta med de tillgängliga funktionerna.

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

Fig. 3.27 Server OAPIF samling detaljsida

Featureslista

Denna endpoint ger en lista över alla funktioner i en samling som känner till samlingens ID. Sökvägen för denna endpoint är /collections/{collectionId}/items.

HTML-representationen ger också en bläddringsbar karta med de tillgängliga funktionerna.

Observera

Denna ändpunkt är analog med GetFeature i WFS 1 och WFS 2.

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

Fig. 3.28 Lista över funktioner i Server OAPIF sida

Detaljerad funktion

Denna endpoint tillhandahåller all tillgänglig information om en enskild feature, inklusive feature-attribut och dess geometri. Sökvägen till denna endpoint är /collections/{collectionId}/items/{itemId}.

HTML-representationen ger också en bläddringsbar karta med objektets geometri.

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

Fig. 3.29 Detaljerad sida för funktionen Server OAPIF

3.6.3. Sidindelning

Paginering av en lång lista med funktioner implementeras i OGC API genom next och prev länkar, QGIS server konstruerar dessa länkar genom att lägga till limit och offset som parametrar i frågesträngen.

Exempel på URL:

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

Observera

Det högsta godtagbara värdet för limit kan konfigureras med serverns konfigurationsinställning QGIS_SERVER_API_WFS3_MAX_LIMIT (se: Miljövariabler).

3.6.4. Filtrering av funktioner

De funktioner som finns i en samling kan filtreras/sökas genom att ange ett eller flera filter.

Datum- och tidsfilter

Samlingar med datum- och/eller datetime-attribut kan filtreras genom att ange ett datetime-argument i frågesträngen. Som standard används det första datum-/datetime-fältet för filtrering. Detta beteende kan konfigureras genom att ange en ”Date”- eller ”Time”-dimension i avsnittet QGIS Server ► Dimension i dialogen för lageregenskaper.

Syntaxen för datum- och tidsfiltrering beskrivs i sin helhet i API-definition och stöder även intervall (start- och slutvärden ingår) utöver enskilda värden.

Exempel på webbadresser:

Returnerar endast de funktioner med datumdimension som matchar 2019-01-01

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

Returnerar endast funktioner med en datatidsdimension som matchar 2019-01-01T01:01:01

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

Returnerar endast funktioner med datetime-dimension i intervallet 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

Filter för begränsande box

Ett spatialt filter med avgränsande box kan specificeras med parametern bbox:

Ordningen på de kommaseparerade elementen är:

  • Nedre vänstra hörnet, WGS 84-longitud

  • Nedre vänstra hörnet, WGS 84 latitud

  • Övre högra hörnet, WGS 84-longitud

  • Övre högra hörnet, WGS 84 latitud

Observera

OGC-specifikationerna tillåter också en bbox-specifikator med 6 objekt där det tredje och sjätte objektet är Z-komponenterna, men detta stöds ännu inte av QGIS-servern.

Exempel på URL:

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

Om CRS för begränsningsrutan inte är WGS 84 kan ett annat CRS anges med hjälp av den valfria parametern bbox-crs. Identifieraren för CRS-formatet måste vara i formatet OGC URI:

Exempel på 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

Attributfilter

Attributfilter kan kombineras med bounding box-filtret och de har följande allmänna form: <attribute name>=<attribute value>. Flera filter kan kombineras med hjälp av operatorn AND.

Exempel på URL:

filtrerar alla funktioner där attributet namn är lika med ”mitt värde”

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

Partiella matchningar stöds också genom att använda operatorn * (”stjärna”):

Exempel på URL:

filtrerar alla funktioner där attributet name slutar med ”value”

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

3.6.5. Sortering av funktioner

Det är möjligt att sortera resultatuppsättningen efter fältvärde med hjälp av frågeparametern ortby.

Resultaten sorteras som standard i stigande ordning. Om du vill sortera resultaten i fallande ordning kan du ange en boolesk flagga (ortdesc):

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

3.6.6. Val av attribut

De funktionsattribut som returneras av ett anrop från Featureslista kan begränsas genom att lägga till en kommaseparerad lista med attributnamn i det valfria argumentet properties i frågesträngen.

Exempel på URL:

returnerar endast attributet name

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

3.6.7. Anpassa HTML-sidorna

HTML-representationen använder en uppsättning HTML-mallar för att generera svaret. Mallen analyseras av en mallmotor som heter inja. Mallarna kan anpassas genom att åsidosätta dem (se: Åsidosättande av mall). Mallen har tillgång till samma data som är tillgängliga för JSON-representationen och några ytterligare funktioner är tillgängliga för mallen:

Anpassade mallfunktioner

  • path_append( path ): lägger till en katalogsökväg till den aktuella webbadressen

  • path_chomp( n ): tar bort det angivna antalet ”n” katalogkomponenter från den aktuella webbadressens sökväg

  • json_dump( ): skriver ut JSON-data som skickas till mallen

  • static( path ): returnerar den fullständiga URL:en till den angivna statiska sökvägen. Till exempel: ”static( ”static( ”/style/black.css” )” med en rotsökväg ”http://localhost/qgisserver/wfs3” returnerar ”http://localhost/qgisserver/wfs3/static/style/black.css”.

  • länkar_filter( länkar, nyckel, värde ): Returnerar filtrerade länkar från en länklista

  • content_type_name( content_type ): Returnerar ett kort namn från en innehållstyp, till exempel ”text/html” returnerar ”HTML”

  • nl2br( text ): Returnerar inmatningstexten med alla nya rader ersatta av ”<br>” taggar

  • starts_with( string, prefix ): returnerar true om en sträng börjar med det angivna strängprefixet, false annars

Åsidosättande av mall

Mallar och statiska tillgångar lagras i underkataloger i QGIS-serverns standard API-resurskatalog (/usr/share/qgis/resources/server/api/ på ett Linux-system), baskatalogen kan anpassas genom att ändra miljövariabeln QGIS_SERVER_API_RESOURCES_DIRECTORY.

En typisk Linux-installation har följande katalogträd:

/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

Om du vill åsidosätta mallarna kan du kopiera hela trädet till en annan plats och peka QGIS_SERVER_API_RESOURCES_DIRECTORY till den nya platsen.