以增量方式获取地理围栏列表
此 API 以增量方式获取地理围栏列表,可在地理围栏创建、修改或删除时快速更新,无需获取完整列表。
工作原理
要以增量方式获取地理围栏列表,需使用 SequenceNumber 字段。该字段单调递增,即创建、修改或删除地理围栏时,其 SequenceNumber 字段会变为比其他所有地理围栏都大的值。因此可以根据 SequenceNumber 分小批获取数据,直到不再有数据为止,然后定期继续获取更新。如果此 API 返回空列表,表示当前没有更新。
通常,调用此 API 的应用程序采用以下流程:
- 应用程序从一个已存储的 SequenceNumber 开始(通常保存在非易失性存储中)。首次执行时,该值为 1。
- 应用程序使用(已存储的 SequenceNumber + 1)执行 API。
- 应用程序收到按 SequenceNumber 排序的地理围栏列表。
- 如果收到的列表为空,应用程序等待几秒后返回第 2 步。
- 如果收到的列表不为空,应用程序存储收到的最大 SequenceNumber。
- 应用程序立即返回第 2 步。
- 当有新地理围栏创建或现有地理围栏被修改时,其 SequenceNumber 会立即变为比上次收到的值更大的值,因此下次执行时就会立即收到其信息。
- 收到的任何元素,如果其 Enabled 属性为 false,表示该元素已被删除;如果 Enabled 属性为 true,表示该元素刚刚创建或修改。
| 上述流程假定应用程序始终使用相同的 clientID 执行 API。如果要使用不同的参数,必须从零开始重新搜索。 |
|---|
| 调试使用此 API 的应用程序时,建议使用 maxCount = 1,以便逐条接收更新。之后可将此参数改为更适合生产环境的值,例如 50。 |
|---|
| 重要:车辆进入或离开地理围栏时,地理围栏的 SequenceNumber 属性不会改变,只有在地理围栏配置发生变化或被删除时才会改变。因此,不能使用此方法以增量方式跟踪地理围栏的进入或离开事件。 |
|---|
请求
GET /api/v2/geozones/incremental/{sequenceNumber}?clientID={clientID}&maxCount={maxCount} HTTP/1.1
Host: gear.cloud.studio
Authorization: Bearer {accessToken}参数
| 名称 | 说明 |
|---|---|
| accessToken | 具有地理围栏信息读取权限的访问令牌。更多信息请参见此页面。访问令牌也可以通过查询字符串中的 "accessToken" 参数发送。 |
| sequenceNumber | 最后收到的地理围栏的 SequenceNumber 字段值。使用 0 表示从头开始。 |
| clientID | 要获取其地理围栏列表的客户标识符。 |
| maxCount | 可选参数,表示结果中包含的最大地理围栏数。 |
响应
响应包含匹配的地理围栏列表,如下例所示:
[
{
"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
}
]最后更新于