以增量方式获取警报列表
此 API 以增量方式获取警报列表,可在警报打开或关闭时快速更新,无需获取完整列表。
工作原理
要以增量方式获取警报列表,需使用 SequenceNumber 字段。该字段单调递增,即警报发生变化时,其 SequenceNumber 字段会变为比其他所有警报都大的值。因此可以根据 SequenceNumber 分小批获取数据,直到不再有数据为止,然后定期继续获取更新。如果此 API 返回空列表,表示当前没有更新。
通常,调用此 API 的应用程序采用以下流程:
- 应用程序从一个已存储的 SequenceNumber 开始(通常保存在非易失性存储中)。首次执行时,该值为 1。
- 应用程序使用(已存储的 SequenceNumber + 1)执行 API。
- 应用程序收到按 SequenceNumber 排序的警报列表。
- 如果收到的列表为空,应用程序等待几秒后返回第 2 步。
- 如果收到的列表不为空,应用程序存储收到的最大 SequenceNumber。
- 应用程序立即返回第 2 步。
- 当有新警报打开或现有警报被修改时,其 SequenceNumber 会立即变为比上次收到的值更大的值,因此下次执行时就会立即收到其信息。
- 收到的任何元素,如果其 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
}
]最后更新于