3.6. OGC API Features

OGC API Features (OAPIF) è la prima implementazione della nuova generazione di protocolli OGC. È descritto dal documento OGC API - Features - Part 1: Core.

Nelle installazioni ordinarie, l’API è raggiungibile tramite http://localhost/qgisserver/wfs3.

Ecco un rapido riassunto informale delle differenze più importanti tra il noto protocollo WFS e OAPIF:

  • OAPIF è basato su un’API REST

  • OAPIF deve seguire le specifiche di OPENAPI.

  • OAPIF supporta diversi formati di output, ma non ne impone nessuno (solo GeoJSON e HTML sono attualmente disponibili in QGIS OAPIF) e utilizza la content negotiation per determinare quale formato deve essere servito al client.

  • JSON e HTML sono considerati di prima classe in OAPIF

  • OAPIF è auto-documentata (attraverso l’endpoint /api)

  • L’OAPIF è completamente navigabile (tramite link) e sfogliabile

Importante

Mentre l’implementazione di OGC API Features in QGIS può utilizzare il parametro MAP per specificare il file di progetto, le specifiche OPENAPI non consentono di utilizzare parametri di interrogazione aggiuntivi. Per questo motivo si raccomanda vivamente di non esporre MAP nell’URL e di specificare il file di progetto nell’ambiente con altri mezzi (ad esempio impostando QGIS_PROJECT_FILE nell’ambiente tramite una regola di riscrittura del server web).

Nota

L’endpoint API fornisce una documentazione completa di tutti i parametri supportati e dei formati in uscita del tuo servizio. I paragrafi seguenti descriveranno solo i più importanti.

3.6.1. Rappresentazione risorse

L’implementazione di OGC API Features in QGIS Server supporta attualmente i seguenti formati di rappresentazione delle risorse (output):

  • HTML

  • JSON

Il formato che viene effettivamente reso dipenderà dalla negoziazione del contenuto, ma un formato specifico può essere richiesto esplicitamente aggiungendo uno specifico formato agli endpoint.

Le estensioni di specifica del formato supportate sono:

  • .json

  • .html

Ulteriori alias di specifica di formato possono essere definiti da endpoint specifici:

  • .openapi: alias per .json supportato dall’endpoint API

  • .geojson: alias per .json supportato dagli endpoint Features e Feature

3.6.2. Endpoint

L’API fornisce una lista di endpoint che i client possono richiamare. Il sistema è progettato in modo tale che ogni risposta fornisce un insieme di link per navigare attraverso tutte le risorse fornite.

Punti endpoint forniti dall’implementazione di QGIS sono:

Nome

Percorso

Descrizione

Pagina di destinazione

/

Informazioni generali sul servizio e fornisce collegamenti a tutti gli endpoint disponibili

Conformità

/conformance

Informazioni sulla conformità del servizio agli standard

API

/api

Descrizione completa degli endpoint forniti dal servizio e della struttura dei documenti restituiti

Collezioni

/collections

Elenco di tutte le collezioni (cioè « layer vettoriali») fornite dal servizio

Collezione

/collections/{collectionId}

Informazioni su una collezione (nome, metadati, estensione ecc.)

Caratteristiche

/collections/{collectionId}/items

Elenco degli elementi forniti dalla collezione

Elemento

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

Informazioni su un singolo elemento

Analogamente al WFS-T (transactional Web Feature Service), è possibile aggiungere, aggiornare e cancellare elementi (CRUD). Le rispettive richieste sono descritte in «/api».

Pagina di destinazione

L’endpoint principale è la Landing Page. Da questa pagina è possibile navigare verso tutti gli endpoint di servizio disponibili. La Landing Page deve fornire collegamenti a

  • la definizione dell’API (percorso /api link delle relazioni service-desc e service-doc),

  • la dichiarazione di Conformità (percorso /conformance, relazione di collegamento conformance), e

  • le Collezioni (percorso /collections, relazione di collegamento data).

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

Fig. 3.23 Server OAPIF landing page

Definizione API

La Definizione dell’API è una descrizione conforme a OPENAPI dell’API fornita dal servizio. Nella sua rappresentazione HTML è una pagina navigabile dove tutti gli endpoint e i loro formati di risposta sono accuratamente elencati e documentati. Il percorso di questo endpoint è /api.

La definizione API fornisce una documentazione completa e autorevole del servizio, compresi tutti i parametri supportati e i formati restituiti.

Nota

Questo endpoint è analogo a GetCapabilities di WFS

Lista Collezioni

L’endpoint collezioni fornisce una lista di tutte le collezioni disponibili nel servizio. Poiché il servizio «serve» un singolo progetto QGIS, le collezioni sono i layer vettoriali del progetto corrente (se sono stati pubblicati come WFS nelle proprietà del progetto). Il percorso di questo endpoint è /collections/.

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

Fig. 3.24 Server OAPIF collections list page

Dettaglio collezione

Mentre l’endpoint delle collezioni non fornisce informazioni dettagliate su ogni collezione disponibile, queste informazioni sono disponibili negli endpoint /collections/{collectionId}. Le informazioni tipiche includono l’estensione, una descrizione, i SR e altri metadati.

La rappresentazione HTML fornisce anche una mappa navigabile con gli elementi disponibili.

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

Fig. 3.25 Server OAPIF collection detail page

Lista elementi

Questo endpoint fornisce un elenco di tutti gli elementi in una collezione conoscendo l’ID della collezione. Il percorso di questo endpoint è /collections/{collectionId}/items.

La rappresentazione HTML fornisce anche una mappa navigabile con gli elementi disponibili.

Nota

Questo endpoint è analogo a GetFeature in WFS 1 e WFS 2.

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

Fig. 3.26 Server OAPIF features list page

