以增量方式获取端点数据
此 API 以增量方式获取端点列表,可快速更新端点,无需获取完整列表。
工作原理
要以增量方式获取端点列表,需使用 SequenceNumber 字段。该字段单调递增,即 EndpointData 发生变化时,其 SequenceNumber 字段会变为比其他所有值都大的值。因此可以根据 SequenceNumber 分小批获取数据,直到不再有数据为止,然后定期继续获取更新。如果此 API 返回空列表,表示当前没有更新。
通常,调用此 API 的应用程序采用以下流程:
- 应用程序从一个已存储的 SequenceNumber 开始(通常保存在非易失性存储中)。首次执行时,该值为 1。
- 应用程序使用(已存储的 SequenceNumber + 1)执行 API。
- 应用程序收到按 SequenceNumber 排序的端点数据列表。
- 如果收到的列表为空,应用程序等待几秒后返回第 2 步。
- 如果收到的列表不为空,应用程序存储收到的最大 SequenceNumber。
- 应用程序立即返回第 2 步。
- 当端点有新的数据读数时,其 SequenceNumber 会立即变为比上次收到的值更大的值,因此下次执行时就会立即收到其信息。
| 上述流程假定应用程序始终使用相同的 clientID、facilityID、deviceID 和 endpointID 参数组合执行 API。如果要使用不同的参数,必须从零开始重新搜索。 |
|---|
| 调试使用此 API 的应用程序时,建议使用 maxCount = 1,以便逐条接收更新。之后可将此参数改为更适合生产环境的值,例如 50。 |
|---|
请求
GET /api/v2/endpointData/incremental/{sequenceNumber}?clientID={clientID}&facilityID={facilityID}&deviceID={deviceID}&endpointID={endpointID}&maxCount={maxCount} HTTP/1.1
Host: gear.cloud.studio
Authorization: Bearer {accessToken}参数
| 名称 | 说明 |
|---|---|
| accessToken | 具有端点信息读取权限的访问令牌。更多信息请参见此页面。访问令牌也可以通过查询字符串中的 "accessToken" 参数发送。 |
| sequenceNumber | 最后收到的 EndpointData 的 SequenceNumber 字段值。使用 0 表示从头开始。 |
| clientID | 可选标识符,表示只获取指定客户的 EndpointData。 |
| facilityID | 可选标识符,表示只获取指定设施的 EndpointData。 |
| deviceID | 可选标识符,表示只获取指定设备的 EndpointData。 |
| endpointID | 可选标识符,表示只获取指定端点的 EndpointData。 |
| maxCount | 可选参数,表示结果中包含的最大记录数。大于 500 的值一律按 500 处理,无论请求中发送的值是多少。 |
| 必须包含 "clientID"、"facilityID"、"deviceID" 或 "endpointID" 参数中的一个(且只能一个)。 |
|---|
响应
响应包含匹配的 EndpointData 列表,如下例所示:
[
{
"EndpointID": 113653,
"Timestamp_UTC": "2021-10-15T23:01:25",
"Value": 16.93,
"SequenceNumber": 6683852
},
{
"EndpointID": 113653,
"Timestamp_UTC": "2021-10-15T23:11:28",
"Value": 16.97,
"SequenceNumber": 6683864
},
{
"EndpointID": 113653,
"Timestamp_UTC": "2021-10-15T23:41:36",
"Value": 16.93,
"SequenceNumber": 6683874
},
{
"EndpointID": 113653,
"Timestamp_UTC": "2021-10-16T00:01:44",
"Value": 16.99,
"SequenceNumber": 6683887
},
{
"EndpointID": 113653,
"Timestamp_UTC": "2021-10-16T00:11:48",
"Value": 15.93,
"SequenceNumber": 6683900
}
]最后更新于