Cette API récupère une liste d'alarmes de manière incrémentale, pour mettre à jour rapidement les alarmes ouvertes ou fermées sans récupérer toute la liste.

Principe de fonctionnement

Pour obtenir une liste d'alarmes de manière incrémentale, on utilise le champ SequenceNumber. Ce champ est monotone croissant : lorsqu'une alarme subit une modification, son champ SequenceNumber prend une valeur supérieure à celle de toutes les autres alarmes. 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 d'alarmes, 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'une nouvelle alarme est ouverte, ou qu'une alarme existante est modifiée, 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.
Tout élément reçu dont la propriété DateTimeClosed_UTC a une valeur non nulle et non vide indique que l'alarme est déjà fermée.

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/alarms/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'alarme. 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 de la dernière alarme reçue. Utilisez 0 pour partir du début.
clientID	Identifiant facultatif indiquant que seules les alarmes du client indiqué doivent être récupérées.
facilityID	Identifiant facultatif indiquant que seules les alarmes de l'installation indiquée doivent être récupérées.
deviceID	Identifiant facultatif indiquant que seules les alarmes de l'appareil indiqué doivent être récupérées.
endpointID	Identifiant facultatif indiquant que seules les alarmes 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 alarmes correspondantes, comme le montre cet exemple :

[
	{
        "AlarmID": 1266896,
        "DeviceID": 7370,
        "DeviceDescription": "Controlador RUPANCO",
        "AlarmTypeID": 1,
        "AlarmTypeDescription": "Dispositivo fuera de línea",
        "AlarmSeverityID": 3,
        "AlarmSeverityDescription": "Alta",
        "DateTimeCreated_UTC": "2021-10-15T17:34:35",
        "DateTimeClosed_UTC": "2021-10-15T18:21:39",
        "SequenceNumber": 28885207,
        "MTTRMinutes": 47.0
    },
    {
        "AlarmID": 1266922,
        "DeviceID": 7370,
        "DeviceDescription": "Controlador RUPANCO",
        "AlarmTypeID": 1,
        "AlarmTypeDescription": "Dispositivo fuera de línea",
        "AlarmSeverityID": 3,
        "AlarmSeverityDescription": "Alta",
        "DateTimeCreated_UTC": "2021-10-15T19:36:41",
        "DateTimeClosed_UTC": "2021-10-15T19:37:23",
        "SequenceNumber": 28885384,
        "MTTRMinutes": 47.0
    },
    {
        "AlarmID": 1266950,
        "DeviceID": 7370,
        "DeviceDescription": "Controlador RUPANCO",
        "AlarmTypeID": 1,
        "AlarmTypeDescription": "Dispositivo fuera de línea",
        "AlarmSeverityID": 3,
        "AlarmSeverityDescription": "Alta",
        "DateTimeCreated_UTC": "2021-11-16T19:49:35",
        "DateTimeClosed_UTC": "2021-11-16T19:49:46",
        "SequenceNumber": 28948817,
        "MTTRMinutes": 47.0
    }
]

Obtenir une liste d'alarmes de manière incrémentale

Principe de fonctionnement

Requête

Paramètres

Réponse

Sur cette page