Passer au contenu principal

Lecture de données (/v2/data)

Mis à jour cette semaine

Cette section détaille les endpoints permettant de lire les données des métriques de Io-base.

Récupérer des valeurs agrégées pour une métrique

Description

Cette requête vous permet de récupérer une série de valeurs agrégées (par exemple : moyenne, somme) pour une métrique sur des intervalles de temps réguliers.

GET /v2/data/aggregated-values

Scope

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

Paramètres

  • MetricName (obligatoire) : Nom de la métrique à requêter.

  • Datasource (obligatoire) : Source de données de la métrique (ex: prod).

  • Start (obligatoire) : Date de début de la période (format ISO 8601).

  • End (obligatoire) : Date de fin de la période (format ISO 8601).

  • Function (obligatoire) : Fonction d'agrégation disponibles (Avg, Sum, Min, Max, Count, Median, StdDev, First, Last, Integral).

  • Interval (obligatoire) : Intervalle pour le regroupement des agrégations (10m, 1h, 1d...).

  • Timezone (optionnel) : Fuseau horaire pour l'alignement des intervalles (format IANA, ex: Europe/Paris).

  • Limit (optionnel) : Limite le nombre de points retournés (max 50000).

  • Annotations (optionnel) : Si true, inclut les annotations dans la réponse.

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 "&" :

.../aggregated-values ?MetricName=[nom_metrique]&Datasource=[source_de_donnees]&Start=[date_debut]&End=[date_fin]&Function=[fonction_agg]&Interval=[intervalle_temps]&Limit=[limite]

Exemple de requête :

# Requête pour calculer la moyenne par tranche de 30 minutes.

curl -X GET \
  "https://xxx.indaba.api.indasuite.io-base.com/v2/data/aggregated-values?MetricName=documentation&Datasource=main&Start=2025-06-26T08:00:00Z&End=2025-06-26T10:00:00Z&Function=Avg&Interval=30m" \
  -H 'Authorization: Bearer VOTRE_JETON_JWT'

Réponses

Réponse valide (200 OK)

{
  "values": [
    {
      "timestamp": "2025-06-26T10:00:00+02:00",
      "value": 115.5
    },
    {
      "timestamp": "2025-06-26T10:30:00+02:00",
      "value": 118.2
    }
  ],
  "isResponseComplete": true,
  "name": "metric4test_ok",
  "datasource": "main"
}

Gestion de la Pagination (isResponseComplete) :

Veuillez vous référer au paragraphe de gestion de la pagination.

Erreurs courantes :

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

Récupérer une seule valeur agrégée

Description

Cette requête vous permet de récupérer une seule valeur agrégée (par exemple : la moyenne, la somme) pour une métrique sur l'ensemble d'une période.

GET /v2/data/aggregated-value

Scope

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

Paramètres

  • MetricName (obligatoire) : Nom de la métrique à requêter.

  • Datasource (optionnel) : Source de données de la métrique.

  • Start (obligatoire) : Date de début de la période (format ISO 8601).

  • End (obligatoire) : Date de fin de la période (format ISO 8601).

  • Function (obligatoire) : Fonction d'agrégation disponibles (Avg, Sum, Min, Max, Count, Median, StdDev, First, Last, Integral)

  • Interval (optionnel) : Intervalle de temps pour le calcul (ex: 1h).

  • Timezone (optionnel) : Fuseau horaire pour l'alignement des intervalles (format IANA).

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 "&" :

.../aggregated-value?MetricName=[nom_metrique]&Start=[date_debut]&End=[date_fin]&Function=[fonction_agg]

Exemple de requête

# Commande pour récupérer la moyenne d'une métrique sur une heure curl -X GET \   'https://xxx.indaba.api.indasuite.io-base.com/v2/data/aggregated-value?MetricName=metric4test_ok&Datasource=main&Start=2025-06-26T07:06:00Z&End=2025-06-26T08:06:00Z&Function=Avg' \   
-H 'Authorization: Bearer VOTRE_JETON_JWT'

Réponses

exemple de réponse valide (200 OK) 

