Important

La traduction est le fruit d’un effort communautaire auquel vous pouvez vous joindre. Cette page est actuellement traduite à 100.00%.

3.6. OGC API Features

OGC API Features (OAPIF) est la première implémentation de la nouvelle génération de protocoles OGC. Elle est décrite par le document OGC API - Features - Part 1: Core.

L’API est accessible sur les installations classiques via http://localhost/qgisserver/wfs3

Voici un résumé informel rapide des différences les plus importantes entre le protocole WFS bien connu et OAPIF:

  • OAPIF est basé sur l’API REST

  • OAPIF doit suivre les spécifications OPENAPI

  • OAPIF prend en charge plusieurs formats de sortie, mais il n’en dicte aucun (seuls GeoJSON et HTML sont actuellement disponibles avec OAPIF sous QGIS) et il utilise la négociation de contenu pour déterminer le format qui doit être servi au client

  • JSON et HTML sont des citoyens de première classe dans OAPIF

  • OAPIF est auto-documenté (via le point de terminaison /api)

  • OAPIF est entièrement navigable (via des liens) et explorable

Important

Alors que l’implémentation OGC API Features dans QGIS peut utiliser le paramètre MAP pour spécifier le fichier de projet, aucun paramètre de requête supplémentaire n’est autorisé par la spécification OPENAPI. Pour cette raison, il est fortement recommandé que MAP ne soit pas exposé dans l’URL et que le fichier de projet soit spécifié dans l’environnement par d’autres moyens (c’est-à-dire en définissant QGIS_PROJECT_FILE dans l’environnement via une règle de réécriture de serveur Web).

Note

Le point de terminaison API fournit une documentation complète de tous les paramètres et formats de sortie pris en charge de votre service. Les paragraphes suivants ne décrivent que les plus importants.

3.6.1. Représentation des ressources

L’implémentation de l’OGC API Features dans QGIS Server prend actuellement en charge les formats de représentation (sortie) de ressources suivants :

  • HTML

  • JSON

Le format réellement servi dépendra de la négociation de contenu, mais un format spécifique peut être explicitement demandé en ajoutant un spécificateur de format aux points de terminaison.

Les extensions de spécificateur de format prises en charge sont:

  • .json

  • .html

Des alias de spécificateur de format supplémentaires peuvent être définis par des points de terminaison spécifiques:

  • .openapi: alias pour .json pris en charge par le point de terminaison API

  • .geojson: alias pour .json pris en charge par les points de terminaison Features et Feature

3.6.2. Points de terminaison

L’API fournit une liste de points de terminaison que les clients peuvent récupérer. Le système est conçu de telle manière que chaque réponse fournit un ensemble de liens pour naviguer à travers toutes les ressources fournies.

Les points de terminaison fournis par l’implémentation de QGIS sont :

Nom

Chemin

Description

Page de destination

/

Informations générales sur le service et fournit des liens vers tous les points de terminaison disponibles

Conformité

/conformance

Informations sur la conformité du service aux normes

API

/api

Description complète des noeuds finaux fournis par le service et de la structure des documents retournés

Les collections

/collections

Liste de toutes les collections (c’est-à-dire « couches vectorielles ») fournies par le service

Collection

/collections/{collectionId}

Informations sur une collection (nom, métadonnées, étendue, etc.)

Fonctionnalités

/collections/{collectionId}/items

Liste des entités fournies par la collection

Entité

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

Informations sur une seule entité

Comme pour le WFS-T (Transactional Web Feature Service), il est possible d’ajouter, de mettre à jour et de supprimer des entités (CRUD). Les requêtes respectives sont décrites sur « /api ».

Page de destination

Le critère d’évaluation principal est la page destination. À partir de cette page, il est possible de naviguer vers tous les points de terminaison de service disponibles. La page de destination doit fournir des liens vers

  • la définition de l’API (chemin d’accès /api relations de liaison service-desc et service-doc),

  • la déclaration de conformité (chemin /conformance, relation de liaison conformance), et

  • les Collections (chemin /collections, relation de lien data).

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

