跳转至主要内容
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. 收到的任何元素,如果其 DateTimeClosed_UTC 属性的值非 null 且非空,则表示该警报已关闭。
上述流程假定应用程序始终使用相同的 clientID、facilityID、deviceID 和 endpointID 参数组合执行 API。如果要使用不同的参数,必须从零开始重新搜索。
调试使用此 API 的应用程序时,建议使用 maxCount = 1,以便逐条接收更新。之后可将此参数改为更适合生产环境的值,例如 50。

请求

GET /api/v2/alarms/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最后收到的警报的 SequenceNumber 字段值。使用 0 表示从头开始。
clientID可选标识符,表示只获取指定客户的警报。
facilityID可选标识符,表示只获取指定设施的警报。
deviceID可选标识符,表示只获取指定设备的警报。
endpointID可选标识符,表示只获取指定端点的警报。
maxCount可选参数,表示结果中包含的最大记录数。大于 500 的值一律按 500 处理,无论请求中发送的值是多少。
必须包含 "clientID"、"facilityID"、"deviceID" 或 "endpointID" 参数中的一个(且只能一个)。

响应

响应包含匹配的警报列表,如下例所示:

[
	{
        "AlarmID": 1266896,
        "DeviceID": 7370,
        "DeviceDescription": "Controlador RUPANCO",
        "AlarmTypeID": 1,
        "AlarmTypeDescription": "Dispositivo fuera de línea",
        "AlarmSeverityID": 3,
        "AlarmSeverityDescription": "Alta",
        "DateTimeCreated_UTC": "2021-10-15T17:34:35",
        "DateTimeClosed_UTC": "2021-10-15T18:21:39",
        "SequenceNumber": 28885207,
        "MTTRMinutes": 47.0
    },
    {
        "AlarmID": 1266922,
        "DeviceID": 7370,
        "DeviceDescription": "Controlador RUPANCO",
        "AlarmTypeID": 1,
        "AlarmTypeDescription": "Dispositivo fuera de línea",
        "AlarmSeverityID": 3,
        "AlarmSeverityDescription": "Alta",
        "DateTimeCreated_UTC": "2021-10-15T19:36:41",
        "DateTimeClosed_UTC": "2021-10-15T19:37:23",
        "SequenceNumber": 28885384,
        "MTTRMinutes": 47.0
    },
    {
        "AlarmID": 1266950,
        "DeviceID": 7370,
        "DeviceDescription": "Controlador RUPANCO",
        "AlarmTypeID": 1,
        "AlarmTypeDescription": "Dispositivo fuera de línea",
        "AlarmSeverityID": 3,
        "AlarmSeverityDescription": "Alta",
        "DateTimeCreated_UTC": "2021-11-16T19:49:35",
        "DateTimeClosed_UTC": "2021-11-16T19:49:46",
        "SequenceNumber": 28948817,
        "MTTRMinutes": 47.0
    }
]

最后更新于

本页内容