Diese API ermöglicht das inkrementelle Abrufen einer Liste von Endpunkten. Dies ermöglicht schnelle Aktualisierungen von Endpunkten, ohne die vollständige Liste abrufen zu müssen.

Funktionsweise

Um eine Liste von Endpunkten inkrementell abzurufen, wird das Feld SequenceNumber verwendet. Dieses Feld ist monoton aufsteigend, was bedeutet, dass bei Änderungen in EndpointData dessen SequenceNumber-Feld auf einen höheren Wert als alle anderen geändert wird. Dies ermöglicht das Abrufen von Daten basierend auf der SequenceNumber in kleinen Stapeln, bis keine weiteren Daten mehr abgerufen werden, und dann periodisch fortzufahren, um Aktualisierungen zu erhalten. Wenn das Ergebnis dieser API eine leere Liste ist, bedeutet dies, dass derzeit keine Aktualisierungen vorhanden sind.

Typischerweise verwendet eine Anwendung, die diese API nutzt, den folgenden Ablauf:

Die Anwendung startet mit einer gespeicherten SequenceNumber (typischerweise in einem nichtflüchtigen Speicher). Bei der ersten Ausführung ist dieser Wert 1.
Die Anwendung führt die API mit (gespeicherte SequenceNumber + 1) aus.
Die Anwendung empfängt eine Liste von Endpunkt-Daten, sortiert nach SequenceNumber.
Wenn die empfangene Liste leer ist, wartet die Anwendung einige Sekunden und kehrt zu Schritt 2 zurück.
Wenn die empfangene Liste nicht leer ist, speichert die Anwendung die höchste empfangene SequenceNumber.
Die Anwendung kehrt sofort zu Schritt 2 zurück.
Wenn es eine neue Datenablesung von einem Endpunkt gibt, ändert sich dessen SequenceNumber sofort auf einen höheren Wert als die zuletzt empfangene, sodass dessen Informationen sofort bei der nächsten Ausführung empfangen werden.

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/endpointData/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 endpoint 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 EndpointData received. Use 0 to start from the beginning.
clientID	Optional identifier indicating that only EndpointData for the given client should be retrieved.
facilityID	Optional identifier indicating that only EndpointData for the given facility should be retrieved.
deviceID	Optional identifier indicating that only EndpointData for the given device should be retrieved.
endpointID	Optional identifier indicating that only EndpointData 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

Die Antwort enthält die Liste der übereinstimmenden EndpointData, wie in diesem Beispiel gezeigt:

[
	{
        "EndpointID": 113653,
        "Timestamp_UTC": "2021-10-15T23:01:25",
        "Value": 16.93,
        "SequenceNumber": 6683852
    },
	{
        "EndpointID": 113653,
        "Timestamp_UTC": "2021-10-15T23:11:28",
        "Value": 16.97,
        "SequenceNumber": 6683864
    },
	{
        "EndpointID": 113653,
        "Timestamp_UTC": "2021-10-15T23:41:36",
        "Value": 16.93,
        "SequenceNumber": 6683874
    },
	{
        "EndpointID": 113653,
        "Timestamp_UTC": "2021-10-16T00:01:44",
        "Value": 16.99,
        "SequenceNumber": 6683887
    },
	{
        "EndpointID": 113653,
        "Timestamp_UTC": "2021-10-16T00:11:48",
        "Value": 15.93,
        "SequenceNumber": 6683900
    }
]

Endpunkt-Daten inkrementell abrufen

Funktionsweise

Anfrage

Parameter

Antwort

Auf dieser Seite