Fig. 3.24 Page de destination du serveur OAPIF

Définition de l’API

La Définition API est une description conforme à OPENAPI de l’API fournie par le service. Dans sa représentation HTML, il s’agit d’une page consultable où tous les points de terminaison et leurs formats de réponse sont répertoriés et documentés avec précision. Le chemin de ce point de terminaison est /api.

La définition de l’API fournit une documentation complète et faisant autorité du service, y compris tous les paramètres pris en charge et les formats renvoyés.

Note

Ce point de terminaison est analogue aux GetCapabilities de WFS

Liste des collections

Le point de terminaison des collections fournit une liste de toutes les collections disponibles dans le service. Étant donné que le service « serves «  un seul projet QGIS, les collections sont les couches vectorielles du projet en cours (si elles ont été publiées en tant que WFS dans les propriétés du projet). Le chemin de ce point de terminaison est /collections/.

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

Fig. 3.25 Page de liste des collections du serveur OAPIF

Détail de la collection

Bien que le point de terminaison des collections ne fournisse pas d’informations détaillées sur chaque collection disponible, ces informations sont disponibles dans les points de terminaison /collections/{collectionId}. Les informations typiques incluent l’étendue, une description, les SCR et autres métadonnées.

La représentation HTML fournit également une carte consultable avec les entités disponibles.

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

Fig. 3.26 Page de détail de la collection du serveur OAPIF

Liste des entités

Ce point de terminaison fournit une liste de toutes les entités d’une collection connaissant l’ID de la collection. Le chemin de ce noeud final est /collections/{collectionId}/items .

La représentation HTML fournit également une carte consultable avec les entités disponibles.

Note

Ce point de terminaison est analogue à GetFeature dans WFS 1 et WFS 2.

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

Fig. 3.27 Page de liste des entités du serveur OAPIF

Détail des entités

Ce point de terminaison fournit toutes les informations disponibles sur une seule entité, y compris les attributs de l’entité et sa géométrie. Le chemin de ce point de terminaison est /collections/{collectionId}/items/{itemId}.

La représentation HTML fournit également une carte consultable avec la géométrie de l’entité.

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

Fig. 3.28 Page de détail des entités du serveur OAPIF

3.6.3. Pagination

La pagination d’une longue liste d’entités est implémentée dans l’API OGC via des liens précédent (next) et suivant (prev). QGIS Server construit ces liens en ajoutant limit et offset comme paramètres de chaîne de requête.

Exemple d’URL :

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

Note

La valeur maximale acceptable pour limit peut être configurée avec le paramètre de configuration du serveur QGIS_SERVER_API_WFS3_MAX_LIMIT (voir Variables d’environnement).

3.6.4. Filtrage des entités

Les entités disponibles dans une collection peuvent être filtrées / recherchées en spécifiant un ou plusieurs filtres.

Filtre date et heure

Les collections avec des attributs date et / ou datetime peuvent être filtrées en spécifiant un argument datetime dans la chaîne de requête. Par défaut, le premier champ date / datetime est utilisé pour le filtrage. Ce comportement peut être configuré en définissant une dimension « Date » ou « Heure » dans QGIS Server ► Dimension de la boîte de dialogue des propriétés de la couche.

La syntaxe de filtrage de la date et de l’heure est entièrement décrite dans Définition de l’API et prend également en charge les plages (les valeurs de début et de fin sont incluses) en plus des valeurs uniques.

Exemples d’URL :

Renvoie uniquement les entités dont la dimension de date correspond à 2019-01-01

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

Renvoie uniquement les entités dont la dimension datetime correspond à 2019-01-01T01: 01: 01

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

Renvoie uniquement les entités dont la dimension datetime se situe dans la plage 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

Filtre de boîte englobante

Un filtre spatial de boîte englobante peut être spécifié avec le paramètre bbox :

