增量获取地理围栏列表
This API allows retrieving a list of geozones incrementally. This enables fast updates of geozones as they are created, modified, or deleted, without needing to retrieve the full list.
Theory of operation
To obtain a list of geozones incrementally, the SequenceNumber field is used. This field is monotonically ascending, meaning that when creating, modifying, or deleting a geozone, its SequenceNumber field will change to a value higher than any other geozone. This allows retrieving data based on the SequenceNumber in small batches until no more data is obtained, and then continuing periodically to get updates. When the result of this API is an empty list, it means that t此处 are currently no updates.
Typically, an application consuming this API uses the following flow:
- The application starts using a stored SequenceNumber (typically in non-volatile storage). On the first execution, this value is 1.
- The application executes the API using (stored SequenceNumber + 1).
- The application receives a list of geozones, sorted by SequenceNumber.
- If the received list is empty, the application waits a few seconds and returns to step 2.
- If the received list is not empty, the application stores the highest SequenceNumber received.
- The application immediately returns to step 2.
- When a new geozone is created, or an existing one is modified, its SequenceNumber will immediately change to a value higher than the last received, so its information will be received immediately in the next execution.
- Any element received with the Enabled property set to false indicates that the element has been deleted. If the Enabled property is true, it indicates that the element has just been created or modified.
| In the flow 上方, 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. |
|---|
| 重要说明: the SequenceNumber property of geozones is not modified when vehicles 输入 or exit the geozone, but only when the geozone configuration changes, or when it is deleted. T此处fore, this method cannot be used to incrementally track entry or exit events for the geozone. |
|---|
Request
GET /api/v2/geozones/incremental/{sequenceNumber}?clientID={clientID}&maxCount={maxCount} HTTP/1.1
Host: gear.cloud.studio
Authorization: Bearer {accessToken}参数
| 名称 | 说明 |
|---|---|
| accessToken | Access token with permissions to read geozone information. See this page for more information. The 访问令牌 can also be sent as part of the query string, 使用 "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. |
Response
The response contains the list of matching geozones, as shown in this example:
[
{
"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
}
]使用参数获取地理围栏列表
This API allows retrieving a list of geozones using parameters. Request GET /api/v2/geozones?clientID={clientID}&maxCount={maxCount} HTTP/1.1 Host:...
持久访问令牌
This API allows obtaining a token with administrator permissions, defining its lifetime. Once generated, these tokens allow the invocation of various...