API de mappage d'instance

API de mappage d'instance

L'API permet de mapper les variables suivantes au sein de l'environnement :

ID client / Description client / ID installation / Description installation / ID appareil / Description appareil / Adresse / ID endpoint / Description endpoint.

Remarque :

L'API est limitée à 500 enregistrements au maximum (100 par défaut si rien n'est précisé) afin de ne pas affecter les performances de l'environnement. Elle doit donc être exécutée plusieurs fois pour mapper toute l'instance.

L'utilisateur peut exécuter le service de la manière suivante :

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

Paramètres

1. SequenceNumber = Numéro de séquence. Commence à 0.
2. accessToken = Token d'accès d'administrateur global
3. MaxFetchItems = Nombre maximal d'éléments à récupérer (facultatif ; 100 par défaut, 500 au maximum)

Remarques :

Le nombre d'éléments obtenus peut être plus élevé, car l'API renvoie les entités propriétaires de chaque entité, dans l'ordre (Client, Facility, Device, Enpoint) ; de ce fait, des éléments peuvent se répéter d'une exécution à l'autre.

Principe de fonctionnement

Pour obtenir de manière incrémentale une liste détaillée de l'instance (Endpoint, Device, Facility, Client), on utilise le champ SequenceNumber. Ce champ est monotone croissant : lorsqu'une entité subit une modification, son champ SequenceNumber prend une valeur supérieure à celle de toutes les autres entités. Il est ainsi possible de récupérer les données à partir du SequenceNumber par petits lots jusqu'à ce qu'il n'y ait plus de données, puis de continuer périodiquement pour obtenir les mises à jour. Lorsque cette API renvoie une liste vide, cela signifie qu'il n'y a aucune mise à jour pour le moment.

En général, une application qui consomme cette API suit le flux suivant :

1. L'application démarre avec un SequenceNumber stocké (généralement dans un stockage non volatil). Lors de la première exécution, cette valeur est 0.
2. L'application exécute l'API avec (SequenceNumber stocké 0).
3. L'application reçoit une liste d'entités, ainsi que le dernier SequenceNumber.
4. Si la liste reçue est vide, l'application attend quelques secondes et revient à l'étape 2.
5. Si la liste reçue n'est pas vide, l'application stocke le SequenceNumber reçu.
6. L'application revient immédiatement à l'étape 2.
7. Lorsqu'une nouvelle entité est créée, ou qu'une entité existante est modifiée, son SequenceNumber prend immédiatement une valeur supérieure au dernier reçu, de sorte que ses informations sont reçues dès l'exécution suivante.

Requête :

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

Paramètres

Réponse sans entités : lorsque la réponse est vide après le parcours de toutes les entités d'un environnement, l'utilisateur peut relancer la requête avec 0 "_SequenceNumber_****"********.****

Remarque :

Définitions importantes.

L'arborescence complète n'est obtenue qu'une fois toute l'instance mappée.

Le résultat n'est pas trié, mais il est hiérarchique.

Là où il n'y a pas d'endpoint, rien n'est renvoyé. Seule la branche complète est renvoyée.

Réponse : La réponse contient la liste des variables, comme le montre cet exemple :

{
    "SequenceNumber": 26247428,
    "Clients": [
        {
            "ClientID": 71,
            "ClientDescription": "Client A",
            "Facilities": [
                {
                    "FacilityID": 70,
                    "FacilityDescription": "Plant 1",
                    "Devices": [
                        {
                            "DeviceID": 7388,
                            "DeviceDescription": "Temperature sensor",
                            "DeviceAddress": "01698126SKYB4C3",
                            "Endpoints": [
                                {
                                    "EndpointID": 15210,
                                    "EndpointDescription": "Temperature"
                                }
                            ]
                        }
                    ]
                }
            ]
        }
    ]
}