Exemple metrics

Cas d'usage : Un fournisseur de services de comptage d'eau effectue le relevé du compteur d'eau et souhaite envoyer ces informations sur la plateforme. Il dispose de trois types de données distincts concernant la consommation :
  • snapshot : l'index de consommation d'eau à un instant donné ;
  • delta : la consommation d'eau à partir d'un moment donné t, pour une durée Δt ;
  • average : la moyenne hebdomadaire de consommation d'eau.


Publication de données



Création des streams metrics

Avant tout envoi de données, il est nécessaire de créer les flux de données (ou streams).

Requête :

URL
/api/data/V1/streams
verbe HTTP
POST

    Création d'un stream qui recevra les données de type index correspondant aux consommations instantanées.
{
  "reference": "STREAM-index",
  "label": "INDEX eau",
  "description": "index de consommation d'eau à un instant donné",
  "type": "metrics",
  "tags": {
    "intent_unit": "m3",
    "intent_assetReference": "000000000056",
    "intent_activityKey": "WaterCons",
    "intent_dataType": "snapshot",
    "intent_frequency": 60,
    "intent_contractReference": "string",
    "meter type": "string",
    "group": "string"
  }
}

    Création d'un stream qui recevra les données de type delta correspondant aux consommations relevées sur une période de temps (définie par le tag intent_frequency).
{
  "reference": "STREAM-delta",
  "label": "DELTA eau",
  "description": "consommation d'eau à partir d'un moment t, pour une durée Δt",
  "type": "metrics",
  "tags": {
    "intent_unit": "m3",
    "intent_assetReference": "000000000056",
    "intent_activityKey": "WaterCons",
    "intent_dataType": "delta",
    "intent_frequency": 43200,
    "intent_contractReference": "string",
    "meter type": "string",
    "group": "string"
  }
}

    Création d'un stream qui recevra les données de type average correspondant aux moyennes de consommation relevées sur une période de temps (définie par le tag intent_frequency).
{
  "reference": "STREAM-average",
  "label": "AVERAGE eau",
  "description": "moyenne hebdomadaire de consommation d'eau",
  "type": "metrics",
  "tags": {
    "intent_unit": "m3",
    "intent_assetReference": "000000000056",
    "intent_activityKey": "WaterCons",
    "intent_dataType": "average",
    "intent_frequency": 10080,
    "intent_contractReference": "string",
    "meter type": "string",
    "group": "string"
  }
}


Réponse :

Retourne le code HTTP 201 The stream has been created, si les flux ont été créés avec succès.


Publication des données dans les streams


Comme expliqué précédemment, seuls 2 paramètres doivent être connus pour publier de la donnée :
  • La référence du stream
  • Le type de la donnée (metrics ou events)


Requête :

URL
/api/data/V1/metrics
verbe HTTP
POST
    Publier des index
{
  "streamReference": "STREAM-index",
  "payload": [
    {
    "timestamp": 1510560000000,
    "value": 1436,
  },
  {
    "timestamp": 1510563600000,
    "value": 1438,
    "trustlevel": "computed"
  }
  ]
}

    Publier des deltas
{
  "streamReference": "STREAM-delta",
  "payload": [
    {
    "timestamp": 1506844800000,
    "value": 17,
  },
  {
    "timestamp": 1509526800000,
    "value": 15,
    "trustlevel": "computed"
  }
  ]
}

    Publier des moyennes
{
  "streamReference": "STREAM-average",
  "payload": [
    {
    "timestamp": 1509958800000,
    "value": 4,
  },
  {
    "timestamp": 1510563600000,
    "value": 5,
    "trustlevel": "computed"
  }
  ]
}


Réponse :



Retourne le code HTTP 202 Metrics are being processed by the platform, si les données ont été envoyées avec succès.
Parmi les erreurs courantes

Absence de crochets [ ] exigés dans le modèle de body, qu'il s'agisse d'envoi d'une ou de plusieurs données,

La date est exprimée en  Unix timestamps (milliseconds) .
Expression du timestamp en secondes (10 chiffres) au lieu de millisecondes (13 chiffres), souvent l'oubli des 3 zéros à la fin du timestamp.


Consultation de données


La récupération des données se fait via la référence du stream contenant les données.Cependant, il faut aussi indiquer la date (au format  ISO-8601 ) à partir de laquelle on souhaite voir les résultats.
Format de date ISO-8601


Pour information :Lorsqu'une date est postée au format : 2017-10-25T02:30:53Z --> alors le Z signifie qu'il s'agit du fuseau horaire UTC

Comme indiqué dans la documentation spécialisée, il est aussi possible d'écrire la date sous la forme : 2017−10−25T02:30:53+01:00
--> ce qui implique un fuseau UTC + 1h00 (soit la France, à l'heure d'hiver)

Cela étant, puisque la grande majorité des utilisateurs IntentPlatform sont en France, nous avons mis en place un mécanisme permettant de lire un format du type 2017-10-25T02:30:53 ou 2017-10-25 (si vous ne voulez pas spécifier l'heure) comme étant une date basée sur le fuseau Central European Time : CET / Paris.


Requête :


URL
/api/data/v1/metrics/STREAM-index?from=2017-11-12&to=2017-11-14
verbe HTTP
GET
Péridode de consultation des metrics et event

Pour obtenir des événements créés entre deux dates, vous pouvez utiliser les paramètres FROM et TO pour faire votre requête.
Pour obtenir des événements mis à jour par la plateforme Intent depuis une date, vous pouvez utiliser le paramètre SINCE.

Un des paramètres from / to ou since est requis.

Les événements sont limités à une année par requête.


Réponse :

{
    "_links": {
        "self": {
            "href": "https://apisandbox.hubintent.com/api/data/v1/metrics/STREAM-index?from=2017-11-12&to=2017-11-14"
        }
    },
    "_embedded": {
        "metrics": [
            {
                "timestamp": 1510560000000,
                "value": 1436,
            },
            {
                "timestamp": 1510563600000,
                "value": 1438,
                "trustlevel": "computed"
            }
        ]
    }
}