Obtenir une liste d'alertes de manière incrémentale
Cette API récupère une liste d'alertes de manière incrémentale, pour suivre vite les alertes créées, modifiées ou supprimées sans récupérer toute la liste.
Principe de fonctionnement
Pour obtenir une liste d'alertes de manière incrémentale, on utilise le champ SequenceNumber. Ce champ est monotone croissant : lors de la création, de la modification ou de la suppression d'une alerte, son champ SequenceNumber prend une valeur supérieure à celle de toutes les autres alertes. 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'alertes, 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 alerte est créée, ou qu'une alerte 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é Enabled vaut false indique que l'élément a été supprimé. Si la propriété Enabled vaut true, l'élément vient d'être créé ou modifié.
| 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/alerts/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'alerte. 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 alerte reçue. Utilisez 0 pour partir du début. |
| clientID | Identifiant facultatif indiquant que seules les alertes du client indiqué doivent être récupérées. |
| facilityID | Identifiant facultatif indiquant que seules les alertes de l'installation indiquée doivent être récupérées. |
| deviceID | Identifiant facultatif indiquant que seules les alertes de l'appareil indiqué doivent être récupérées. |
| endpointID | Identifiant facultatif indiquant que seules les alertes de l'endpoint indiqué doivent être récupérées. |
| maxCount | Paramètre facultatif indiquant le nombre maximal d'alertes à inclure dans le résultat. |
| 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 alertes correspondantes, comme le montre cet exemple :
[
{
"AlertID": 211,
"VariableTypeID": 1,
"EndpointID": 114092,
"ConditionType": 3,
"Threshold": 25,
"ClientID": 4,
"FacilityID": 184,
"NormalConditionType": 6,
"NormalThreshold": 24,
"MinimumDurationSeconds": 300,
"NotificationEmails": ["someone@somewhere.com"],
"NotificationSMSNumbers": ["+1123456789"],
"NotificationVoiceNumbers": ["+1123456789"],
"Tags": ["default", "gateway-default"],
"SequenceNumber": 45701485,
"Enabled": true,
"Schedules": [],
"Timezone": {
"CurrentOffsetMinutes": -180,
"TimeZoneCode": "america/argentina/buenos_aires"
}
},
{
"AlertID": 212,
"VariableTypeID": 1,
"EndpointID": 114092,
"ConditionType": 5,
"Threshold": 20,
"ClientID": 4,
"FacilityID": 184,
"NormalConditionType": 3,
"NormalThreshold": 22,
"MinimumDurationSeconds": 300,
"NotificationEmails": ["someone@somewhere.com"],
"NotificationSMSNumbers": ["+1123456789"],
"NotificationVoiceNumbers": ["+1123456789"],
"Tags": ["default", "gateway-default"],
"SequenceNumber": 45701485,
"Enabled": true,
"Schedules": [
{
"Days": [
1,
2,
4,
5
],
"StartTime": {
"Hour": 0,
"Millisecond": 0,
"Minute": 0,
"Second": 0
},
"EndTime": {
"Hour": 23,
"Millisecond": 999,
"Minute": 0,
"Second": 59
}
}
],
"Timezone": {
"CurrentOffsetMinutes": -180,
"TimeZoneCode": "america/argentina/buenos_aires"
}
}
]Dernière mise à jour le
Obtenir une liste d'alertes à l'aide de paramètres
Référence de l'API pour obtenir une liste d'alertes filtrées par client, installation, appareil ou endpoint, avec un nombre maximal de résultats.
Alarmes
Comment interroger par l'API les alarmes générées par les alertes de Gear Studio, ouvertes ou fermées, par ID, par paramètres ou en incrémental.