Passer au contenu principal

Gestion des éléments (items)

Mis à jour il y a plus d’une semaine

Cette section décrit les endpoints de l'API permettant de créer, lister, rechercher, modifier et supprimer les éléments de vos arborescences fonctionnelles.

Rappel : Un "item" est un élément contenu dans votre arborescence. Il peut s'agir d'un dossier ou d'une métrique.

Exporter les éléments d'une arborescence

Description

Cette requête vous permet de télécharger une liste des différents types d'éléments présents dans une arborescence.

Get v2/data-structures/{data_structure_id}/export

Scope

Pour effectuer cette requête, vous devez posséder le scope metadata:read.

Paramètres

Ce paramètre doit être ajouté à l'URL pour construire la chaîne de requête :

/v2/data-structures/{data_structure_id}/export

Exemple de requête :

# Commande pour exporter les éléments d'une arborescence 
 curl -X GET \ 
   'https://xxx.indaba.api.indasuite.io-base.com/v2/data-structures/f455a22f-e9e3-4c1b-a5a9-87b1cb0a7dc4/export' \ 
   -H 'Authorization: Bearer VOTRE_JETON_JWT'

Exporter les éléments d'une arborescence au format plat

Description

Cette requête permet de télécharger le référentiel complet d'une arborescence sous une forme "plate" (une simple liste).

GET /v2/data-structures/{data_structure_id}/export/tree

Scope

Pour effectuer cette requête, vous devez posséder le scope metadata:read.

Paramètres

Ce paramètre doit être ajouté à l'URL pour construire la chaîne de requête :

/v2/data-structures/{data_structure_id}/export/tree

Exemple de requête

# Commande pour exporter les éléments d'une arborescence (format plat)
 curl -X GET \ 
   'https://xxx.indaba.api.indasuite.io-base.com/v2/data-structures/f455a22f-e9e3-4c1b-a5a9-87b1cb0a7dc4/export/tree' \ 
   -H 'Authorization: Bearer VOTRE_JETON_JWT'

Importer une arborescence depuis un fichier excel

Description

Cette requête vous permet d'importer le contenu d'une arborescence depuis un fichier excel.

Remarque : Le fichier d'import doit respecter une structure définie. Si vous n'êtes pas familiers avec cette fonctionnalité, consultez l'article portant sur l'import/export d'une arborescence fonctionnelle.

Post /v2/data-structures/{data_structure_id}/import

Scope

Pour effectuer cette requête, vous devez posséder le scope metadata:admin.

Paramètres

Ce paramètre doit être ajouté à l'URL pour construire la chaîne de requête tel que :

/v2/data-structures/{data_structure_id}/import

Corps de la requête

  • file (string ($binary) ) : chemin vers le fichier excel dont on souhaite importer le contenu.

Exemple de requête : 

# Commande pour importer le contenu d'une arborescence à partir d'un fichier 
 curl -X 'POST' \ 
   'https://xxx.indaba.api.indasuite.io-base.com/v2/data-structures/66731055-a2f2-4890-8212-217f7d653d01/import' \ 
 
   # ----- En-têtes ----- 
   -H 'accept: application/json' \ 
   -H 'Authorization: Bearer VOTRE_JETON_JWT' \ 
   -H 'Content-Type: multipart/form-data' \ 
 
   # ----- Fichier à envoyer ----- 
   -F 'file=@/chemin/vers/DemoGTB-2025-07-16.xlsx;type=application/vnd.openxmlformats-officedocument.spreadsheetml.sheet'

Réponses :

Exemple de réponse valide (200 ok) :

{ 
   "resultCode": 2010, 
   "message": "OK" 
 }

Erreurs courantes :

Veuillez vous référer à la liste des erreurs courantes.

Erreur 400 spécifique :

Si le fichier d'import n'est pas valide, l'erreur suivante apparaîtra : 

{ 
   "errors": [], 
   "resultCode": 2122, 
   "message": "Type is used" 
 }

Lister les éléments d'une arborescence

Description

Cette requête retourne la liste de tous les éléments d'une arborescence, en incluant pour chacun leurs informations respectives et notamment leurs identifiants (ID), qui sont nécessaires pour d'autres requêtes.

Get /v2/data-structures/{data_structure_id}/items

Scope

Pour effectuer cette requête, vous devez posséder le scope metadata:read.

