Cette section détaille les endpoints de l'API permettant de créer, lister, modifier et supprimer les modèles de formules au sein d'une arborescence.
Rappel : Si vous n'êtes pas familiers avec cette fonctionnalité, consultez la documentation relative aux modèles de formules.
Récupérer la liste des formules génériques présentes dans l'arborescence
Cette requête renvoie une liste avec les différentes formules génériques présentes dans l'arborescence.
Get /v2/data-structures/{data_structure_id}/formulas
Scope
Cette requête nécessite d'avoir le scope metadata:read.
Paramètres
data_structure_id (string, obligatoire) : ID attribué à l'arborescence.
Cet ID peut être récupéré via la requête
GET v2/data-structures
ou lors de la création d'une nouvelle arborescence avecPOST v2/data-structures
.
Ce paramètre doit être ajouté à l'URL pour construire la chaîne de requête :
/v2/data-structures/{data_structure_id}/formulas
Exemple de requête
# Commande pour lister les formules d'une structure de données
curl -X 'GET' \
'https://xxx.indaba.api.indasuite.io-base.com/v2/data-structures/67337415-6bcb-4c21-b0f5-8253d68b6e80/formulas' \
# ----- En-têtes -----
-H 'accept: application/json' \
-H 'Authorization: Bearer VOTRE_JETON_JWT'
Réponses
exemple de réponse valide (200 OK) :
{
"data": [
{
"id": "9b034dcf-0e5b-4b45-908a-1c07ff7880c1",
"metricTypeId": "0b3f2349-9b17-45d9-b7c4-0b47d0f39960",
"options": "Name",
"label": "DOPEN",
"metricTemplate": "main@DOPEN_{code_site}",
"version": 3,
"formula": {
"formulaTemplate": "if([id_moy]>0 or [id_moy]>0, 1, 0)",
"description": "Formule vérifiant si la diode du site {code_site} est ouverte ou non.",
"schedule": "0 6 * * *",
"timezone": "Europe/Paris",
"resultType": "REAL",
"sourceValidityInSecond": 0
}
}
],
"resultCode": 2010,
"message": "OK"
}
Erreurs courantes
Veuillez vous référer à la liste des erreurs courantes.
Récupérer les formules génériques associées à un type
Cette requête renvoie une liste avec les différentes formules génériques présentes dans une arborescence, au sein d'un type particulier.
GET /v2/data-structures/{data_structure_id}/types/{type_id}/formulas
Scope
Pour effectuer cette requête, vous devez posséder le scope suivant : metadata:read.
Paramètres
data_structure_id (string, obligatoire) : ID attribué à l'arborescence.
Cet ID peut être récupéré via la requête
GET v2/data-structures
ou lors de la création d'une nouvelle arborescence avecPOST v2/data-structures
.
type_id (string, obligatoire) : ID attribué au type d'élément.
Cet ID peut être récupéré via la requête
GET /v2/data-structures/{data_structure_id}/types
ou suite à la création d'un nouveau type avecPost v2/data-structures/{data_structure_id}/types
.
Ces paramètres doivent être ajoutés à l'URL pour construire la chaîne de requête :
.../data-structures/{data_structure_id}/types/{type_id}/formulas
Exemple de requête
# Commande pour lister les formules d'un type spécifique
curl -X 'GET' \
'https://xxx.indaba.api.indasuite.io-base.com/v2/data-structures/67337415-6bcb-4c21-b0f5-8253d68b6e80/types/e9910c2b-83e9-4954-a1dd-abca2d833999/formulas' \
# ----- En-têtes -----
-H 'accept: application/json' \
-H 'Authorization: Bearer VOTRE_JETON_JWT'
Réponses
exemple de réponse valide (200 ok) :
{
"data": [
{
"id": "9b034dcf-0e5b-4b45-908a-1c07ff7880c1",
"metricTypeId": "0b3f2349-9b17-45d9-b7c4-0b47d0f39960",
"options": "Name",
"label": "DOPEN",
"metricTemplate": "main@DOPEN_{code_site}",
"version": 3,
"formula": {
"formulaTemplate": "if([id_moy]>0 or [id_moy]>0, 1, 0)",
"description": "Formule vérifiant si la diode du site {code_site} est ouverte ou non.",
"schedule": "0 6 * * *",
"timezone": "Europe/Paris",
"resultType": "REAL",
"sourceValidityInSecond": 0
}
}
],
"resultCode": 2010,
"message": "OK"
}
Erreurs courantes
Veuillez vous référer à la liste des erreurs courantes.
Créer un nouveau modèle de formules
Description
Cette requête vous permet d'ajouter un nouveau modèle de formules à un type donné dans votre arborescence.
Post /v2/data-structures/{data_structure_id}/types/{type_id}/formulas
Scope
Pour effectuer cette requête, vous devez posséder le scope suivant : metadata:admin.
Paramètres
data_structure_id (string, obligatoire) : ID attribué à l'arborescence.
Cet ID peut être récupéré via la requête
GET v2/data-structures
ou lors de la création d'une nouvelle arborescence avecPOST v2/data-structures
.
type_id (string, obligatoire) : ID attribué au type d'élément.
Cet ID peut être récupéré via la requête
GET /v2/data-structures/{data_structure_id}/types
ou suite à la création d'un nouveau type avecPost v2/data-structures/{data_structure_id}/types
.
Ces paramètres doivent être ajoutés à l'URL pour construire la chaîne de requête :
/v2/data-structures/{data_structure_id}/types/{type_id}/formulas
Corps de la requête
{
"label": "string",
"metricTypeId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"options": "Custom",
"formula": {
"resultType": "BOOL",
"schedule": "string",
"sourceValidityInSecond": 0,
"timezone": "string",
"description": "string",
"unit": "string",
"formulaTemplate": "string"
},
"metricTemplate": "string"
}
Dans le corps de requête, renseignez les informations nécessaires à la création du modèle de formules :
label : label du modèle
metricTypeId : ID du type "métrique" souhaité présent dans l'arborescence. Les formules (métriques calculées) générées seront ajoutées dans l'arborescence avec le type "métrique" défini ici.
formula :
resultType : type de résultat attendu.
Peut prendre les valeurs BOOL, REAL ou INT.schedule : périodicité, une expression CRON est attendue
sourceValidityInSecond : permet de s'assurer que le calcul ne s'exécute qu'avec des données récentes, en bloquant l'opération si les valeurs d'entrée sont plus anciennes que la durée spécifiée afin de garantir la fiabilité du résultat.
Remarque : Indiquer "0" pour désactiver cette fonctionnalité.
timezone : fuseau horaire
description
unit : unité à associer aux formules génériques
formulaTemplate : expression de la formule générique
metric template : nom générique des formules (métriques calculées) générées par le modèle.
Attention, ici il est important d'indiquer la base de données dans laquelle vont être stockées les formules.
On a donc la syntaxe suivante :
[base de données]@{propriete_arbo}.documentation
Exemple de requête
# Commande pour créer une nouvelle formule générique dans un type
curl -X 'POST' \
'https://xxx.indaba.api.indasuite.io-base.com/v2/data-structures/67337415-6bcb-4c21-b0f5-8253d68b6e80/types/e9910c2b-83e9-4954-a1dd-abca2d833999/formulas' \
# ----- En-têtes -----
-H 'accept: application/json' \
-H 'Authorization: Bearer VOTRE_JETON_JWT' \
-H 'Content-Type: application/json' \
# ----- Corps de la requête -----
-d '
{
"label": "test_import",
"metricTypeId": "0b3f2349-9b17-45d9-b7c4-0b47d0f39960",
"options": "Custom",
"formula": {
"resultType": "REAL",
"schedule": "*/2 * * * *",
"sourceValidityInSecond": 0,
"timezone": "Europe/Paris",
"description": "test_description",
"unit": "C",
"formulaTemplate": "if([id_moy]>0 or [id_moy]>0, 1, 0)"
},
"metricTemplate": "main@{code_site}.val"
}
'
Réponses
exemple de réponse valide (200 ok)
{
"data": {
"id": "b4ba1278-4e91-44b2-b6c5-8ced3d8fc1eb",
"metricTypeId": "0b3f2349-9b17-45d9-b7c4-0b47d0f39960",
"options": "Custom",
"label": "test_import",
"metricTemplate": "main@{code_site}.val",
"version": 1,
"formula": {
"formulaTemplate": "if([id_moy]>0 or [id_moy]>0, 1, 0)",
"description": "test_description",
"unit": "C",
"schedule": "*/2 * * * *",
"timezone": "Europe/Paris",
"resultType": "REAL",
"sourceValidityInSecond": 0
}
},
"resultCode": 2010,
"message": "OK"
}
Erreurs courantes
Veuillez vous référer à la liste des erreurs courantes.
Mettre à jour un modèle de formules génériques
Description
Cette requête vous permet d'ajouter un nouveau modèle de formules à un type donné dans votre arborescence.
Put /v2/data-structures/{data_structure_id}/types/{type_id}/formulas/{template_id}
Scope
Pour effectuer cette requête, vous devez posséder le scope suivant : metadata:admin.
Paramètres
data_structure_id (string, obligatoire) : ID attribué à l'arborescence.
Cet ID peut être récupéré via la requête
GET v2/data-structures
ou lors de la création d'une nouvelle arborescence avecPOST v2/data-structures
.
type_id (string, obligatoire) : ID attribué au type d'élément.
Cet ID peut être récupéré via la requête
GET /v2/data-structures/{data_structure_id}/types
ou suite à la création d'un nouveau type avecPost v2/data-structures/{data_structure_id}/types
.
template_id (string, obligatoire) : ID attribué au modèle de formules que vous souhaitez éditer.
Cet ID peut être récupéré via la requête
Get v2/data-structures/{data_structure_id}/types/{type_id}/formulas
ou lors de la création du template de formules.
Ces paramètres doivent être ajoutés à l'URL pour construire la chaîne de requête :
/v2/data-structures/{data_structure_id}/types/{type_id}/formulas
Corps de la requête
Le corps de la requête est identique à celui de la création d'un nouveau modèle de formules.
{
"label": "string",
"metricTypeId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"options": "Custom",
"formula": {
"resultType": "BOOL",
"schedule": "string",
"sourceValidityInSecond": 0,
"timezone": "string",
"description": "string",
"unit": "string",
"formulaTemplate": "string"
},
"metricTemplate": "string"
}
Remarque : Il n'est pas possible de modifier le champ "metricTemplate", représentant le nom générique des formules (métriques calculées) générées par le modèle.
Exemple de requête
# Commande pour mettre à jour un modèle de formule existant
curl -X 'PUT' \
'https://xxx.indaba.api.indasuite.io-base.com/v2/data-structures/67337415-6bcb-4c21-b0f5-8253d68b6e80/types/e9910c2b-83e9-4954-a1dd-abca2d833999/formulas/b4ba1278-4e91-44b2-b6c5-8ced3d8fc1eb' \
# ----- En-têtes -----
-H 'accept: application/json' \
-H 'Authorization: Bearer VOTRE_JETON_JWT' \
-H 'Content-Type: application/json' \
# ----- Corps de la requête -----
-d '
{
"label": "test_modif_formulas_template",
"metricTypeId": "b63f4f26-2103-460f-bb89-727c341ccfb6",
"options": "Custom",
"formula": {
"resultType": "INT",
"schedule": "*/3 * * * *",
"sourceValidityInSecond": 60,
"timezone": "Europe/Lisbon",
"description": "modif_description",
"unit": "C",
"formulaTemplate": "[id_moy]*100"
},
"metricTemplate": "main@{code_site}.val"
}
'
Réponses
exemple de réponse valide (200 ok) :
{
"data": {
"id": "b4ba1278-4e91-44b2-b6c5-8ced3d8fc1eb",
"metricTypeId": "b63f4f26-2103-460f-bb89-727c341ccfb6",
"options": "Custom",
"label": "test_modif_formulas_template",
"metricTemplate": "main@{code_site}.val",
"version": 2,
"formula": {
"formulaTemplate": "[id_moy]*100",
"description": "modif_description",
"unit": "C",
"schedule": "*/3 * * * *",
"timezone": "Europe/Lisbon",
"resultType": "INT",
"sourceValidityInSecond": 60
}
},
"resultCode": 2010,
"message": "OK"
}
Erreurs courantes
Veuillez vous référer à la liste des erreurs courantes.
Supprimer un modèle de formules génériques
Delete /v2/data-structures/{data_structure_id}/types/{type_id}/formulas/{template_id}
Scope
Pour effectuer cette requête, vous devez posséder le scope suivant : metadata:admin.
Paramètres
data_structure_id (string, obligatoire) : ID attribué à l'arborescence.
Cet ID peut être récupéré via la requête
GET v2/data-structures
ou lors de la création d'une nouvelle arborescence avecPOST v2/data-structures
.
type_id (string, obligatoire) : ID attribué au type d'élément.
Cet ID peut être récupéré via la requête
GET /v2/data-structures/{data_structure_id}/types
ou suite à la création d'un nouveau type avecPost v2/data-structures/{data_structure_id}/types
.
template_id (string, obligatoire) : ID attribué au modèle de formules que vous souhaitez éditer.
Cet ID peut être récupéré via la requête
Get v2/data-structures/{data_structure_id}/types/{type_id}/formulas
ou lors de la création du template de formules.
delete_metrics (boolean, optionnel) : permet d'indiquer si vous souhaitez supprimer les métriques associées au modèle de l'arborescence. Ce champ peut prendre deux valeurs :
true : les métriques associées au modèle seront supprimées de l'arborescence
false (valeur par défaut) : les métriques associées au modèle seront conservées dans l'arborescence.
Ces paramètres doivent être ajoutés à l'URL pour construire la chaîne de requête tel que :
/v2/data-structures/{data_structure_id}/types/{type_id}/formulas?delete_metrics=[true or false]
Exemple de requête :
# Commande pour supprimer un modèle de formule
curl -X 'DELETE' \
'https://xxx.indaba.api.indasuite.io-base.com/v2/data-structures/f9f16627-460e-4369-b345-a4ee3e94221e/types/88dacd49-2f01-4ca7-944c-6716322cb67e?delete_metrics=false' \
# ----- 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.