From bbfe5f1ecba1d3a9037160d16347405e7cb94205 Mon Sep 17 00:00:00 2001 From: Orka Arnest CRUZE Date: Fri, 20 Dec 2024 16:02:49 +0100 Subject: [PATCH] docs: mention annexes pour documents, capabilities etc #565 --- docs/developer/entrepot/README.md | 16 +++++--- docs/developer/entrepot/annexes.md | 62 +++++++++++++++++++++++++++-- docs/developer/entrepot/entities.md | 6 --- docs/developer/entrepot/labels.md | 32 +++++++++++++++ docs/developer/entrepot/statics.md | 2 +- docs/developer/entrepot/tags.md | 39 +++++++++++++----- 6 files changed, 130 insertions(+), 27 deletions(-) delete mode 100644 docs/developer/entrepot/entities.md diff --git a/docs/developer/entrepot/README.md b/docs/developer/entrepot/README.md index 95973d34..b12b4951 100644 --- a/docs/developer/entrepot/README.md +++ b/docs/developer/entrepot/README.md @@ -1,8 +1,12 @@ # Utilisation de l'API Entrepôt -- [Description des entités de l'API](./entities.md) -- Utilisation des : - - [tags](./tags.md) - - [labels](./labels.md) - - [annexes](./annexes.md) - - [fichiers statiques](./statics.md) +Le site cartes.gouv.fr repose principalement sur l'API Entrepôt. + +Voici les liens de sa documentation en [production](https://geoplateforme.github.io/entrepot/production) et [qualification](https://geoplateforme.github.io/entrepot/qualification) + +- [Description des entités de l'API](https://geoplateforme.github.io/entrepot/production/concepts) +- Utilisation des : + - [tags](./tags.md) + - [labels](./labels.md) + - [annexes](./annexes.md) + - [fichiers statiques](./statics.md) diff --git a/docs/developer/entrepot/annexes.md b/docs/developer/entrepot/annexes.md index ac6734c3..204255b2 100644 --- a/docs/developer/entrepot/annexes.md +++ b/docs/developer/entrepot/annexes.md @@ -1,6 +1,6 @@ # Utilisation des fichiers annexes -Il s'agit d'une [entité](./entities.md) de l'API qui représente des fichiers librement déposés et utilisés par les utilisateurs de l'API Entrepôt. +Il s'agit d'une [entité](https://geoplateforme.github.io/entrepot/production/concepts/) de l'API qui représente des fichiers librement déposés et utilisés par les utilisateurs de l'API Entrepôt. ## un ensemble de fichiers de style associés à une configuration @@ -16,7 +16,19 @@ Syntaxe du path : Structure de cet annexe json : -- `SLD` ou `QML` pour une configuration du type `WFS` +```ts +export type Styles = { + name: string; + current?: boolean; + layers: { + name?: string; + annexe_id: string; + url: string; + }[]; +}[]; +``` + +- `SLD` ou `QML` pour une configuration du type `WFS` ```json [ @@ -45,7 +57,7 @@ Structure de cet annexe json : > Il y a un fichier de style SLD par table. Donc pour chaque table il y a un annexe qui contient le style. Et cette structure json globale répertorie tous les styles associés à une configuration WFS. -- `Mapbox` pour une configuration du type `WMTS-TMS` +- `Mapbox` pour une configuration du type `WMTS-TMS` (pyramide de tuiles vectorielles) ```json [ @@ -66,3 +78,47 @@ Structure de cet annexe json : } ] ``` + +## un ensemble de documents liés à une fiche de donnée + +Syntaxe du path : + +``` +/documents/[datasheet_name]/styles.json +``` + +| variable | description | | +| ---------------- | ------------------------- | ------ | +| `datasheet_name` | nom de la fiche de donnée | string | + +Structure de cet annexe json : + +```ts +export type DatasheetDocument = { + type: "link" | "file"; + url: string; + name: string; + description?: string; + id: string; +}; +``` + +```json +[ + { + "type": "link", + "name": "test lien", + "description": "test lien desc", + "id": "uuid généré automatiquement par cartes.gouv.fr", + "url": "https://ign.fr" + }, + { + "type": "file", + "name": "projet qgis", + "description": "un projet qgis", + "id": "identifiant de l'annexe", + "url": "url complète de l'annexe" + } + ... +] +``` diff --git a/docs/developer/entrepot/entities.md b/docs/developer/entrepot/entities.md deleted file mode 100644 index ac793bcf..00000000 --- a/docs/developer/entrepot/entities.md +++ /dev/null @@ -1,6 +0,0 @@ -# Entités de l'API Entrepôt - -Lien vers la documentation officielle de l'API sur le sujet : - -- https://geoplateforme.github.io/entrepot/concepts (production) -- https://geoplateforme.github.io/entrepot/qualification/concepts (qualification) diff --git a/docs/developer/entrepot/labels.md b/docs/developer/entrepot/labels.md index e2c85576..4e88e472 100644 --- a/docs/developer/entrepot/labels.md +++ b/docs/developer/entrepot/labels.md @@ -4,6 +4,8 @@ Certaines entités portent une propriété `labels`, qui est une liste de chaîn Mais nous utilisons les labels comme des `tags` de la manière suivante : "[clé]=[valeur]". Donc, pas de "=" possible dans les labels. +Exemple : datasheet_name=Ma donnée + ## `annexe` ### vignette d'une fiche de donnée @@ -15,7 +17,37 @@ Mais nous utilisons les labels comme des `tags` de la manière suivante : "[clé ### fichier de style individuel (par ex. contenu du SLD, QML etc) +Un fichier de style déposé via cartes.gouv.fr est stocké d'abord dans un annexe avant d'être référencé dans l'annexe "chapeau" décrit [ici](./annexes.md) + | label | description | | | ---------------- | ------------------------- | ------ | | `datasheet_name` | nom de la fiche de donnée | string | | `type` | valeur fixe : "style" | string | + +### ensemble de documents liés à une fiche de donnée + +| label | description | | +| ---------------- | ----------------------------- | ------ | +| `datasheet_name` | nom de la fiche de donnée | string | +| `type` | valeur fixe : "document-list" | string | + +### un document lié à une fiche de donnée + +Un document du type fichier est stocké d'abord dans un annexe avant d'être référencé dans l'annexe "chapeau" décrit au-dessus et [ici](./annexes.md) + +| label | description | | +| ---------------- | ------------------------- | ------ | +| `datasheet_name` | nom de la fiche de donnée | string | +| `type` | valeur fixe : "document" | string | + +### fichier GetCapabilities filtrés pour les endpoints WFS, WMS (raster et vecteur) et WMTS + +Syntaxe du path : + +``` +/[endpoint_technical_name]/capabilities.xml +``` + +| label | description | | +| ------ | ---------------------------- | ------ | +| `type` | valeur fixe : "capabilities" | string | diff --git a/docs/developer/entrepot/statics.md b/docs/developer/entrepot/statics.md index bb278b88..ac6d61fd 100644 --- a/docs/developer/entrepot/statics.md +++ b/docs/developer/entrepot/statics.md @@ -1,6 +1,6 @@ # Utilisation des fichiers statiques -Il s'agit d'une [entité](./entities.md) de l'API qui représente des fichiers de configuration utilisés par l'Entrepôt en arrière plan lors des différents traitements. +Il s'agit d'une [entité](https://geoplateforme.github.io/entrepot/production/concepts/) de l'API qui représente des fichiers de configuration utilisés par l'Entrepôt en arrière plan lors des différents traitements. Cette entité `static` a seulement une propriété `name`, pas de `tags` ni de `labels`. Donc, afin de pouvoir lier ces fichiers statiques à d'autres entités pour notre usage, nous allons se contenter d'utiliser une nomination particulière. diff --git a/docs/developer/entrepot/tags.md b/docs/developer/entrepot/tags.md index 26261e0c..b018d60b 100644 --- a/docs/developer/entrepot/tags.md +++ b/docs/developer/entrepot/tags.md @@ -6,14 +6,14 @@ Certaines entités portent une propriété `tags`, qui est un dictionnaire clé/ | tag | description | | | -------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- | ------- | -| `proc_int_id` | identifiant de l'exécution du traitement "Intégration de données vecteur livrées en base" | uuidv4 | | `datasheet_name` | nom de la fiche de donnée | string | +| `proc_int_id` | identifiant de l'exécution du traitement "Intégration de données vecteur livrées en base" | uuidv4 | | `vectordb_id` | identifiant de la donnée stockée en sortie du traitement `proc_int_id` | uuidv4 | | `data_upload_path` | chemin vers le fichier téléversé | | | `integration_progress` | progression de l'intégration en base de données (envoi du fichier téléversé à l'API, attente des vérifications et puis le traitement d'intégration en BD) | json(1) | | `integration_current_step` | numéro de l'étape courante de integration_progress | number | -(1) structure de json : +(1) structure de json (chaîne json encodée) : ```json // nom de l'étape : statut [waiting, in_progress, successful, failed] @@ -28,24 +28,41 @@ Certaines entités portent une propriété `tags`, qui est un dictionnaire clé/ ### tags communs +> [!IMPORTANT] +> Ces tags sont présents sur tous les stored_data + | tag | description | | | ---------------- | --------------------------------------- | ------ | | `datasheet_name` | pareil que `datasheet_name` de `upload` | string | ### tags spécifiques aux stored_data du type `VECTOR-DB` -| tag | description | | -| ------------- | ------------------------------------------------------------- | ------ | -| `upload_id` | identifiant de l'`upload` utilisé lors de l'intégration en BD | uuidv4 | -| `proc_int_id` | pareil que `proc_int_id` de `upload` | uuidv4 | +| tag | description | | +| ---------------- | ------------------------------------------------------------- | ------ | +| `datasheet_name` | - | - | +| `upload_id` | identifiant de l'`upload` utilisé lors de l'intégration en BD | uuidv4 | +| `proc_int_id` | pareil que `proc_int_id` de `upload` | uuidv4 | ### tags spécifiques aux stored_data du type `ROK4-PYRAMID-VECTOR` -| tag | description | | -| ------------------- | ------------------------------------------------------------------------------------------- | ------- | -| `proc_pyr_creat_id` | identifiant de l'exécution du traitement "Calcul de pyramide vecteur" | uuidv4 | -| `vectordb_id` | identifiant de la donnée stockée `VECTOR-DB` utilisée pour le calcul de la pyramide vecteur | uuidv4 | -| `is_sample` | vrai s'il s'agit d'un échantillon : pyramide vecteur générée dans une petite zone | boolean | +| tag | description | | +| ------------------- | ------------------------------------------------------------------------------------------- | ----------------- | +| `datasheet_name` | - | - | +| `upload_id` | - | - | +| `proc_int_id` | - | - | +| `proc_pyr_creat_id` | identifiant de l'exécution du traitement "Calcul de pyramide vecteur" | uuidv4 | +| `vectordb_id` | identifiant de la donnée stockée `VECTOR-DB` utilisée pour le calcul de la pyramide vecteur | uuidv4 | +| `is_sample` | vrai s'il s'agit d'un échantillon : pyramide vecteur générée dans une petite zone | "true" \| "false" | + +### tags spécifiques aux stored_data du type `ROK4-PYRAMID-RASTER` + +| tag | description | | +| ------------------- | ------------------------------------------------------------------------------------------------------- | ------ | +| `datasheet_name` | - | - | +| `upload_id` | - | - | +| `proc_int_id` | - | - | +| `vectordb_id` | - | - | +| `proc_pyr_creat_id` | identifiant de l'exécution du traitement "Calcul ou mise à jour de pyramide raster par moissonnage WMS" | uuidv4 | ## `configuration`