Dettaglio elemento

Questo endpoint fornisce tutte le informazioni disponibili su un singolo elemento, compresi gli attributi dell’elemento e la sua geometria. Il percorso di questo endpoint è /collections/{collectionId}/items/{itemId}.

La rappresentazione HTML fornisce anche una mappa navigabile con la geometria degli elementi.

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

Fig. 3.27 Server OAPIF feature detail page

3.6.3. Paginazione

La paginazione di una lunga lista di elementi è implementata nell’API OGC attraverso i link next` e prev, il server QGIS costruisce questi link aggiungendo limit e offset come parametri della query string.

Esempio di URL:

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

Nota

Il valore massimo accettabile per limit può essere configurato con l’impostazione di configurazione del server QGIS_SERVER_API_WFS3_MAX_LIMIT (vedi: qgis-server-envvar`).

3.6.4. Filtro delle geometrie

Gli elementi disponibili in una collezione possono essere filtrati/ricercati specificando uno o più filtri.

Filtro data e ora

Le collezioni con attributi data e/o datetime possono essere filtrate specificando un argomento datetime nella stringa della query. Per impostazione predefinita, il primo campo data/ora è usato per il filtraggio. Questo comportamento può essere configurato impostando una dimensione «Date» o «Time» nella sezione QGIS Server ► Dimension della finestra di dialogo delle proprietà del layer.

La sintassi del filtraggio di data e ora è completamente descritta nella Definizione API e supporta anche intervalli (i valori iniziali e finali sono inclusi) oltre a valori singoli.

Esempi URL:

Restituisce solo gli elementi con una dimensione di data corrispondente a 2019-01-01.

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

Restituisce solo gli elementi con dimensione datetime che corrisponde a 2019-01-01T01:01:01.

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

Restituisce solo gli elementi con dimensione datetime nell’intervallo 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

Filtro rettangolo di delimitazione

Un filtro spaziale bounding box può essere specificato con il parametro bbox:

L’ordine degli elementi separati da virgola è:

  • Angolo inferiore sinistro, longitudine WGS 84

  • Angolo inferiore sinistro, latitudine WGS 84

  • Angolo superiore destro, longitudine WGS 84

  • Angolo superiore destro, latitudine WGS 84

Nota

Le specifiche OGC permettono anche uno specifico bbox a 6 elementi dove il terzo e il sesto elemento sono i componenti Z, questo non è ancora supportato dal server QGIS.

Esempio di URL:

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

Se il SR del riquadro di delimitazione non è WGS 84, un CRS diverso può essere specificato usando il parametro opzionale bbox-crs. L’identificatore del formato SR deve essere nel formato OGC URI:

Esempio di 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

Filtro Attributo

I filtri degli attributi possono essere combinati con il filtro bounding box e sono nella forma generale: <attribute name>=<attribute value>. Filtri multipli possono essere combinati usando l’operatore AND`.

Esempio di URL:

filtra tutti gli elementi in cui l’attributo name è uguale a «my value»

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

Le corrispondenze parziali sono supportate anche usando un operatore * («star»):

Esempio di URL:

filtra tutti gli elementi in cui l’attributo name finisce con «value»

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

3.6.5. Ordinamento elemento

È possibile ordinare l’insieme dei risultati per valore di campo usando il parametro della query sortby.

I risultati sono ordinati in ordine crescente per impostazione predefinita. Per ordinare i risultati in ordine decrescente, si può impostare un flag booleano (sortdesc):

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

3.6.6. Selezione attributo

Gli attributi elemenelementi restituiti da una chiamata Lista elementi possono essere limitati aggiungendo una lista separata da virgole di nomi di attributi nell’argomento opzionale properties della query string.

Esempio di URL:

restituisce solo l’attributo name.

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

3.6.7. Personalizzare le pagine HTML

La rappresentazione HTML utilizza un insieme di modelli HTML per generare la risposta. Il template viene analizzato da un motore di template chiamato inja. I template possono essere personalizzati sovrascrivendoli (vedere: Sovrascritture modello). Il template ha accesso agli stessi dati disponibili per la rappresentazione JSON e alcune funzioni aggiuntive sono disponibili per il template:

Funzioni personalizzate modello

  • path_append( path ): aggiunge un percorso di cartella all’url corrente

  • path_chomp( n ): rimuove il numero specificato «n» di componenti di cartella dal percorso url corrente

  • json_dump( ): stampa i dati JSON passati al modello

  • static( path ): restituisce l’URL completo del percorso statico specificato. Per esempio: «static( «/style/black.css» )» con un percorso radice «http://localhost/qgisserver/wfs3» restituirà «http://localhost/qgisserver/wfs3/static/style/black.css».

  • links_filter( links, key, value ): Restituisce i link filtrati da un elenco di link

  • content_type_name( content_type ): Restituisce un nome breve di un tipo di contenuto, per esempio «text/html» restituirà «HTML»

  • nl2br( text ): Restituisce il testo in ingresso con tutte le linee nuove sostituite dal tag «<br>».

  • starts_with( string, prefix ): restituisce true se una stringa inizia con il prefisso fornito, false altrimenti

Sovrascritture modello

I modelli e le risorse statiche sono memorizzati nelle sottocartelle della cartella delle risorse API di default del server QGIS (/usr/share/qgis/resources/server/api/ su un sistema Linux), la cartella di base può essere personalizzata cambiando la variabile di ambiente QGIS_SERVER_API_RESOURCES_DIRECTORY.

Una tipica installazione di Linux avrà il seguente albero di cartelle:

/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

Per sovrascrivere i modelli puoi copiare l’intero albero in un’altra posizione e assegnare QGIS_SERVER_API_RESOURCES_DIRECTORY alla nuova posizione.