Obtener una lista de alertas en forma incremental
Esta API permite obtener una lista de alertas, en forma incremental. Esto permite obtener actualizaciones rápidas de las alertas a medida que son creadas, modificadas, o eliminadas, sin necesidad de obtener la lista completa.
Teoría de operación
Para obtener una lista de alertas en forma incremental, se utiliza el campo SequenceNumber. Este campo es de tipo monotónico ascendente, es decir que al crear, modificar, o eliminar una alerta, su campo SequenceNumber cambiará a un valor mayor al de cualquier otra alerta. Esto permite obtener datos basados en el SequenceNumber, en pequeños lotes, hasta que no se obtengan más datos, y luego continuar periódicamente, para obtener actualizaciones. Cuando el resultado de esta API es una lista vacía, esto significa que por el momento no existen actualizaciones.
Típicamente, una aplicación que consume esta API utiliza el siguiente flujo:
- La aplicación comienza utilizando un SequenceNumber almacenado (típicamente en almacenamiento no volátil). En la primera ejecución, este valor es 1.
- La aplicación ejecuta la API utilizando el (SequenceNumber almacenado + 1).
- La aplicación recibe una lista de alertas, ordenadas por SequenceNumber.
- Si la lista recibida vacía, la aplicación espera algunos segundos, y vuelve al paso 2.
- Si la lista recibida no es vacía, la aplicación almacena el mayor SequenceNumber recibido.
- La aplicación vuelve inmediatamente al paso 2.
- Cuando se crea una nueva alerta, o una existente es modificada, su SequenceNumber cambiará inmediatamente a un valor más alto que el último recibido, por lo cual su información será recibida inmediatamente en la próxima ejecución.
- Cualquier elemento que se reciba con la propiedad Enabled con valor false, indica que ese elemento ha sido eliminado. Si la propiedad Enabled tiene valor true, indica que el elemento acaba de ser creado o modificado.
| En el flujo anterior, se asume que la aplicación siempre ejecuta la API con el mismo conjunto de parámetros clientID, facilityID, deviceID, y endpointID. Si se desea usar parámetros diferentes, la búsqueda debe comenzar desde cero. |
|---|
| Para hacer debugging de cualquier aplicación que utilice esta API, se recomienda usar maxCount = 1, para recibir las actualizaciones de a una por vez. Este parámetro puede luego ser cambiado a un valor más práctico para producción, como 50. |
|---|
Request
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}Parámetros
| Nombre | Descripción |
|---|---|
| accessToken | Token de acceso con permisos para leer información de alertas. Vea esta página para más información. El access token también puede enviarse como parte del query string, utilizando el parámetro “accessToken”. |
| sequenceNumber | Valor del campo SequenceNumber de la última alerta recibida. Puede indicarse 0 para comenzar desde el inicio. |
| clientID | Identificador opcional indicando que sólo se desea obtener la lista de alertas para el cliente dado. |
| facilityID | Identificador opcional indicando que sólo se desea obtener la lista de alertas para el facility dado. |
| deviceID | Identificador opcional indicando que sólo se desea obtener la lista de alertas para el dispositivo dado. |
| endpointID | Identificador opcional indicando que sólo se desea obtener la lista de alertas para el endpoint dado. |
| maxCount | Parámetro opcional indicando la cantidad máxima de alertas a incluir en el resultado. |
| Es obligatorio incluir uno (y sólo uno) de los parámetros “clientID”, “facilityID”, “deviceID”, o “endpointID”. |
|---|
Response
La respuesta contiene la lista de alertas buscada, como se muestra en este ejemplo:
[
{
"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"
}
}
]Obtener una lista de alertas utilizando parámetros
Esta API permite obtener una lista de alertas, utilizando parámetros. Request GET...
Alarmas
Introducción Esta sección explica cómo extraer la definición de las alarmas generadas a partir de alertas de la plataforma Gear Studio, utilizando la API de...