Obtenir une liste de géozones de manière incrémentale
Cette API récupère une liste de géozones de manière incrémentale, pour suivre vite les géozones créées, modifiées ou supprimées sans récupérer toute la liste.
Principe de fonctionnement
Pour obtenir une liste de géozones de manière incrémentale, on utilise le champ SequenceNumber. Ce champ est monotone croissant : lors de la création, de la modification ou de la suppression d'une géozone, son champ SequenceNumber prend une valeur supérieure à celle de toutes les autres géozones. Il est ainsi possible de récupérer les données à partir du SequenceNumber par petits lots jusqu'à ce qu'il n'y ait plus de données, puis de continuer périodiquement pour obtenir les mises à jour. Lorsque cette API renvoie une liste vide, cela signifie qu'il n'y a aucune mise à jour pour le moment.
En général, une application qui consomme cette API suit le flux suivant :
- L'application démarre avec un SequenceNumber stocké (généralement dans un stockage non volatil). Lors de la première exécution, cette valeur est 1.
- L'application exécute l'API avec (SequenceNumber stocké + 1).
- L'application reçoit une liste de géozones, triée par SequenceNumber.
- Si la liste reçue est vide, l'application attend quelques secondes et revient à l'étape 2.
- Si la liste reçue n'est pas vide, l'application stocke le SequenceNumber le plus élevé reçu.
- L'application revient immédiatement à l'étape 2.
- Lorsqu'une nouvelle géozone est créée, ou qu'une géozone existante est modifiée, son SequenceNumber prend immédiatement une valeur supérieure au dernier reçu, de sorte que ses informations sont reçues dès l'exécution suivante.
- Tout élément reçu dont la propriété Enabled vaut false indique que l'élément a été supprimé. Si la propriété Enabled vaut true, l'élément vient d'être créé ou modifié.
| Dans le flux ci-dessus, on suppose que l'application exécute toujours l'API avec le même clientID. Si l'on souhaite utiliser d'autres paramètres, la recherche doit repartir de zéro. |
|---|
| Pour déboguer une application qui utilise cette API, il est recommandé d'utiliser maxCount = 1, afin de recevoir les mises à jour une par une. Ce paramètre peut ensuite être porté à une valeur plus adaptée à la production, par exemple 50. |
|---|
| Important : la propriété SequenceNumber des géozones n'est pas modifiée lorsque des véhicules entrent dans la géozone ou en sortent, mais uniquement lorsque la configuration de la géozone change ou lorsqu'elle est supprimée. Cette méthode ne permet donc pas de suivre de manière incrémentale les événements d'entrée ou de sortie de la géozone. |
|---|
Requête
GET /api/v2/geozones/incremental/{sequenceNumber}?clientID={clientID}&maxCount={maxCount} HTTP/1.1
Host: gear.cloud.studio
Authorization: Bearer {accessToken}Paramètres
| Nom | Description |
|---|---|
| accessToken | Token d'accès disposant des permissions de lecture des informations de géozone. Consultez cette page pour plus d'informations. Le token d'accès peut également être envoyé dans la chaîne de requête, au moyen du paramètre « accessToken ». |
| sequenceNumber | Valeur du champ SequenceNumber de la dernière géozone reçue. Utilisez 0 pour partir du début. |
| clientID | Identifiant du client pour lequel la liste des géozones doit être récupérée. |
| maxCount | Paramètre facultatif indiquant le nombre maximal de géozones à inclure dans le résultat. |
Réponse
La réponse contient la liste des géozones correspondantes, comme le montre cet exemple :
[
{
"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
}
]Dernière mise à jour le
Obtenir une liste de géozones à l'aide de paramètres
Référence de l'API pour obtenir une liste de géozones filtrées par des paramètres comme le client, avec le token d'accès correspondant.
Tokens d'accès persistants
Comment obtenir un token d'accès persistant avec des permissions d'administrateur et une durée de vie définie pour intégrer des systèmes externes.