跳转至主要内容
CloudStudio

以增量方式获取地理围栏列表

此 API 以增量方式获取地理围栏列表,可在地理围栏创建、修改或删除时快速更新,无需获取完整列表。

工作原理

要以增量方式获取地理围栏列表,需使用 SequenceNumber 字段。该字段单调递增,即创建、修改或删除地理围栏时,其 SequenceNumber 字段会变为比其他所有地理围栏都大的值。因此可以根据 SequenceNumber 分小批获取数据,直到不再有数据为止,然后定期继续获取更新。如果此 API 返回空列表,表示当前没有更新。

通常,调用此 API 的应用程序采用以下流程:

  1. 应用程序从一个已存储的 SequenceNumber 开始(通常保存在非易失性存储中)。首次执行时,该值为 1。
  2. 应用程序使用(已存储的 SequenceNumber + 1)执行 API。
  3. 应用程序收到按 SequenceNumber 排序的地理围栏列表。
  4. 如果收到的列表为空,应用程序等待几秒后返回第 2 步。
  5. 如果收到的列表不为空,应用程序存储收到的最大 SequenceNumber。
  6. 应用程序立即返回第 2 步。
  7. 当有新地理围栏创建或现有地理围栏被修改时,其 SequenceNumber 会立即变为比上次收到的值更大的值,因此下次执行时就会立即收到其信息。
  8. 收到的任何元素,如果其 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
	}
]

最后更新于

本页内容