{
  "timestamp": "2025-06-26T07:06:00+00:00",
  "value": 123,
  "name": "metric4test_ok",
  "datasource": "main"
}

Erreurs courantes :

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

Récupérer des valeurs brutes (non agrégées)

Description

Cette requête récupère les valeurs brutes (non agrégées) d'une métrique sur une plage de temps.

GET /v2/data/values

Scope

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

Paramètres

  • MetricName (string, obligatoire) : Nom de la métrique.

  • Datasource (string, optionnel) : Source de données de la métrique.

  • Start (date-time, obligatoire) : Date de début de la période (format ISO 8601).

  • End (date-time, obligatoire) : Date de fin de la période (format ISO 8601).

  • Limit (integer, optionnel) : Limite le nombre de points retournés (max 50000).

  • Timezone (string, optionnel) : Fuseau horaire pour l'interprétation des dates.

  • OrderBy (string, optionnel) : Trie les résultats par horodatage. Valeurs possibles : ASC (croissant) ou DESC (décroissant).

  • Filter (string, optionnel) : Expression de filtrage sur les valeurs (ex: value > 100).

  • Annotations (boolean, optionnel) : Si true, inclut les annotations dans la réponse.

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 :

.../values?MetricName=[nom_metrique]&Datasource=[source]&Start=[date_debut]&End=[date_fin]&Limit=[limite]&OrderBy=[ASC|DESC]&Filter=[expression_filtre]&Annotations=[true|false]&Timezone=[fuseau_horaire]

Exemple de requête

# Commande pour récupérer les 100 dernières valeurs brutes supérieures à 50, triées par ordre décroissant. 
 curl -X GET \ 
   'https://xxx.indaba.api.indasuite.io-base.com/v2/data/values?MetricName=metric4test_ok&Datasource=main&Start=2025-06-26T07:06:00Z&End=2025-06-26T08:06:00Z&Limit=100&OrderBy=DESC&Filter=value>50' \ 
   -H 'Authorization: Bearer VOTRE_JETON_JWT'

Réponses

Réponse valide (200 ok) : 

{ 
   "values": [ 
     { 
       "timestamp": "2025-07-01T13:50:55.8349135+00:00", 
       "value": 45 
     }, 
     { 
       "timestamp": "2025-07-01T14:50:55.8349142+00:00", 
       "value": 100.21 
     } 
   ], 
   "isResponseComplete": true, 
   "name": "cip_30", 
   "datasource": "test", 
   "unit": "°C" 
 }

Gestion de la Pagination (isResponseComplete) :

Veuillez vous référer au paragraphe de gestion de la pagination.

Erreurs courantes :

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

Récupérer la dernière valeur d'une (ou plusieurs) métrique(s)

Description

Cette requête récupère la dernière valeur reçue pour une ou plusieurs métriques. Tous les paramètres sont fournis dans le corps de la requête.

POST /v2/data/query/values/latest

Scope

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

