Saltar al contenido principal
CloudStudio

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:

  1. La aplicación comienza utilizando un SequenceNumber almacenado (típicamente en almacenamiento no volátil). En la primera ejecución, este valor es 1.
  2. La aplicación ejecuta la API utilizando el (SequenceNumber almacenado + 1).
  3. La aplicación recibe una lista de datos de Endpoints, ordenados por SequenceNumber.
  4. Si la lista recibida está vacía, la aplicación espera algunos segundos, y vuelve al paso 2.
  5. Si la lista recibida no es vacía, la aplicación almacena el mayor SequenceNumber recibido.
  6. La aplicación vuelve inmediatamente al paso 2.
  7. 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

NombreDescripción
accessTokenToken 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”.
sequenceNumberValor del campo SequenceNumber del último EndpointData recibido. Puede indicarse 0 para comenzar desde el inicio.
clientIDIdentificador opcional indicando que sólo se desea obtener la lista de EndpointData para el cliente dado.
facilityIDIdentificador opcional indicando que sólo se desea obtener la lista de EndpointData para el facility dado.
deviceIDIdentificador opcional indicando que sólo se desea obtener la lista de EndpointData para el dispositivo dado.
endpointIDIdentificador opcional indicando que sólo se desea obtener la lista de EndpointData para el endpoint dado.
maxCountPará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
    }
]

Última actualización

En esta página