Obtener datos de endpoints en forma incremental
Esta API permite obtener una lista de Endpoints, en forma incremental. Esto permite obtener actualizaciones rápidas de los Endpoints sin necesidad de obtener la lista completa.
Teoría de operación
Para obtener una lista de Endpoints en forma incremental, se utiliza el campo SequenceNumber. Este campo es de tipo monotónico ascendente, es decir que al darse cambios en EndpointData, su campo SequenceNumber cambiará a un valor mayor al de cualquier otro. 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 datos de Endpoints, ordenados 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 hay una nueva lectura de datos de un Endpoint, 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.
| 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/endpointData/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 endpoints. 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 del último EndpointData recibido. Puede indicarse 0 para comenzar desde el inicio. |
| clientID | Identificador opcional indicando que sólo se desea obtener la lista de EndpointData para el cliente dado. |
| facilityID | Identificador opcional indicando que sólo se desea obtener la lista de EndpointData para el facility dado. |
| deviceID | Identificador opcional indicando que sólo se desea obtener la lista de EndpointData para el dispositivo dado. |
| endpointID | Identificador opcional indicando que sólo se desea obtener la lista de EndpointData 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 EndpointData buscados, como se muestra en este ejemplo:
[
{
"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
}
]Obtener el último dato de múltiples Endpoints
Este servicio permite consultar los últimos datos registrados de hasta 5 dispositivos al mismo tiempo , usando una única llamada. Su uso es principalmente...
Geozonas
Introducción Esta sección explica cómo extraer la definición de las geozonas creadas en la plataforma Gear Studio utilizando la API de extracción de datos. Las...