Paramètres

  • metrics (liste d'objets, obligatoire) : Liste des métriques à interroger.

  • metricName (chaîne, obligatoire) : Nom de la métrique.

  • datasource (chaîne, optionnel) : Source de données.

  • targetUnit (string, optionnel) : L'unité dans laquelle la valeur doit être retournée.

  • timezone (string, optionnel) : Fuseau horaire pour l'interprétation des dates.
    ​

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 : 

{ "metrics": [ { "metricName": "nom_de_la_metrique_1", "datasource": "source_de_donnees" }, { "metricName": "nom_de_la_metrique_2" } ], "timezone": "fuseau_horaire" }

Exemple de requête

# Commande pour récupérer la dernière valeur de trois métriques 
 curl -X POST \ 
   --url 'https://xxx.indaba.api.indasuite.io-base.com/v2/data/query/values/latest' \ 
   # ----- En-têtes ----- 
   -H 'Authorization: Bearer VOTRE_JETON_JWT' \ 
   -H 'Content-Type: application/json' \ 
 
   # ----- Corps de la requête ----- 
   -d ' 
   { 
     "metrics": [ 
       { "metricName": "metric4test_ok", "datasource": "main" }, 
       { "metricName": "metric_accessible_2", "datasource": "main" }, 
       { "metricName": "metric_inaccessible", "datasource": "main" } 
     ] 
   } 
   '

Réponses

Exemple de réponse valide (200 OK) :

Cette requête peut interroger plusieurs métriques simultanément. Sa réponse est donc structurée pour gérer les succès et les échecs métrique par métrique.

Pour cette raison, la requête retourne un statut global 200 OK, et c'est dans le corps de la réponse que chaque métrique se voit attribuer un champ "status" pour indiquer si l'opération a réussi ou non.

Si l'accès est refusé, aucune valeur n'est affectée à la métrique dans la réponse.

Ci-dessous, un exemple de réponse pour une requête sur trois métriques.

  • La première est retournée avec succès (status 200).

  • La deuxième est inaccessible pour l'utilisateur quand il n'a pas les droits nécessaires (status 403).

  • La troisième n'existe pas dans le référentiel (status 404).

[ 
   { 
     "status": 200, 
     "timestamp": "2025-07-02T09:22:41Z", 
     "value": 123.5, 
     "name": "metric_accessible_1", 
     "datasource": "main" 
   }, 
   { 
     "status": 403, 
     "name": "metric_inaccessible", 
     "datasource": "main" 
   }, 
   { 
     "status": 404, 
     "timestamp": "2025-07-02T09:20:15Z", 
     "value": 99.9, 
     "name": "metric_accessible_2", 
     "datasource": "main" 
   } 
 ]

Pour plus d'informations sur les statuts d'erreur, veuillez vous référer à la liste des erreurs courantes.

Récupérer la dernière valeur pour une seule métrique

Description

Cette requête récupère la dernière valeur connue pour une seule métrique. C'est une version optimisée de la requête POST correspondante, plus simple et performante pour le cas d'usage d'une métrique unique.

GET /v2/data/values/latest

Scope

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

Paramètres

  • MetricName (obligatoire) : Nom de la métrique.

  • Datasource (optionnel) : Source de donné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 "&".

.../values/latest?MetricName=[nom_metrique]&Datasource=[source_de_donnees]

Exemple de requête

# Commande pour récupérer la dernière valeur d'une métrique. 
 curl -X GET \ 
   'https://xxx.indaba.api.indasuite.io-base.com/v2/data/values/latest?MetricName=metric4test_ok&Datasource=main' \ 
   -H 'Authorization: Bearer VOTRE_JETON_JWT'

Réponses

Exemple de réponse valide (200 OK)

{
  "timestamp": "2025-06-26T10:04:52+02:00",
  "value": 123,
  "name": "metric4test_ok",
  "datasource": "main"
}

Erreurs courantes :

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

Récupérer une valeur à un instant T pour plusieurs métriques

Description

Cette requête récupère la valeur de plusieurs métriques à un instant T précis (ou la valeur immédiatement avant/après ce moment).

POST /v2/data/query/values/instant

Scope

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

Paramètres

Les paramètres suivants seront à spécifier dans le corps de la requête :

  • moment (date-time, obligatoire) : L'instant T à interroger.

  • metrics (liste d'objets, obligatoire) : Liste des métriques à interroger.

    • metricName (string, obligatoire) : Nom de la métrique.

    • datasource (string, optionnel) : Source de données.

    • targetUnit (string, optionnel) : L'unité dans laquelle la valeur doit être retournée.

  • rangeLimiter (string, obligatoire) : Limite la recherche dans le temps (ex: 30m).

  • queryDirection (string, optionnel) : Before_moment (défaut) ou After_moment.

  • timezone (string, optionnel) : Fuseau horaire pour l'interprétation des dates.

Exemple de requête

# Commande pour récupérer la valeur de trois métriques avant 13h00, 
# en limitant la recherche à une fenêtre de 30 minutes. 
 
curl -X POST \ 
  --url 'https://xxx.indaba.api.indasuite.io-base.com/v2/data/query/values/instant' \ 
 
  # ----- En-têtes ----- 
  -H 'Authorization: Bearer VOTRE_JETON_JWT' \ 
  -H 'Content-Type: application/json' \ 
 
  # ----- Corps de la requête ----- 
  -d ' 
  { 
    "moment": "2025-06-27T13:00:00+02:00", 
    "rangeLimiter": "30m", 
    "metrics": [ 
      { "metricName": "metric4test_ok", "datasource": "main" }, 
      { "metricName": "metric_accessible_2", "datasource": "main" }, 
       { "metricName": "metric_accessible_3", "datasource": "main" } 
    ] 
  } 
  '

Réponses

Exemple de réponse valide (200 OK) :

Cette requête peut interroger plusieurs métriques simultanément. Sa réponse est donc structurée pour gérer les succès et les échecs métrique par métrique.

Pour cette raison, la requête retourne un statut global 200 OK, et c'est dans le corps de la réponse que chaque métrique se voit attribuer un champ "status" pour indiquer si l'opération a réussi ou non.

Si l'accès est refusé, aucune valeur n'est affectée à la métrique dans la réponse.

Ci-dessous, un exemple de réponse pour une requête sur trois métriques.

  • La première est retournée avec succès (status 200).

  • La deuxième est inaccessible pour l'utilisateur quand il n'a pas les droits nécessaires (status 403).

  • La troisième n'existe pas dans le référentiel (status 404).

[ 
   { 
     "status": 200, 
     "timestamp": "2025-07-02T12:59:58+02:00", 
     "value": 123.5, 
     "name": "metric_accessible_1", 
     "datasource": "main" 
   }, 
   { 
     "status": 403, 
     "name": "metric_inaccessible", 
     "datasource": "main" 
   }, 
   { 
     "status": 404, 
     "name": "metric_qui_n_existe_pas", 
     "datasource": "main" 
   } 
 ]

Pour plus d'informations sur les statuts d'erreur, veuillez vous référer à la liste des erreurs courantes.

Récupérer une valeur à un instant T (une seule métrique)

Description

Cette requête récupère la valeur d'une seule métrique à un instant T précis (ou la valeur immédiatement avant/après ce moment).

GET /v2/data/values/instant

Scope

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

Paramètres

  • MetricName (string, obligatoire) : Nom de la métrique.

  • Datasource (string, optionnel) : Source de données de la métrique.

  • Moment (date-time, obligatoire) : L'instant T à interroger (format ISO 8601).

  • RangeLimiter (string, obligatoire) : Restreint la recherche à un intervalle de temps (ex: 30m).

  • QueryDirection (string, optionnel) : Spécifie s'il faut chercher la valeur avant (Before_moment, défaut) ou après (After_moment) l'instant T.

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 "&".

Exemple de requête

curl -X GET \
  "https://xxx.indaba.api.indasuite.io-base.com/v2/data/values/instant?MetricName=metric_test&Datasource=test&Moment=2020-01-26T13:00:00%2B01:00&QueryDirection=after_moment&RangeLimiter=30m" \
  -H 'Authorization: Bearer VOTRE_JETON_JWT'

Réponses

Exemple de réponse valide (200 OK) : 

{
    "timestamp": "2025-01-26T13:29:08.000+01:00",
    "value": 0.422,
    "name": "meas_doc1",
    "datasource": "test"
}

Erreurs courantes :

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

Gestion de la pagination

Pour des raisons de performance, lorsque vous demandez des données sur une longue période, l'API peut retourner les résultats en plusieurs fois. Certaines réponses contiennent un champ booléen nommé "isResponseComplete" pour gérer ce cas.

  • Si isResponseComplete est true : Vous avez reçu toutes les données pour la période demandée.

  • Si isResponseComplete est false : Il reste des données à récupérer. Pour obtenir la suite, vous devez effectuer une nouvelle requête en ajustant vos paramètres :

    1. Récupérez l'horodatage (timestamp) du dernier point de donnée reçu.

    2. Faites une nouvelle requête identique, mais en utilisant cet horodatage comme nouvelle date de début (Start).

    3. Répétez ce processus jusqu'à ce que la réponse contienne isResponseComplete: 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": "Field Required", 
           "message": "The xxx field is required." 
         } 
       ], 
       "statusCode": 1050, 
       "message": "Invalid request" 
     }

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

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