Eine Liste von Alarmen inkrementell abrufen
This API allows retrieving a list of alarms incrementally. This enables fast updates of alarms as they are opened or closed without needing to retrieve the full list.
Funktionsweise
To obtain a list of alarms incrementally, the SequenceNumber field is used. This field is monotonically ascending, meaning that when changes occur in an alarm, its SequenceNumber field will change to a value higher than any other alarm. This allows retrieving data based on the SequenceNumber in small batches until no more data is obtained, and then continuing periodically to get updates. When the result of this API is an empty list, it means that there are currently no updates.
Eine Anwendung, die diese API nutzt, verwendet typischerweise folgenden Ablauf:
- Die Anwendung startet mit einer gespeicherten SequenceNumber (typischerweise im nichtflüchtigen Speicher). Bei der ersten Ausführung beträgt dieser Wert 1.
- Die Anwendung ruft die API mit (gespeicherte SequenceNumber + 1) auf.
- The application receives a list of alarms, sorted by SequenceNumber.
- Ist die empfangene Liste leer, wartet die Anwendung einige Sekunden und kehrt zu Schritt 2 zurück.
- Ist die empfangene Liste nicht leer, speichert die Anwendung die höchste empfangene SequenceNumber.
- Die Anwendung kehrt sofort zu Schritt 2 zurück.
- When a new alarm is opened, or an existing one is modified, its SequenceNumber will immediately change to a value higher than the last received, so its information will be received immediately in the next execution.
- Any element received with the DateTimeClosed_UTC property having a non-null and non-empty value indicates that the alarm has already been closed.
| In the flow above, it is assumed that the application always executes the API with the same set of clientID, facilityID, deviceID, and endpointID parameters. If different parameters are desired, the search must start from zero. |
|---|
| For debugging any application using this API, it is recommended to use maxCount = 1, to receive updates one at a time. This parameter can later be changed to a more practical value for production, such as 50. |
|---|
Anfrage
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}Parameter
| Name | Description |
|---|---|
| accessToken | Access token with permissions to read alarm information. See this page for more information. The access token can also be sent as part of the query string, using the "accessToken" parameter. |
| sequenceNumber | Value of the SequenceNumber field from the last alarm received. Use 0 to start from the beginning. |
| clientID | Optional identifier indicating that only alarms for the given client should be retrieved. |
| facilityID | Optional identifier indicating that only alarms for the given facility should be retrieved. |
| deviceID | Optional identifier indicating that only alarms for the given device should be retrieved. |
| endpointID | Optional identifier indicating that only alarms for the given endpoint should be retrieved. |
| maxCount | Optional parameter indicating the maximum number of records to include in the result. Values greater than 500 are limited to 500 regardless of the value sent in the request. |
| It is mandatory to include one (and only one) of the parameters "clientID", "facilityID", "deviceID", or "endpointID". |
|---|
Antwort
The response contains the list of matching alarms, as shown in this example:
[
{
"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
}
]