Instanz-Mapping-API

Instanz-Mapping-API

The API allows mapping the following variables within the environment:

Client ID / Client Description / Facility ID / Facility Description / Device ID / Device Description / Address / Endpoint ID / Endpoint Description.

Hinweis:

The API has a limitation of a maximum of 500 records (if not specified, it defaults to 100) to avoid impacting the environment's performance. Therefore, it must be executed multiple times to map the entire instance.

The user can execute the service as follows:

GET/api/v2/instance/mapping/{SequenceNumber}?accessToken={accessToken}

Parameter

1. SequenceNumber = Sequenznummer. Beginnt bei 0.
2. accessToken = Access Token des globalen Administrators
3. MaxFetchItems = Maximale Anzahl der abzurufenden Elemente (Optional. Standard 100, Maximum 500)

Hinweise:

The number of elements obtained may be larger since the API will return the owner entities of each entity, in the order (Client, Facility, Device, Enpoint) and, because of this, elements may repeat between executions.

Funktionsweise

To obtain a detailed list of the instance (Endpoint, Device, Facility, Client) incrementally, the SequenceNumber field is used. This field is monotonically ascending, meaning that when changes occur in any entity, its SequenceNumber field will change to a value higher than any other entity. 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:

1. The application starts using a stored SequenceNumber (typically in non-volatile storage). On the first execution, this value is 0.
2. The application executes the API using (stored SequenceNumber 0).
3. The application receives a list of entities, and the last SequenceNumber.
4. Ist die empfangene Liste leer, wartet die Anwendung einige Sekunden und kehrt zu Schritt 2 zurück.
5. If the received list is not empty, the application stores the received SequenceNumber.
6. Die Anwendung kehrt sofort zu Schritt 2 zurück.
7. When a new entity is created, 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.

Anfrage:

GET:/api/v2/instance/mapping/{SequenceNumber}?accessToken={accessToken}&maxCount={MaxFetchItems}

Parameter

Empty entity response: when it returns empty after traversing all entities within an environment, the user can make the query again using 0 "_SequenceNumber_****"********.****

Hinweis:

Important definitions.

The complete tree will not be obtained until the entire instance has been mapped.

It will not be displayed sorted but it will be hierarchical.

Where there is no endpoint, nothing will be returned. Only the complete branch will be returned.

Antwort: The response contains the list of variables, as shown in this example: