实例映射 API
实例映射 API
该 API 可以映射环境中的以下变量:
客户 ID / 客户描述 / 设施 ID / 设施描述 / 设备 ID / 设备描述 / 地址 / 端点 ID / 端点描述。
注意:
为避免影响环境性能,该 API 每次最多返回 500 条记录(未指定时默认为 100 条)。因此,必须多次执行才能映射整个实例。
用户可以按如下方式执行该服务:
GET/api/v2/instance/mapping/{SequenceNumber}?accessToken={accessToken}
参数
- SequenceNumber = 序列号,从 0 开始。
- accessToken = 全局管理员访问令牌
- MaxFetchItems = 要获取的最大元素数(可选,默认 100,最大 500)
注意事项:
获取的元素数量可能更多,因为该 API 会按以下顺序返回每个实体的所属实体 (Client, Facility, Device, Enpoint),因此不同执行之间的元素可能重复。
工作原理
要以增量方式获取实例的详细列表(端点、设备、设施、客户),需使用 SequenceNumber 字段。该字段单调递增,即任何实体发生变化时,其 SequenceNumber 字段会变为比其他所有实体都大的值。因此可以根据 SequenceNumber 分小批获取数据,直到不再有数据为止,然后定期继续获取更新。如果此 API 返回空列表,表示当前没有更新。
通常,调用此 API 的应用程序采用以下流程:
- 应用程序从一个已存储的 SequenceNumber 开始(通常保存在非易失性存储中)。首次执行时,该值为 0。
- 应用程序使用(已存储的 SequenceNumber 0)执行 API。
- 应用程序收到实体列表以及最后的 SequenceNumber。
- 如果收到的列表为空,应用程序等待几秒后返回第 2 步。
- 如果收到的列表不为空,应用程序存储收到的 SequenceNumber。
- 应用程序立即返回第 2 步。
- 当有新实体创建或现有实体被修改时,其 SequenceNumber 会立即变为比上次收到的值更大的值,因此下次执行时就会立即收到其信息。
请求:
GET:/api/v2/instance/mapping/{SequenceNumber}?accessToken={accessToken}&maxCount={MaxFetchItems}
参数
| 必须包含 "SequenceNumber" 和 "accessToken" 参数。"AccessToken" 必须由全局管理员生成,"SequenceNumber" 则会随每次执行而变化。 |
|---|
**实体响应为空:**当遍历完环境中的所有实体后返回为空时,用户可以再次使用 0 "_SequenceNumber_****"********。****
注意:
重要定义。
在映射完整个实例之前,无法获得完整的树。
结果不会排序显示,但会按层级显示。
没有端点的地方不会返回任何内容,只会返回完整的分支。
**响应:**响应包含变量列表,如下例所示:
{
"SequenceNumber": 26247428,
"Clients": [
{
"ClientID": 71,
"ClientDescription": "Client A",
"Facilities": [
{
"FacilityID": 70,
"FacilityDescription": "Plant 1",
"Devices": [
{
"DeviceID": 7388,
"DeviceDescription": "Temperature sensor",
"DeviceAddress": "01698126SKYB4C3",
"Endpoints": [
{
"EndpointID": 15210,
"EndpointDescription": "Temperature"
}
]
}
]
}
]
}
]
}最后更新于