Cette API permet de récupérer une liste d'endpoints de manière incrémentale, pour mettre à jour rapidement les endpoints sans récupérer toute la liste.

Principe de fonctionnement

Pour obtenir une liste d'endpoints de manière incrémentale, on utilise le champ SequenceNumber. Ce champ est monotone croissant : lorsqu'un EndpointData subit une modification, son champ SequenceNumber prend une valeur supérieure à toutes les autres. Il est ainsi possible de récupérer les données à partir du SequenceNumber par petits lots jusqu'à ce qu'il n'y ait plus de données, puis de continuer périodiquement pour obtenir les mises à jour. Lorsque cette API renvoie une liste vide, cela signifie qu'il n'y a aucune mise à jour pour le moment.

En général, une application qui consomme cette API suit le flux suivant :

L'application démarre avec un SequenceNumber stocké (généralement dans un stockage non volatil). Lors de la première exécution, cette valeur est 1.
L'application exécute l'API avec (SequenceNumber stocké + 1).
L'application reçoit une liste de données d'endpoints, triée par SequenceNumber.
Si la liste reçue est vide, l'application attend quelques secondes et revient à l'étape 2.
Si la liste reçue n'est pas vide, l'application stocke le SequenceNumber le plus élevé reçu.
L'application revient immédiatement à l'étape 2.
Lorsqu'un endpoint transmet une nouvelle lecture de données, son SequenceNumber prend immédiatement une valeur supérieure au dernier reçu, de sorte que ses informations sont reçues dès l'exécution suivante.

Dans le flux ci-dessus, on suppose que l'application exécute toujours l'API avec le même ensemble de paramètres clientID, facilityID, deviceID et endpointID. Si l'on souhaite utiliser d'autres paramètres, la recherche doit repartir de zéro.

Pour déboguer une application qui utilise cette API, il est recommandé d'utiliser maxCount = 1, afin de recevoir les mises à jour une par une. Ce paramètre peut ensuite être porté à une valeur plus adaptée à la production, par exemple 50.

Requête

GET /api/v2/endpointData/incremental/{sequenceNumber}?clientID={clientID}&facilityID={facilityID}&deviceID={deviceID}&endpointID={endpointID}&maxCount={maxCount} HTTP/1.1
Host: gear.cloud.studio
Authorization: Bearer {accessToken}

Paramètres

Nom	Description
accessToken	Token d'accès disposant des permissions de lecture des informations d'endpoint. Consultez cette page pour plus d'informations. Le token d'accès peut également être envoyé dans la chaîne de requête, au moyen du paramètre « accessToken ».
sequenceNumber	Valeur du champ SequenceNumber du dernier EndpointData reçu. Utilisez 0 pour partir du début.
clientID	Identifiant facultatif indiquant que seules les EndpointData du client indiqué doivent être récupérées.
facilityID	Identifiant facultatif indiquant que seules les EndpointData de l'installation indiquée doivent être récupérées.
deviceID	Identifiant facultatif indiquant que seules les EndpointData de l'appareil indiqué doivent être récupérées.
endpointID	Identifiant facultatif indiquant que seules les EndpointData de l'endpoint indiqué doivent être récupérées.
maxCount	Paramètre facultatif indiquant le nombre maximal d'enregistrements à inclure dans le résultat. Les valeurs supérieures à 500 sont limitées à 500, quelle que soit la valeur envoyée dans la requête.

Il est obligatoire d'inclure un (et un seul) des paramètres « clientID », « facilityID », « deviceID » ou « endpointID ».

Réponse

La réponse contient la liste des EndpointData correspondants, comme le montre cet exemple :

[
	{
        "EndpointID": 113653,
        "Timestamp_UTC": "2021-10-15T23:01:25",
        "Value": 16.93,
        "SequenceNumber": 6683852
    },
	{
        "EndpointID": 113653,
        "Timestamp_UTC": "2021-10-15T23:11:28",
        "Value": 16.97,
        "SequenceNumber": 6683864
    },
	{
        "EndpointID": 113653,
        "Timestamp_UTC": "2021-10-15T23:41:36",
        "Value": 16.93,
        "SequenceNumber": 6683874
    },
	{
        "EndpointID": 113653,
        "Timestamp_UTC": "2021-10-16T00:01:44",
        "Value": 16.99,
        "SequenceNumber": 6683887
    },
	{
        "EndpointID": 113653,
        "Timestamp_UTC": "2021-10-16T00:11:48",
        "Value": 15.93,
        "SequenceNumber": 6683900
    }
]

Obtenir les données d'endpoints de manière incrémentale

Principe de fonctionnement

Requête

Paramètres

Réponse

Sur cette page