Obtener una lista de alarmas en forma incremental
Esta API permite obtener una lista de alarmas, en forma incremental. Esto permite obtener actualizaciones rápidas de las alarmas a medida que son abiertas o cerradas sin necesidad de obtener la lista completa.
Teoría de operación
Para obtener una lista de alarmas en forma incremental, se utiliza el campo SequenceNumber. Este campo es de tipo monotónico ascendente, es decir que al darse cambios en una alarma, su campo SequenceNumber cambiará a un valor mayor al de cualquier otra alarma. 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 alarmas, ordenadas por SequenceNumber.
- Si la lista recibida está 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 abre una nueva alarma, 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 DateTimeClosed_UTC con valor no nulo ni vacio, indica que esa alarma ya ha sido cerrada.
| 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/alarms/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 alarmas. 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 alarma recibida. Puede indicarse 0 para comenzar desde el inicio. |
| clientID | Identificador opcional indicando que sólo se desea obtener la lista de alarmas para el cliente dado. |
| facilityID | Identificador opcional indicando que sólo se desea obtener la lista de alarmas para el facility dado. |
| deviceID | Identificador opcional indicando que sólo se desea obtener la lista de alarmas para el dispositivo dado. |
| endpointID | Identificador opcional indicando que sólo se desea obtener la lista de alarmas para el endpoint dado. |
| maxCount | Parámetro opcional indicando la cantidad máxima de registros a incluir en el resultado, valores superiores a 500 se limitan a 500 independientemente del valor enviado en el request. |
| Es obligatorio incluir uno (y sólo uno) de los parámetros “clientID”, “facilityID”, “deviceID”, o “endpointID”. |
|---|
Response
La respuesta contiene la lista de alarmas buscadas, como se muestra en este ejemplo:
[
{
"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
}
]Obtener una lista de alarmas utilizando parámetros
Esta API permite obtener una lista de alarmas, utilizando parámetros. Request GET...
Datos de endpoints
Introducción Esta sección explica cómo extraer los datos de los Endpoints creados en la plataforma Gear Studio utilizando la API de extracción de datos. Para...