L’ordre des éléments séparés par des virgules est le suivant:

  • Coin inférieur gauche, longitude WGS 84

  • Coin inférieur gauche, latitude WGS 84

  • Coin supérieur droit, longitude WGS 84

  • Coin supérieur droit, latitude WGS 84

Note

Les spécifications OGC autorisent également un spécificateur bbox à 6 éléments où les troisième et sixième éléments sont les composants Z, ce qui n’est pas encore pris en charge par le serveur QGIS.

Exemple d’URL :

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

Si le SCR de la boîte englobante n’est pas WGS 84, un SCR différent peut être spécifié en utilisant le paramètre optionnel bbox-crs. L’identificateur de format du SCR doit être au format OGC URI :

Exemple d’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

Filtres d’attributs

Les filtres d’attribut peuvent être combinés avec le filtre de boîte englobante et ils se présentent sous la forme générale: 1=2. Plusieurs filtres peuvent être combinés à l’aide de l’opérateur AND.

Exemple d’URL :

filtre toutes les entités où l’attribut name est égal à « ma valeur »

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

Les correspondances partielles sont également prises en charge en utilisant un opérateur * (« etoile »):

Exemple d’URL :

filtre toutes les entités où l’attribut name se termine par « value »

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

3.6.5. Tri des éléments

Il est possible d’ordonner le résultat par valeur de champ en utilisant le paramètre d’interrogation « sortby ».

Par défaut, les résultats sont triés par ordre croissant. Pour trier les résultats par ordre décroissant, un drapeau booléen (sortdesc) peut être activé :

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

3.6.6. Sélection d’attribut

Les attributs d’entité renvoyés par un appel Liste des entités peuvent être limités en ajoutant une liste de noms d’attributs séparés par des virgules dans l’argument de chaîne de requête facultatif propriétés.

Exemple d’URL :

renvoie uniquement l’attribut name

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

3.6.7. Personnaliser les pages HTML

La représentation HTML utilise un ensemble de modèles HTML pour générer la réponse. Le modèle est analysé par un moteur de modèle appelé inja. Les modèles peuvent être personnalisés en les remplaçant (voir Remplacements de modèle). Le modèle a accès aux mêmes données disponibles pour la représentation JSON, avec quelques fonctions supplémentaires :

Fonctions de modèle personnalisées

  • path_append(path) : ajoute un chemin de répertoire à l’url actuelle

  • path_chomp(n) : supprime le nombre spécifié « n » de composants de répertoire du chemin d’URL actuel

  • json_dump(): affiche les données JSON transmises au modèle

  • static(path): renvoie l’URL complète du chemin statique spécifié. Par exemple: « static(« /style/black.css ») » avec un chemin racine « http://localhost/qgisserver/wfs3 » renverra « http://localhost/qgisserver/wfs3/static/style/black.css ».

  • links_filter(links, key, value): retourne les liens filtrés d’une liste de liens

  • content_type_name(content_type): renvoie un nom court à partir d’un type de contenu, par exemple « text / html » renverra « HTML »

  • nl2br( text ): Renvoie le texte en entrée avec les nouvelles lignes remplacées par les tags « <br> »

  • starts_with( string, prefix ): renvoie vrai si un texte commence par le préfixe indiqué, sinon faux

Remplacements de modèle

Les modèles et les actifs statiques sont stockés dans des sous-répertoires du répertoire de ressources de l’API par défaut du serveur QGIS ( /usr/share/qgis/resources/server/api/ sur un système Linux), le répertoire de base peut être personnalisé en modifiant le variable d’environnement QGIS_SERVER_API_RESOURCES_DIRECTORY.

Une installation Linux typique aura l’arborescence de répertoires suivante:

/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

Pour remplacer les modèles, vous pouvez copier l’arborescence entière vers un autre emplacement et pointer vers le nouvel emplacement. QGIS_SERVER_API_RESOURCES_DIRECTORY