Paramètres

  • data_structure_id (string, obligatoire) : ID attribué à l'arborescence.

    Vous pouvez retrouver l'ID d'une arborescence dans le corps de réponse à la requête Get v2/data-structures ou dans le corps de réponse de la création d'une nouvelle arborescence.

    Les paramètres suivants permettent d'applique un filtre sur la recherche :

  • typeId (string, optionnel) : Filtre les résultats pour ne retourner que les éléments associés à un type spécifique, identifié par son ID.

  • isMetric (boolean, optionnel) : Permet de filtrer les éléments en fonction de leur type (si c'est un type metric ou non) peut prendre deux valeurs (true ou false).

  • displayParents (boolean, optionnel) : permet d'indiquer si l'on souhaite affiche les parents de chaque élément dans la réponse. peut prendre deux valeurs (true ou false).

  • paginationKey (string, optionnel) : Clé pour obtenir la page de résultats suivante (voir gestion de la pagination)

  • limit (integer, optionnel) : limite de résultats à afficher

    En complément de ces filtres, un paramètre "query" est disponible pour vous permettre de construire une expression de filtrage plus précise. Sa syntaxe spécifique et ses fonctions de recherche sont détaillées ci-dessous.

    Pour construire votre expression, vous disposez :

    • d'opérateurs logiques et de comparaison

    • de fonctions de recherche

    Liste des opérateurs disponibles :

    Comparaison :

Description

Syntaxe à utiliser

Égal à

==

Différent de

!=

Supérieur à

>

Inférieur à

<

Supérieur ou égal à

>=

Inférieur ou égal à

<=

Logiques :

Opérateur "ET"

&&

Opérateur "OU"

||

Fonctions de recherche à utiliser

Pour créer votre expression dans le champ "query", vous devez utiliser les fonctions de recherche suivantes.
​


​searchProperty([type du parent], [nom de la propriété à vérifier])


Cette fonction filtre les éléments en se basant sur les propriétés de l'un de leurs parents dans l'arborescence. Elle ne retournera que les éléments dont le parent correspond aux critères que vous spécifiez.

  • type_id (string | uuid, obligatoire) : L'identifiant ou le nom du type du parent que vous ciblez.

  • nom_de_la_propriete (string, obligatoire) : Le nom de la propriété du parent que vous voulez vérifier.
    ​


​.contains("valeur")
​
Cette méthode s'applique à une propriété de l'élément recherché et vérifie si sa valeur contient la chaîne de caractères spécifiée.

On aura donc [nom de la propriété de l'élément recherché].contains("valeur")

.StartsWith("valeur")

Cette méthode s'applique à une propriété de l'élément recherché et vérifie si sa valeur commence par la chaîne de caractères spécifiée.

On aura donc [nom de la propriété de l'élément recherché].StartsWith("valeur")

.EndsWith("valeur")

Cette méthode s'applique à une propriété de l'élément recherché et vérifie si sa valeur termine par la chaîne de caractères spécifiée.

On aura donc [nom de la propriété de l'élément recherché].EndsWith("valeur")

Exemple d'expression à mettre dans "query" :
​
On souhaite récupérer les éléments de l'arborescence qui remplissent les deux conditions suivantes :
​
- Ils doivent avoir un parent de type "08fcddd6-5951-4f06-a3df-fd9eea1bb8a3" dont la propriété "test_propriete" vaut "Pau".
​
- Leur propre propriété unit doit contenir la lettre "c".
​

Requête à indiquer :


​searchProperty("08fcddd6-5951-4f06-a3df-fd9eea1bb8a3", "test_propriete") == "Pau" && unit.contains("c")

Décomposition :

  • searchProperty("08fcddd6-5951-4f06-a3df-fd9eea1bb8a3", "test_propriete") == "Pau" : Cette condition indique que l'on souhaite avoir les éléments ayant un parent avec le type indiqué et la bonne valeur pour la propriété "test_propriete".

  • && : L'opérateur "ET" pour ajouter une condition supplémentaire.
    ​

  • unit.contains("c") : Cette partie filtre les résultats précédents pour ne garder que ceux dont la propriété "unit" contient la lettre "c".

Ces paramètres doivent être ajoutés à l'URL pour construire la chaîne de requête :

/v2/data-structures/{data_structure_id}/items?isMetric=[]&displayParents=[]&limit[]&query=[]

Exemple de requête

# Commande pour rechercher des éléments qui ont un parent de type "Silot" avec la propriété "test_propriete" égale à "Pau" 
# - ET dont l'unité contient la lettre "c". 
 
curl -X 'GET' \ 
  'https://xxx.indaba.api.indasuite.io-base.com/v2/data-structures/f455a22f-e9e3-4c1b-a5a9-87b1cb0a7dc4/items?isMetric=true&displayParents=false&limit=50&query=searchProperty("Silot", "test_propriete") = "Pau" and unit.contains("c")' \ 
 
  # ----- En-têtes ----- 
  -H 'accept: application/json' \ 
  -H 'Authorization: Bearer VOTRE_JETON_JWT'

Réponses

Exemple de réponse valide (200 OK) : 

{ 
   "data": [ 
     { 
       "id": "3d24ece8-d815-4e2a-a31d-9c34cbc29035", 
       "dataStructureId": "f455a22f-e9e3-4c1b-a5a9-87b1cb0a7dc4", 
       "typeId": "21c4451d-4a20-4ebc-9667-fb29e73825fa", 
       "parentId": "batiments-elementaire", 
       "label": "nj26uv_temperature_elementaire", 
       "metric": { 
         "id": "main@nj26uv_temperature_elementaire", 
         "name": "nj26uv_temperature_elementaire", 
         "datasource": "main", 
         "unit": "°C", 
         "type": "Raw" 
       }, 
       "options": { 
         "indabaId": "main@nj26uv_temperature_elementaire", 
         "indabaLabel": "Name" 
       }, 
       "isTypeMetric": true, 
       "hasError": false 
     } 
   ], 
   "paginationInfo": { 
     "count": 1, 
     "total": 1, 
     "isComplete": true 
   }, 
   "resultCode": 2010, 
   "message": "OK" 
 }

Gestion de la pagination

Pour garantir de bonnes performances, l'API peut diviser les réponses contenant un grand nombre de résultats en plusieurs "pages". Certaines réponses contiennent un champ booléen nommé "isComplete", dans l'objet "paginationInfo" pour gérer ce cas.

  • Si isComplete est true : Vous avez reçu toutes les données.

  • Si isComplete est false : Il reste des données à récupérer. Pour obtenir la suite :

    1. Récupérez la valeur du champ "paginationKey" dans la réponse que vous venez de recevoir.

    2. Effectuez une nouvelle requête en y ajoutant "paginationKey" comme paramètre et en attribuant à ce paramètre la valeur récupérée.

    3. Répétez ce processus jusqu'à ce que la réponse finale contienne "isComplete" : true.

Erreurs courantes

Veuillez vous référer à la liste des erreurs courantes.

Ajouter un nouvel élément dans une arborescence

Description

Cette requête vous permet d'ajouter un nouvel élément dans une arborescence.

Post v2/data-structures/{data_structure_id}/items

Scope

Pour effectuer cette requête, vous devez posséder le scope "metadata:admin".

Paramètres

Ce paramètre doit être ajouté à l'URL pour construire la chaîne de requête :

/v2/data-structures/{data_structure_id}/items

Corps de la requête

En fonction de l'élément que vous souhaitez créer, le corps de la requête comprendra des champs différents.

Champs communs à tous les éléments :

  • label : nom d'affichage du nouvel élément dans l'arborescence

  • properties : si le type choisie contient des propriétés, vous pouvez affecter une valeur à ces propriétés dans le corps de la requête. Voir les exemple ci-dessous.

    exemple :

{

"id": "F0",

"typeId": "63c80ffc-321e-4a4d-ab44-c643c4ff156d",

"label": "France",

"properties": {

"name": "name country",

"description": "description country",

"hasDescription": true,

"count": 12

}

}

Champs spécifiques :

  • Si vous souhaitez créer un élément avec un (ou des) parent(s) dans l'arborescence

{

"id": "R0",

"typeId": "f33d478f-04e9-4613-b094-74df6c62abcb",

"parentId": "F0",

"label": "Region",

"properties": {

"name": "name region"

}

}

  • si vous souhaitez créer un élément de type métrique

    • options:

      • indabaId : identifiant indaba de la métrique (datasource@name)

      • IndabaLabel : nom de la métrique

{

"typeId": "6975832e-34f3-42e3-aedb-b16f5802f89a",

"parentId": "XXXXXXX",

"options": {

"indabaId": "datasource@name",

"indabaLabel": "Name"

}

}

Exemple de requête

# Commande pour créer un nouvel item dans une arborescence
 curl -X 'POST' \ 
   'https://xxx.indaba.api.indasuite.io-base.com/v2/data-structures/f455a22f-e9e3-4c1b-a5a9-87b1cb0a7dc4/items' \ 
 
   # ----- En-têtes ----- 
   -H 'accept: application/json' \ 
   -H 'Authorization: Bearer VOTRE_JETON_JWT' \ 
   -H 'Content-Type: application/json' \ 
 
   # ----- Corps de la requête ----- 
   -d ' 
   { 
     "typeId": "38caa3e6-11f0-4fb9-ae34-5b168558a17a", 
     "label": "doc", 
     "properties": { 
       "test_propriete": "valeur2" 
     } 
   } 
   '

Réponses

exemple de réponde valide (200 OK) : 

{ 
   "data": { 
     "id": "_doc", 
     "dataStructureId": "f455a22f-e9e3-4c1b-a5a9-87b1cb0a7dc4", 
     "typeId": "38caa3e6-11f0-4fb9-ae34-5b168558a17a", 
     "label": "doc", 
     "properties": { 
       "test_propriete": "valeur2" 
     }, 
     "isTypeMetric": false, 
     "hasError": false 
   }, 
   "resultCode": 2010, 
   "message": "OK" 
 }

Erreurs courantes

Veuillez vous référer à la liste des erreurs courantes.

Mettre à jour un élément existant

Put /v2/data-structures/{data_structure_id}/items/{item_id}

Scope

Pour effectuer cette requête, vous devez posséder le scope metadata:admin.

Paramètres

Ces paramètres doivent être ajoutés à l'URL pour construire la chaîne de requête :

v2/data-structures/{data_structure_id}/items/{item_id}

Corps de la requête

Le corps de la requête est similaire à l'ajout d'un nouvel élément.

Exemple de requête

# Commande pour mettre à jour un élément existant dans une structure de données 
 curl -X 'PUT' \ 
   'https://xxx.indaba.api.indasuite.io-base.com/v2/data-structures/f455a22f-e9e3-4c1b-a5a9-87b1cb0a7dc4/items/batiments-elementaire' \ 
 
   # ----- En-têtes ----- 
   -H 'accept: application/json' \ 
   -H 'Authorization: Bearer VOTRE_JETON_JWT' \ 
   -H 'Content-Type: application/json' \ 
 
   # ----- Corps de la requête ----- 
   -d ' 
   { 
     "typeId": "38caa3e6-11f0-4fb9-ae34-5b168558a17a", 
     "label": "label_modif", 
     "properties": { 
       "name": "name country", 
       "description": "description country", 
       "hasDescription": true, 
       "count": 12 
     } 
   } 
   '

Réponses

Exemple de réponse valide (200 OK) 

{ 
   "data": { 
     "id": "batiments-elementaire", 
     "dataStructureId": "f455a22f-e9e3-4c1b-a5a9-87b1cb0a7dc4", 
     "typeId": "38caa3e6-11f0-4fb9-ae34-5b168558a17a", 
     "label": "label_modif", 
     "properties": {}, 
     "isTypeMetric": false, 
     "hasError": false 
   }, 
   "resultCode": 2010, 
   "message": "OK" 
 }

Erreurs courantes

Veuillez vous référer à la liste des erreurs courantes.

Supprimer un élément d'une arborescence

Cette requête supprime un élément ainsi que tous ses descendants dans l'arborescence.

Attention, cette action est irréversible.

DELETE /v2/data-structures/{data_structure_id}/items/{item_id}

Scope

Pour effectuer cette requête, vous devez posséder le scope suivant : metadata:admin.

Paramètres

Ces paramètres doivent être ajoutés à l'URL pour construire la chaîne de requête :

v2/data-structures/{data_structure_id}/items/{item_id}

Exemple de requête

# Commande pour supprimer un élément spécifique d'une arborescence
 curl -X 'DELETE' \ 
   'https://xxx.indaba.api.indasuite.io-base.com/v2/data-structures/67337415-6bcb-4c21-b0f5-8253d68b6e80/items/_sited' \ 
 
   # ----- En-têtes ----- 
   -H 'accept: application/json' \ 
   -H 'Authorization: Bearer VOTRE_JETON_JWT'

Réponses

exemple de réponse valide (200 OK) : 

{ 
   "resultCode": 2010, 
   "message": "OK" 
 }

Erreurs courantes

Veuillez vous référer à la liste des erreurs courantes.

Erreurs courantes

Vous rencontrerez principalement les codes d'erreur HTTP suivants :

  • 400 Bad Request : Votre requête est malformée. Cela peut être dû à un paramètre manquant, un type de donnée incorrect ou un JSON invalide. Le corps de la réponse contiendra un tableau errors détaillant le problème.
    ​

    { 
    "errors": [ 
    { 
    "error": "Type_De_L_Erreur", 
    "message": "Description détaillée de l'erreur spécifique." 
    } 
    ], 
    "statusCode": 1050, 
    "message": "Invalid request" 
    }

  • 401 Unauthorized : Votre jeton d'authentification (JWT) est manquant, invalide ou expiré. Vous devez obtenir un nouveau jeton valide.

  • 403 Forbidden : Votre jeton d'authentification est valide, mais vous n'avez pas les droits nécessaires pour cette action.

    Votre jeton n'a pas les droits (scope) nécessaires (par exemple, vous tentez de créer une arborescence sans avoir le scope metadata:admin).

  • 404 Not Found : La ressource que vous essayez d'atteindre n'existe pas. Cela se produit typiquement si vous utilisez un ID incorrect ou si vous demandez une métrique qui n'existe pas.

Article suivant

Avez-vous trouvé la réponse à votre question ?