Exemple events

Cas d'usage : Un fournisseur de services de comptage d'eau souhaite informer son client sur l'état de son patrimoine concernant des évènements de type changement de compteur et des alertes de type suspicion de fuite d'eau :Pour cela, il dispose des données du type :
  • alert : une alerte signifiant un événement particulier.


Publication d'alertes

Création des streams events


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 "events" qui recevra les données de type alert correspondant aux différents statuts des alertes sur la consommation d'eau.
{
  "reference": "STREAM-14-11-2017-01",
  "label": "Alertes compteurs d'eau",
  "description": "évènements sur les compteurs d'eau",
  "type": "events",
  "tags": {
    "intent_assetReference": "TEST-EQUIP-API-01",
    "intent_activityKey": "WaterCons",
    "intent_dataType": "alert"
  }
}


Réponse :



Retourne le code HTTP 201 The stream has been created, si les flux ont été créés avec succès.
{
    "creationDate": "2017-12-07T16:48:47+01:00",
    "type": "events",
    "label": "Alertes compteurs d'eau",
    "description": "évènements sur les compteurs d'eau",
    "lastUpdateDate": "2017-12-07T16:48:47+01:00",
    "reference": "STREAM-14-11-2017-01",
    "tags": {
        "intent_activityKey": "WaterCons",
        "intent_dataType": "alert",
        "intent_frequency": 0,
        "intent_sourceType": "api",
        "intent_sourceEntity": {
            "label": "Tests - Toit Social Habitat",
            "logoUrl": "https://hubintent.com/intent/entities/logos/5a7dc4cb-10f5-4e9f-b213-820e8246f97c"
        },
        "intent_assetReference": "TEST-EQUIP-API-01"
    },
    "_links": {
        "self": {
            "href": "https://apici.intent-technologies.eu/api/data/v1/streams/STREAM-14-11-2017-01"
        }
    }
}


Publication des évènements


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/events
verbe HTTP
POST

Publier des évènements
{
  "streamReference": "STREAM-14-11-2017-01",
  "payload": [
    {
      "type": "Etat Compteur",
      "status": "pose",
      "timestamp": 1510642800000,
      "information": {
        "newIndex": 1389
      }
    },
    {
      "type": "Fuite d eau",
      "status": "DEBUT",
      "timestamp": 1510642810000,
      "information": {}
    },
      {
      "type": "Fuite d eau",
      "status": "FIN",
      "timestamp": 1510646400000,
      "information": {}
    },
   ]
 }


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 d'évènements


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

IntentPlatform utilise des dates au format 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/events/STREAM-14-11-2017-01?since=2017-10-04
verbe HTTP
GET
ou
URL
/api/data/v1/events/STREAM-14-11-2017-01?from=2017-11-13 00:00:00&to=2017-11-15 11:00:00
verbe HTTP
GET
Période de consultation des metrics ou events

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://apici.intent-technologies.eu/api/data/V1/events/STREAM-14-11-2017-01?since=2017-10-04"
        }
    },
    "_embedded": {
        "events": [
            {
                "type": "Etat Compteur",
                "status": "pose",
                "timestamp": 1510642800000,
                "information": {
                   "newIndex": 1389
                   }
            },
            {
                "type": "Fuite compteur eau",
                "status": "DEBUT",
                "timestamp": 1510642800000
            },
            {
                "type": "Fuite compteur eau",
                "status": "FIN",
                "timestamp": 1510642810000
            }
        ]
    }
}