Obtener una lista de geozonas en forma incremental
Esta API permite obtener una lista de geozonas, en forma incremental. Esto permite obtener actualizaciones rápidas de las geozonas 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 geozonas 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 geozona, su campo SequenceNumber cambiará a un valor mayor al de cualquier otra geozona. 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 geozonas, 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 geozona, 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 clientID. 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. |
|---|
| Importante: la propiedad SequenceNumber de las geozonas no se modifica cuando los vehículos ingresan o egresan de la geozona, sino sólo cuando cambia la configuración de la geozona, o cuando es eliminada. Por lo tanto, este método no puede emplearse para conocer incrementalmente los eventos de ingreso o egreso a la geozona. |
|---|
Request
GET /api/v2/geozones/incremental/{sequenceNumber}?clientID={clientID}&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 geozonas. 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 geozona recibida. Puede indicarse 0 para comenzar desde el inicio. |
| clientID | Identificador del cliente para el cual se desea obtener la lista de geozonas. |
| maxCount | Parámetro opcional indicando la cantidad máxima de geozonas a incluir en el resultado. |
Response
La respuesta contiene la lista de geozonas buscada, como se muestra en este ejemplo:
[
{
"GeozoneID":35,
"ClientID":79,
"Description":"Hokkaido",
"ExternalCode":"3424",
"Polygon":{
"PolygonID":35,
"Points":[
[
43.93935551,
142.57453478
],
[
43.49469073,
143.60724962
],
[
43.06278289,
143.49738634
],
[
42.9020392,
142.92609728
],
[
42.96638711,
142.6624254
],
[
42.96638711,
142.17902696
],
[
42.9020392,
141.80549181
],
[
42.88594172,
141.49787462
],
[
43.06278289,
141.34406603
],
[
43.19107519,
141.6077379
],
[
43.36703768,
141.93732775
],
[
43.669774,
141.82746446
],
[
43.82849869,
142.02521837
],
[
43.90770318,
142.37678087
]
],
"BorderColor":0,
"BorderWidth":3,
"BorderOpacity":100.0,
"FillColor":0,
"FillOpacity":50.0
},
"Vehicles":[
{
"VehicleID":133,
"Description":"Asset 70",
"LicensePlate":"XD1320070"
},
{
"VehicleID":134,
"Description":"Asset 71",
"LicensePlate":"XD1320071"
},
{
"VehicleID":135,
"Description":"Asset 72",
"LicensePlate":"XD1320072"
},
{
"VehicleID":136,
"Description":"Asset 73",
"LicensePlate":"XD1320073"
},
{
"VehicleID":138,
"Description":"Asset 75",
"LicensePlate":"XD1320075"
},
{
"VehicleID":139,
"Description":"Asset 76",
"LicensePlate":"XD1320076"
},
{
"VehicleID":140,
"Description":"Asset 77",
"LicensePlate":"XD1320077"
},
{
"VehicleID":141,
"Description":"Asset 78",
"LicensePlate":"XD1320078"
},
{
"VehicleID":142,
"Description":"Asset 79",
"LicensePlate":"XD1320079"
}
],
"SequenceNumber":74017203,
"Enabled":true
},
{
"GeozoneID":36,
"ClientID":79,
"Description":"1",
"ExternalCode":null,
"Polygon":{
"PolygonID":36,
"Points":[
[
0.870633,
177.7532959
],
[
0.62895465,
178.34655762
],
[
1.34295563,
177.84118652
]
],
"BorderColor":0,
"BorderWidth":3,
"BorderOpacity":100.0,
"FillColor":0,
"FillOpacity":50.0
},
"Vehicles":[
],
"SequenceNumber":74017204,
"Enabled":true
},
{
"GeozoneID":37,
"ClientID":79,
"Description":"2",
"ExternalCode":null,
"Polygon":{
"PolygonID":37,
"Points":[
[
-1.26057944,
178.3026123
],
[
-0.35979988,
179.63195801
],
[
-0.62346182,
-179.34631348
]
],
"BorderColor":0,
"BorderWidth":3,
"BorderOpacity":100.0,
"FillColor":0,
"FillOpacity":50.0
},
"Vehicles":[
],
"SequenceNumber":74017205,
"Enabled":true
}
]Obtener una lista de geozonas utilizando parámetros
Esta API permite obtener una lista de geozonas, utilizando parámetros. Request GET /api/v2/geozones?clientID={clientID}&maxCount={maxCount} HTTP/1.1 Host:...
Access Tokens Persistentes
Esta API permite obtener un token que tendrá permisos de administrador, definiendo el tiempo de vida del mismo. Estos tokens una vez generados permiten la...