此 API 以增量方式获取提醒列表，可在提醒创建、修改或删除时快速更新，无需获取完整列表。

工作原理

要以增量方式获取提醒列表，需使用 SequenceNumber 字段。该字段单调递增，即创建、修改或删除提醒时，其 SequenceNumber 字段会变为比其他所有提醒都大的值。因此可以根据 SequenceNumber 分小批获取数据，直到不再有数据为止，然后定期继续获取更新。如果此 API 返回空列表，表示当前没有更新。

通常，调用此 API 的应用程序采用以下流程：

应用程序从一个已存储的 SequenceNumber 开始（通常保存在非易失性存储中）。首次执行时，该值为 1。
应用程序使用（已存储的 SequenceNumber + 1）执行 API。
应用程序收到按 SequenceNumber 排序的提醒列表。
如果收到的列表为空，应用程序等待几秒后返回第 2 步。
如果收到的列表不为空，应用程序存储收到的最大 SequenceNumber。
应用程序立即返回第 2 步。
当有新提醒创建或现有提醒被修改时，其 SequenceNumber 会立即变为比上次收到的值更大的值，因此下次执行时就会立即收到其信息。
收到的任何元素，如果其 Enabled 属性为 false，表示该元素已被删除；如果 Enabled 属性为 true，表示该元素刚刚创建或修改。

上述流程假定应用程序始终使用相同的 clientID、facilityID、deviceID 和 endpointID 参数组合执行 API。如果要使用不同的参数，必须从零开始重新搜索。

调试使用此 API 的应用程序时，建议使用 maxCount = 1，以便逐条接收更新。之后可将此参数改为更适合生产环境的值，例如 50。

请求

GET /api/v2/alerts/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	可选参数，表示结果中包含的最大提醒数。

必须包含 "clientID"、"facilityID"、"deviceID" 或 "endpointID" 参数中的一个（且只能一个）。

响应

响应包含匹配的提醒列表，如下例所示：

[
	{
		"AlertID": 211,
		"VariableTypeID": 1,
		"EndpointID": 114092,
		"ConditionType": 3,
		"Threshold": 25,
		"ClientID": 4,
		"FacilityID": 184,
		"NormalConditionType": 6,
		"NormalThreshold": 24,
		"MinimumDurationSeconds": 300,
		"NotificationEmails": ["someone@somewhere.com"],
		"NotificationSMSNumbers": ["+1123456789"],
		"NotificationVoiceNumbers": ["+1123456789"],
		"Tags": ["default", "gateway-default"],
		"SequenceNumber": 45701485,
		"Enabled": true,
		"Schedules": [],
        "Timezone": {
            "CurrentOffsetMinutes": -180,
            "TimeZoneCode": "america/argentina/buenos_aires"
        }
	},
	{
		"AlertID": 212,
		"VariableTypeID": 1,
		"EndpointID": 114092,
		"ConditionType": 5,
		"Threshold": 20,
		"ClientID": 4,
		"FacilityID": 184,
		"NormalConditionType": 3,
		"NormalThreshold": 22,
		"MinimumDurationSeconds": 300,
		"NotificationEmails": ["someone@somewhere.com"],
		"NotificationSMSNumbers": ["+1123456789"],
		"NotificationVoiceNumbers": ["+1123456789"],
		"Tags": ["default", "gateway-default"],
		"SequenceNumber": 45701485,
		"Enabled": true,
		"Schedules": [
		     {
                "Days": [
                    1,
                    2,
                    4,
                    5
                ],
                "StartTime": {
                    "Hour": 0,
                    "Millisecond": 0,
                    "Minute": 0,
                    "Second": 0
                },
                "EndTime": {
                    "Hour": 23,
                    "Millisecond": 999,
                    "Minute": 0,
                    "Second": 59
                }
            }
        ],
        "Timezone": {
            "CurrentOffsetMinutes": -180,
            "TimeZoneCode": "america/argentina/buenos_aires"
        }
	}
]

以增量方式获取提醒列表

工作原理

请求

参数

响应

本页内容