Eine Liste von Geozonen inkrementell abrufen
Diese API ermöglicht das inkrementelle Abrufen einer Liste von Geozonen. Dies ermöglicht schnelle Aktualisierungen von Geozonen, wenn diese erstellt, geändert oder gelöscht werden, ohne die vollständige Liste abrufen zu müssen.
Funktionsweise
Um eine Liste von Geozonen inkrementell abzurufen, wird das Feld SequenceNumber verwendet. Dieses Feld ist monoton aufsteigend, was bedeutet, dass beim Erstellen, Ändern oder Löschen einer Geozone ihr SequenceNumber-Feld auf einen höheren Wert als bei jeder anderen Geozone geändert wird. Dies ermöglicht das Abrufen von Daten basierend auf der SequenceNumber in kleinen Stapeln, bis keine weiteren Daten mehr abgerufen werden, und dann periodisch fortzufahren, um Aktualisierungen zu erhalten. Wenn das Ergebnis dieser API eine leere Liste ist, bedeutet dies, dass derzeit keine Aktualisierungen vorhanden sind.
Typischerweise verwendet eine Anwendung, die diese API nutzt, den folgenden Ablauf:
- Die Anwendung startet mit einer gespeicherten SequenceNumber (typischerweise in einem nichtflüchtigen Speicher). Bei der ersten Ausführung ist dieser Wert 1.
- Die Anwendung führt die API mit (gespeicherte SequenceNumber + 1) aus.
- Die Anwendung empfängt eine Liste von Geozonen, sortiert nach SequenceNumber.
- Wenn die empfangene Liste leer ist, wartet die Anwendung einige Sekunden und kehrt zu Schritt 2 zurück.
- Wenn die empfangene Liste nicht leer ist, speichert die Anwendung die höchste empfangene SequenceNumber.
- Die Anwendung kehrt sofort zu Schritt 2 zurück.
- Wenn eine neue Geozone erstellt oder eine bestehende geändert wird, ändert sich ihre SequenceNumber sofort auf einen höheren Wert als die zuletzt empfangene, sodass ihre Informationen sofort bei der nächsten Ausführung empfangen werden.
- Jedes empfangene Element mit der Eigenschaft Enabled auf false zeigt an, dass das Element gelöscht wurde. Wenn die Eigenschaft Enabled true ist, zeigt dies an, dass das Element gerade erstellt oder geändert wurde.
| In the flow above, it is assumed that the application always executes the API with the same clientID. If different parameters are desired, the search must start from zero. |
|---|
| For debugging any application using this API, it is recommended to use maxCount = 1, to receive updates one at a time. This parameter can later be changed to a more practical value for production, such as 50. |
|---|
| Important: the SequenceNumber property of geozones is not modified when vehicles enter or exit the geozone, but only when the geozone configuration changes, or when it is deleted. Therefore, this method cannot be used to incrementally track entry or exit events for the geozone. |
|---|
Anfrage
GET /api/v2/geozones/incremental/{sequenceNumber}?clientID={clientID}&maxCount={maxCount} HTTP/1.1
Host: gear.cloud.studio
Authorization: Bearer {accessToken}Parameter
| Name | Description |
|---|---|
| accessToken | Access token with permissions to read geozone information. See this page for more information. The access token can also be sent as part of the query string, using the "accessToken" parameter. |
| sequenceNumber | Value of the SequenceNumber field from the last geozone received. Use 0 to start from the beginning. |
| clientID | Client identifier for which the list of geozones should be retrieved. |
| maxCount | Optional parameter indicating the maximum number of geozones to include in the result. |
Antwort
Die Antwort enthält die Liste der übereinstimmenden Geozonen, wie in diesem Beispiel gezeigt:
[
{
"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
}
]Eine Liste von Geozonen anhand von Parametern abrufen
This API allows retrieving a list of geozones using parameters. Request GET /api/v2/geozones?clientID={clientID}&maxCount={maxCount} HTTP/1.1 Host:...
Persistente Access Tokens
This API allows obtaining a token with administrator permissions, defining its lifetime. Once generated, these tokens allow the invocation of various...