Passer au contenu principal

Gestion des modèles de formules (templates)

Mis à jour il y a plus de 2 semaines

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

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

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

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

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

  • 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.

Article suivant

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