跳转至主要内容
CloudStudio

实例映射 API

实例映射 API

该 API 可以映射环境中的以下变量:

客户 ID / 客户描述 / 设施 ID / 设施描述 / 设备 ID / 设备描述 / 地址 / 端点 ID / 端点描述。

注意:

为避免影响环境性能,该 API 每次最多返回 500 条记录(未指定时默认为 100 条)。因此,必须多次执行才能映射整个实例。

用户可以按如下方式执行该服务:

GET/api/v2/instance/mapping/{SequenceNumber}?accessToken={accessToken}

参数

  1. SequenceNumber = 序列号,从 0 开始。
  2. accessToken = 全局管理员访问令牌
  3. MaxFetchItems = 要获取的最大元素数(可选,默认 100,最大 500)

注意事项:

获取的元素数量可能更多,因为该 API 会按以下顺序返回每个实体的所属实体 (Client, Facility, Device, Enpoint),因此不同执行之间的元素可能重复。

工作原理

要以增量方式获取实例的详细列表(端点、设备、设施、客户),需使用 SequenceNumber 字段。该字段单调递增,即任何实体发生变化时,其 SequenceNumber 字段会变为比其他所有实体都大的值。因此可以根据 SequenceNumber 分小批获取数据,直到不再有数据为止,然后定期继续获取更新。如果此 API 返回空列表,表示当前没有更新。

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

  1. 应用程序从一个已存储的 SequenceNumber 开始(通常保存在非易失性存储中)。首次执行时,该值为 0。
  2. 应用程序使用(已存储的 SequenceNumber 0)执行 API。
  3. 应用程序收到实体列表以及最后的 SequenceNumber。
  4. 如果收到的列表为空,应用程序等待几秒后返回第 2 步。
  5. 如果收到的列表不为空,应用程序存储收到的 SequenceNumber。
  6. 应用程序立即返回第 2 步。
  7. 当有新实体创建或现有实体被修改时,其 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"
                                }
                            ]
                        }
                    ]
                }
            ]
        }
    ]
}

最后更新于

本页内容