Cette section détaille les endpoints pour créer, lister, modifier et supprimer les métriques dans le référentiel.
Lister et rechercher des métriques
Description
Cette requête récupère une liste de métriques, avec la possibilité de filtrer et de paginer les résultats.
GET /v2/metrics
Scope
Pour effectuer cette requête, vous devez posséder le scope suivant : metrics:read.
Paramètres
name (string, optionnel) : Filtre les métriques dont le nom contient cette chaîne.
datasource (string, optionnel) : Filtre sur une source de données spécifique.
limit (integer, optionnel) : Nombre de résultats par page (défaut: 50).
paginationKey (string, optionnel) : Clé pour obtenir la page de résultats suivante (voir gestion de la pagination).
onlyFormula (boolean, optionnel) : Si true, ne retourne que les métriques calculées.
Ces paramètres doivent être ajoutés à la fin de l'URL pour construire la chaîne de requête. Le premier est précédé d'un "?" et les suivants sont séparés par un "&".
Syntaxe générale de la requête GET :
.../metrics?datasource=[source_de_donnees]&limit=[limite]&name=[filtre_nom]
Exemple de requête
# Commande pour lister les 2 premières métriques de la datasource "main"
curl -X GET \
'https://xxx.indaba.api.indasuite.io-base.com/v2/metrics?datasource=main&limit=2' \
-H 'Authorization: Bearer VOTRE_JETON_JWT'
Réponses
Exemple de réponse valide (200 OK) :
{
"data": [
{
"id": "main@cip_50",
"name": "cip_50",
"datasource": "main",
"type": "Raw",
"description": "metric description",
"unit": "C°"
},
{
"id": "main@cip_51",
"name": "cip_51",
"datasource": "main",
"type": "Calculated",
"description": "formula",
"unit": "C°"
}
],
"paginationInfo": {
"count": 2,
"isComplete": false,
"paginationKey": "[id:main@cip_51]"
},
"statusCode": 1010,
"message": "OK"
}
Gestion de la Pagination (isComplete)
Veuillez vous référer au paragraphe de gestion de la pagination.
Erreurs Courantes :
Veuillez vous référer à la liste des erreurs courantes.
Créer une nouvelle métrique
Description
Cette requête ajoute une nouvelle métrique au référentiel.
POST /v2/metrics
Scope
Pour effectuer cette requête, vous devez posséder le scope suivant : metrics:admin.
Paramètres
Ces paramètres sont à intégrer dans le corps de votre requête.
name (string, obligatoire) : Nom de la métrique (doit être unique par datasource).
datasource (string, obligatoire) : Source de données à laquelle la métrique appartient.
type (string, obligatoire) : Type de la métrique (Raw, Calculated, Manual, System).
description (string, optionnel) : Description textuelle de la métrique.
unit (string, optionnel) : Unité de mesure de la métrique.
storageRuleId (uuid, optionnel) : ID de la règle de stockage à appliquer.
accessZones (liste de uuid, optionnel) : Liste des ID des zones d'accès (autorisations) à appliquer.
Les paramètres suivants doivent être fournis dans le corps de la requête, au format JSON.
Syntaxe générale du corps de la requête
{
"name": "nom_unique_par_datasource",
"datasource": "source_de_donnees",
"type": "Raw | Calculated | Manual | System",
"description": "description_de_la_metrique",
"unit": "unite_de_mesure",
"storageRuleId": "uuid_regle_stockage",
"accessZones": [ "uuid_zone_acces_1" ]
}
Exemple de requête
# Commande pour créer une nouvelle métrique
curl -X POST \
--url 'https://xxx.indaba.api.indasuite.io-base.com/v2/metrics' \
# ----- En-têtes -----
-H 'Authorization: Bearer VOTRE_JETON_JWT' \
-H 'Content-Type: application/json' \
# ----- Corps de la requête -----
-d '
{
"name": "test_metric_creation_api",
"datasource": "main",
"type": "Raw",
"description": "Métrique de test créée via API"
}
'
Réponses
Exemple de réponse valide (201 OK):
{
"data": {
"id": "main@test_api",
"name": "test_api",
"datasource": "main",
"type": "Raw",
"storageRule": {
"id": "86ca92b1-dc30-4f32-ac78-b8ab4033d6db",
"name": "TestRule_V1_bf6d15b9",
"deadband": 0,
"validityInSecond": 3600,
"decimalPrecision": 2,
"isDefault": false
},
"accessZones": [
{
"id": "4e1daf3a-9a1c-4c54-a6ea-f826e03c4270",
"name": "#DefaultAccessZoneRead",
"accessType": "Read",
"isDefault": true
}
],
"description": "test description",
"unitSettings": {
"sourceUnit": "m2",
"category": "Area",
"targetUnit1": "m2",
"targetUnit2": "mi2"
},
"source": ""
},
"resultCode": 1010,
"message": "OK"
}
Erreurs Courantes :
Veuillez vous référer à la liste des erreurs courantes.
Obtenir les détails d'une métrique
Description
Cette requête récupère la configuration complète d'une seule métrique en utilisant son identifiant unique.
GET /v2/metrics/{metricId}
Scope
Pour effectuer cette requête, vous devez posséder le scope suivant : metrics:read.
Paramètres
metricId (string, obligatoire) : Identifiant unique de la métrique au format datasource@metricName.
Cette requête utilise un paramètre de chemin, qui est intégré directement dans l'URL.
Syntaxe générale de la requête GET :
.../metrics/[datasource]@[nom_de_la_metrique]
Exemple de requête
# Commande pour obtenir la métrique "main@test_metric_f0fb6f7c"
curl -X GET 'https://xxx.indaba.api.indasuite.io-base.com/v2/metrics/main@test_metric_f0fb6f7c'
-H 'Authorization: Bearer VOTRE_JETON_JWT'
Réponses
Exemple de réponse valide (200 OK) :
{
"data": {
"id": "main@test_metric_f0fb6f7c",
"name": "test_metric_f0fb6f7c",
"datasource": "main",
"type": "Raw",
"accessZones": [],
"description": "Métrique de test",
"unitSettings": {}
},
"statusCode": 1010,
"message": "OK"
}
Erreurs Courantes :
Veuillez vous référer à la liste des erreurs courantes.
Mettre à jour une métrique
Description
Cette requête met à jour la configuration d'une métrique existante.
PUT /v2/metrics/{metricId}
Scope
Pour effectuer cette requête, vous devez posséder le scope suivant : metrics:admin.
Paramètres
metricId (string, obligatoire) : Identifiant de la métrique à mettre à jour.
Cette requête utilise un paramètre de chemin, qui est intégré directement dans l'URL.
Syntaxe générale de l'URL :
.../metrics/[datasource]@[nom_de_la_metrique]
Corps de la requête
Les champs suivants doivent être fournis dans le corps de la requête, au format JSON. Ils sont identiques à ceux de la création de métrique.
name (string, obligatoire) : Nom de la métrique (doit être unique par datasource).
datasource (string, obligatoire) : Source de données à laquelle la métrique appartient.
type (string, obligatoire) : Type de la métrique (Raw, Calculated, Manual, System).
description (string, optionnel) : Description textuelle de la métrique.
unit (string, optionnel) : Unité de mesure de la métrique.
storageRuleId (uuid, optionnel) : ID de la règle de stockage à appliquer.
accessZones (liste de uuid, optionnel) : Liste des ID des zones d'accès (autorisations) à appliquer.
Syntaxe générale du corps de la requête :
{
"name": "nom_unique_par_datasource",
"datasource": "source_de_donnees",
"type": "Raw | Calculated | Manual | System",
"description": "description_de_la_metrique",
"unit": "unite_de_mesure",
"storageRuleId": "uuid_regle_stockage",
"accessZones": [ "uuid_zone_acces_1" ]
}
Exemple de requête
# Commande pour mettre à jour la description d'une métrique
curl -X PUT \
--url 'https://xxx.indaba.api.indasuite.io-base.com/v2/metrics/main@test_metric_f0fb6f7c' \
# ----- En-têtes -----
-H 'Authorization: Bearer VOTRE_JETON_JWT' \
-H 'Content-Type: application/json' \
# ----- Corps de la requête -----
-d '
{
"name": "test_metric_f0fb6f7c",
"datasource": "main",
"type": "Raw",
"description": "Métrique de test mise à jour"
}
'
Réponses
Exemple de réponse valide (200 OK) :
{
"data": {
"id": "main@test_metric_f0fb6f7c",
"name": "test_metric_f0fb6f7c",
"datasource": "main",
"type": "Raw",
"description": "Métrique de test mise à jour",
"unitSettings": {}
},
"statusCode": 1010,
"message": "OK"
}
Erreurs Courantes :
Veuillez vous référer à la liste des erreurs courantes.
Supprimer une métrique
Description
Cette requête supprime complètement une métrique et tout son historique de valeurs. Attention, cette action est irréversible.
DELETE /v2/metrics/{metricId}
Scope
Pour effectuer cette requête, vous devez posséder le scope suivant : metrics:admin.
Paramètres
metricId (string, obligatoire) : ID de la métrique à supprimer (datasource@metricName).
Cette requête utilise un paramètre de chemin, qui est intégré directement dans l'URL.
Syntaxe générale de la requête DELETE :
.../metrics/[datasource]@[nom_de_la_metrique]
Exemple de requête
# Commande pour supprimer la métrique 'main@test_metric_f0fb6f7c_renamed'
curl -X DELETE \
'https://xxx.indaba.api.indasuite.io-base.com/v2/metrics/main@test_metric_f0fb6f7c_renamed' \
-H 'Authorization: Bearer VOTRE_JETON_JWT'
Réponses
Exemple de réponse valide (200 OK) :
{
"statusCode": 1010,
"message": "OK"
}
Erreurs Courantes :
Veuillez vous référer à la liste des erreurs courantes.
Renommer une métrique
Description
Cette requête permet de renommer une métrique existante. Cette action doit être utilisée avec précaution.
PUT /v2/metrics/{metricId}/rename
Scope
Pour effectuer cette requête, vous devez posséder le scope suivant : metrics:support.
Paramètres
metricId (string, obligatoire) : ID de la métrique à renommer.
newName (string, obligatoire) : Le nouveau nom à donner à la métrique.
Cette requête utilise un paramètre de chemin, qui est intégré directement dans l'URL.
Syntaxe générale de l'URL :
.../metrics/[datasource]@[nom_actuel_metrique]/rename
Corps de la requête :
Le champ newName doit être fourni dans le corps de la requête, au format JSON.
Syntaxe générale du corps de la requête :
{
"newName": "nouveau_nom_de_la_metrique"
}
Exemple de requête
# Commande pour renommer une métrique
curl -X PUT \
--url 'https://xxx.indaba.api.indasuite.io-base.com/v2/metrics/main@test_metric_f0fb6f7c/rename' \
# ----- En-têtes -----
-H 'Authorization: Bearer VOTRE_JETON_JWT' \
-H 'Content-Type: application/json' \
# ----- Corps de la requête -----
-d '
{
"newName": "test_metric_f0fb6f7c_renamed"
}
'
Réponses
Exemple de réponse valide (200 OK) :
{
"statusCode": 1010,
"message": "OK"
}
Erreurs Courantes :
Veuillez vous référer à la liste des erreurs courantes.
Modifier partiellement une métrique (Patch)
Description
Cette requête permet de modifier de manière ciblée la configuration d'une métrique, comme ses zones d'accès ou sa règle de stockage, sans avoir à renvoyer toute la configuration de la métrique.
PATCH /v2/metrics/{metricId}
Scope
Pour effectuer cette requête, vous devez posséder le scope suivant : metrics:admin.
Paramètres
metricId (string, obligatoire) : Identifiant unique de la métrique au format datasource@metricName.
Cette requête utilise un paramètre de chemin, qui est intégré directement dans l'URL.
Syntaxe générale de l'URL :
.../metrics/[datasource]@[nom_de_la_metrique]
Corps de la requête
accessZonesId (liste de uuid, optionnel) : Remplace la liste des zones d'accès associées à la métrique par celle fournie.
storageRuleId (uuid, optionnel) : Change la règle de stockage associée à la métrique.
Les champs suivants doivent être fournis dans le corps de la requête, au format JSON. Vous pouvez fournir un ou plusieurs champs.
Syntaxe générale du corps de la requête :
{
"accessZonesId": [ "uuid_zone_1", "uuid_zone_2" ],
"storageRuleId": "uuid_de_la_regle_de_stockage"
}
Exemple de requête
# Commande pour associer des zones d'accès à une métrique
curl -X PATCH \
--url 'https://xxx.indaba.api.indasuite.io-base.com/v2/metrics/main@test_metric_f0fb6f7c' \
# ----- En-têtes -----
-H 'Authorization: Bearer VOTRE_JETON_JWT' \
-H 'Content-Type: application/json' \
# ----- Corps de la requête -----
-d '
{
"accessZonesId": [
"8f8ccdb5-8918-4710-bbfa-1bb7260f257e",
"14567e2c-70a6-41fd-806e-3be66b4129b7"
]
}
'
Réponses
Exemple de réponse valide (200 OK):
{
"statusCode": 1010,
"message": "OK"
}
Erreurs Courantes :
Veuillez vous référer à la liste des erreurs courantes.
Exporter le référentiel de métriques
Description
Cette requête permet de télécharger le référentiel complet des métriques d'une source de données dans un fichier, généralement au format Excel.
GET /v2/metrics/export/{datasource}
Scope
Pour effectuer cette requête, vous devez posséder le scope suivant : metrics:read.
Paramètres
datasource (string, obligatoire) : La source de données dont le référentiel de métriques doit être exporté.
Cette requête utilise un paramètre de chemin, qui est intégré directement dans l'URL.
Syntaxe générale de la requête GET :
.../metrics/export/[source_de_donnees]
Exemple de requête
# Commande pour exporter les métriques de la datasource "main" # et sauvegarder le résultat dans un fichier local.
curl -X GET \
'https://xxx.indaba.api.indasuite.io-base.com/v2/metrics/export/main' \
-H 'Authorization: Bearer VOTRE_JETON_JWT' \
-o 'export_metrics.xlsx'
Réponses
Exemple de réponse valide (200 OK)
La réponse ne contient pas de JSON. Le corps de la réponse est le contenu binaire du fichier d'export (ex: .xlsx), accompagné des en-têtes HTTP appropriés (Content-Type et Content-Disposition).
Erreurs Courantes :
Veuillez vous référer à la liste des erreurs courantes.
Importer un référentiel de métriques
Description
Cette requête permet de créer ou de mettre à jour en masse des métriques dans une source de données à partir d'un fichier.
POST /v2/metrics/import/{datasource}
Scope
Pour effectuer cette requête, vous devez posséder le scope suivant : metrics:admin.
Paramètres
datasource (string, obligatoire) : La source de données dans laquelle les métriques du fichier seront importées.
Cette requête utilise un paramètre de chemin, qui est intégré directement dans l'URL.
Syntaxe générale de la requête POST :
.../metrics/import/[source_de_donnees]
Corps de la requête
Cette requête doit être au format multipart/form-data et contenir une seule partie :
file (fichier, obligatoire) : Le fichier (généralement Excel) contenant les métriques à importer.
Exemple de requête
# Commande pour importer un fichier de métriques dans la datasource "main"
curl -X POST \
--url 'https://xxx.indaba.api.indasuite.io-base.com/v2/metrics/import/main' \
# ----- En-têtes -----
-H 'Authorization: Bearer VOTRE_JETON_JWT' \
-H 'Content-Type: multipart/form-data' \
# ----- Fichier à envoyer -----
-F 'file=@/chemin/vers/mon_referentiel.xlsx'
Réponses
Exemple de réponse valide (200 OK)
Une réponse 200 OK sans corps de message indique que l'import a été traité avec succès.
Erreurs Courantes :
Veuillez vous référer à la liste des erreurs courantes.
Gestion de la Pagination (isComplete)
Pour garantir de bonnes performances, l'API peut diviser les réponses contenant un grand nombre de résultats (par exemple, une longue liste de métriques) 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 :
Récupérez la valeur du champ "paginationKey" dans la réponse que vous venez de recevoir.
Effectuez une nouvelle requête en y ajoutant "paginationKey" comme paramètre et en attribuant à ce paramètre la valeur récupérée.
Répétez ce processus jusqu'à ce que la réponse finale contienne "isComplete" : true.
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. Cela peut arriver pour deux raisons :
Votre jeton n'a pas les droits (scope) nécessaires (par exemple, vous tentez d'écrire des données sans avoir le scope metrics:write).
Votre jeton a le bon scope, mais votre utilisateur (ou compte de service) n'est pas rattaché à une autorisation qui donne accès à la métrique demandée.
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.