CRUD des objets IoT avec l’API OData

Dans cet article

    Afficher plus
    Réduire

    1. Introduction

    Cet article montre comment lire, créer, modifier et supprimer les objets IoT exposés par Immersive RestFrontage : Equipment, EquipmentInstance et SupervisionScope. Ces quatre opérations constituent le CRUD. Il décrit aussi la gestion de leur association, représentée par SupervisionScopeEquipmentInstance.

    Le parcours commence toujours par la recherche de l’Organization concernée. Son identifiant permet ensuite de sélectionner les bonnes ressources et de vérifier leur appartenance avant chaque écriture. Nous prendrons l’exemple d’un capteur de température rattaché à un bâtiment.

    2. Comprendre les objets

    Objet Rôle Relation principale
    Organization Organisation propriétaire des données. Son Identifier définit le périmètre du traitement.
    Equipment Famille d’équipements IoT. Elle porte OrganizationIdentifier et peut posséder plusieurs instances.
    EquipmentInstance Équipement réel installé ou suivi. Elle appartient à une famille via ParentEquipmentIdentifier. Son organisation est celle de cette famille.
    SupervisionScope Périmètre de supervision, rattaché à une organisation. Un périmètre peut contenir plusieurs instances, et une instance peut être associée à plusieurs périmètres.
    SupervisionScopeEquipmentInstance Association entre un périmètre et une instance. Sa clé est composée de SupervisionScopeIdentifier et EquipmentInstanceIdentifier.

    Equipment décrit donc le modèle de l’équipement, tandis que EquipmentInstance désigne un objet concret. Pour rattacher une instance à un périmètre, on crée l’association ; la création du périmètre ou de l’instance ne crée pas automatiquement ce lien.

    Un objet Equipment sera par exemple Ascenseur, Capteur température, Porte automatique, Véhicule d'intervention, ...

    Un objet EquipmentInstance sera par exemple Ascenseur ATR5910, Capteur température niveau 0 hall, Porte automatique coté quai, Véhicule d'intervention X312A, ... Via la relation ParentIdentifier on peut lier une parentalité entre instance d'équipement. Par exemple une armoire electrique pourrait avoir en enfant les disjoncteurs, automates ... Un objet EquipmentInstance a forcément une propriété ParentEquipmentIdentifier pointant vers un Equipment existant.

    Un objet SupervisionScope sera par exemple Equipements IOT niveau 4, Batiment Administratif, Gare de Raincourt, ...

    SupervisionScopeEquipmentInstance possède forcement les propriétés SupervisionScopeIdentifier et EquipmentInstanceIdentifier pointant vers des objets existants.

    Le schéma suivant défini la relation entre les différents objets :

    flowchart TD
        O["Organization"] -->|"OrganizationIdentifier"| E["Equipment : famille"]
        E -->|"ParentEquipmentIdentifier"| I["EquipmentInstance : objet concret"]
        O -->|"OrganizationIdentifier"| S["SupervisionScope : périmètre"]
        S -->|"SupervisionScopeIdentifier"| L["SupervisionScopeEquipmentInstance"]
        I -->|"EquipmentInstanceIdentifier"| L
    

    3. Préparer les appels

    3.1 Authentification

    Les exemples utilisent un jeton Bearer. Transmettez l’en-tête Authorization sur chaque requête, y compris lorsque les exemples de lecture n’affichent que l’URL.

    Pour plus d'information reportez vous au tutoriel "S'authentifier par code auprès d'Immersive : mot de passe, MFA et clés API"

    3.2 Maîtriser la syntaxe OData

    OData, pour Open Data Protocol, définit une manière standard de consulter et de modifier des données à travers HTTP. Dans Immersive, les objets sont exposés sous forme de collections, comme Equipments, et de ressources identifiées, comme Equipments(12). Le client décrit dans l’URL les données à sélectionner ; le serveur exécute la requête dans les limites de ses fonctionnalités et des droits du compte.

    Les méthodes HTTP indiquent l’opération : GET lit, POST crée, PATCH modifie certaines propriétés et DELETE supprime. OData complète ces opérations avec une syntaxe commune pour filtrer, trier, paginer et parcourir les relations. Le tutoriel de prise en main OData présente ces principes.

    3.2.1 Lire une URL OData

    Une URL comporte l’adresse du serveur, le chemin de la ressource et, éventuellement, des options après ?. Plusieurs options sont séparées par &.

    Élément Signification dans cet article
    /odata/Equipments Interroger la collection des familles d’équipements.
    /odata/Equipments(12) Cibler la famille dont l’identifiant est 12.
    /odata/EquipmentInstances(34)/ParentEquipment Suivre la relation de l’instance 34 vers sa famille.
    OrganizationIdentifier eq 7 Tester si l’identifiant d’organisation est égal à 7.
    Name eq 'Capteur de température' Comparer une propriété à une chaîne entre apostrophes.
    and, or, not Combiner des conditions : et, ou, négation.

    Les nombres et booléens s’écrivent sans apostrophes, par exemple Identifier eq 12 et IsEnabled eq true. Les noms des propriétés doivent correspondre au modèle publié par le serveur.

    3.2.2 Choisir les options de lecture

    Option Effet Exemple
    $filter Choisir les objets répondant à une condition. $filter=OrganizationIdentifier eq 7
    $select Choisir les propriétés à recevoir pour chaque objet. $select=Identifier,Name
    $orderby Définir l’ordre des résultats ; le tri est croissant par défaut. $orderby=Identifier
    $top Demander au plus le nombre indiqué d’objets. $top=100
    $skip Ignorer les premiers objets dans l’ordre demandé. $skip=100
    $expand Inclure les objets liés dans la réponse. $expand=ParentEquipment
    $count Demander le nombre total d’objets correspondant au filtre, avant pagination. $count=true

    $filter détermine quels objets sont retournés ; $select détermine quelles propriétés sont retournées. $expand ajoute le détail des relations. Ces options sont décrites dans la présentation des options de requête Microsoft Learn.

    3.2.3 Tutoriels pour approfondir

    Ces ressources sont en anglais et décrivent le protocole général. Leurs modèles d’exemple ne sont pas ceux d’Immersive ; les fonctionnalités utilisables dépendent du modèle et de la configuration du serveur. Les exemples de cet article appliquent cette syntaxe aux objets IoT effectivement exposés.

    3.3 Modèle et format des requêtes

    L’API OData est exposée sous /odata. Consultez son modèle avant d’intégrer un client afin de vérifier toutes les propriétés et leurs types :

    GET {{server}}/odata/$metadata
    Authorization: Bearer {{token}}
    Accept: application/xml
    
    

    Les écritures utilisent JSON. Le jeton doit être associé à un compte autorisé à lire ou modifier les données demandées.

    Authorization: Bearer {{token}}
    Content-Type: application/json
    Accept: application/json
    
    

    Dans les URL de cet article, les espaces des filtres sont laissés lisibles. Le client HTTP doit encoder les paramètres de requête. Dans une chaîne OData, une apostrophe se double : Name eq 'L''Atelier'.

    4. Retrouver l’organisation avant toute opération IoT

    4.1 Rechercher l’organisation cible

    4.1.1 Découvrir les organisations accessibles

    Si vous ne connaissez ni le nom ni l’identifiant de l’organisation, commencez par lister celles qui sont accessibles au compte authentifié. Cette requête OData ne contient aucun filtre de nom :

    GET {{server}}/odata/Organizations?$select=Identifier,Name,DistinguishedName&$orderby=Name,Identifier&$top=100
    Authorization: Bearer {{token}}
    Accept: application/json
    
    

    Elle demande jusqu’à 100 organisations de votre périmètre, triées par nom puis par identifiant. Pour chacune, elle retourne l’identifiant à utiliser dans les opérations IoT, le nom à afficher et le DistinguishedName, qui permet de distinguer les organisations de l’annuaire. Le serveur limite cette liste aux organisations accessibles au compte ; il ne s’agit pas d’une liste globale de toutes les organisations.

    Extrait illustratif de réponse :

    {
      "value": [
        {
          "Identifier": 9,
          "Name": "Atelier Nord",
          "DistinguishedName": "OU=Atelier Nord,DC=exemple,DC=fr"
        },
        {
          "Identifier": 7,
          "Name": "Organisation Demo",
          "DistinguishedName": "OU=Organisation Demo,DC=exemple,DC=fr"
        }
      ]
    }
    
    

    Choisissez l’organisation correspondant au traitement souhaité et conservez son Identifier. Si votre compte accède à plusieurs organisations, prévoyez une sélection explicite dans l’application ou sa configuration. Une liste vide ne permet pas de poursuivre. Pour parcourir une liste plus longue, suivez @odata.nextLink s’il est fourni, ou poursuivez avec le même tri et $skip=100, puis $skip=200.

    4.1.2 Alternative facultative : la WebAPI OrganizationsInScope

    Si votre intégration connaît déjà le DistinguishedName complet du compte utilisateur utilisé, elle peut aussi retrouver ses organisations avec l’appel suivant :

    GET {{server}}/api/Security/Users/{{userDistinguishedNameEncoded}}/OrganizationsInScope
    Authorization: Bearer {{token}}
    Accept: application/json
    
    

    Remplacez {{userDistinguishedNameEncoded}} par le DN de cet utilisateur, encodé comme un segment d’URL. Il s’agit du DN du compte, pas de celui de l’organisation recherchée. Avec une clé API, utilisez le compte associé à cette clé et les deux en-têtes d’authentification par clé.

    4.1.3 Rechercher une organisation dont le nom est connu

    Une fois le nom découvert dans la liste, ou s’il est déjà connu par configuration, vous pouvez effectuer une recherche ciblée :

    GET {{server}}/odata/Organizations?$filter=Name eq 'Organisation Demo'&$select=Identifier,Name,DistinguishedName&$top=2
    Authorization: Bearer {{token}}
    Accept: application/json
    
    

    Extrait illustratif de réponse, sans les annotations OData :

    {
      "value": [
        {
          "Identifier": 7,
          "Name": "Organisation Demo",
          "DistinguishedName": "OU=Organisation Demo,DC=exemple,DC=fr"
        }
      ]
    }
    
    

    Les résultats de cette lecture de collection OData se trouvent dans le tableau value. Pour cette recherche ciblée, traitez explicitement ces trois situations :

    • Aucun résultat : arrêter le traitement. L’organisation peut être absente ou inaccessible au compte utilisé.
    • Un résultat : vérifier qu’il correspond à l’organisation attendue, puis conserver son Identifier.
    • Plusieurs résultats : préciser la sélection, par exemple à l’aide du DistinguishedName attendu. Ne pas choisir arbitrairement le premier résultat.

    La limite $top=2 suffit pour détecter une ambiguïté. Elle ne sert pas à choisir une organisation.

    Si un identifiant est déjà fourni par la configuration de votre intégration, vérifiez tout de même son existence, son accessibilité et son identité :

    GET {{server}}/odata/Organizations(7)?$select=Identifier,Name,DistinguishedName
    
    

    Dans la suite, 7 représente l’identifiant effectivement retrouvé. Les identifiants 12, 34 et 56 représenteront respectivement une famille, une instance et un périmètre retrouvés ou créés pendant le traitement.

    4.2 Conserver un périmètre cohérent

    Ressource Filtre d’appartenance à l’organisation 7 Rattachement à la création
    Equipment OrganizationIdentifier eq 7 "OrganizationIdentifier": 7
    EquipmentInstance ParentEquipment/OrganizationIdentifier eq 7 ParentEquipmentIdentifier doit désigner une famille de l’organisation 7.
    SupervisionScope OrganizationIdentifier eq 7 "OrganizationIdentifier": 7
    Association Vérifier l’instance et le périmètre. Utiliser les deux identifiants contrôlés.

    Effectuez cette résolution au début de chaque traitement métier, puis réutilisez l’identifiant confirmé pour les opérations qui le composent. Recommencez si le serveur, le compte ou l’organisation cible change.

    Pour les appels Bearer, vous pouvez aussi déclarer le contexte d’organisation avec cet en-tête facultatif, une fois l’organisation retrouvée :

    X-Organization-Identifier: 7
    
    

    5. Lire les objets de l’organisation

    5.1 Lister et filtrer

    Les quatre requêtes suivantes sont des lectures GET. Elles ne modifient pas les données et renvoient leurs résultats dans value, selon les droits du compte. L’organisation 7 a été choisie à l’étape précédente.

    5.1.1 Lister les familles de l’organisation

    Cette requête retourne jusqu’à 100 familles appartenant à l’organisation 7. Pour chaque famille, elle demande seulement Identifier, Name et OrganizationIdentifier. Les résultats sont triés par identifiant croissant :

    GET {{server}}/odata/Equipments?$filter=OrganizationIdentifier eq 7&$select=Identifier,Name,OrganizationIdentifier&$orderby=Identifier&$top=100
    
    

    5.1.2 Lister les instances de l’organisation

    Cette requête retourne jusqu’à 100 instances dont la famille appartient à l’organisation 7, toutes familles confondues. Elle demande l’identifiant et le nom de chaque instance, ainsi que ParentEquipmentIdentifier pour retrouver sa famille. Le tri est effectué sur l’identifiant de l’instance :

    GET {{server}}/odata/EquipmentInstances?$filter=ParentEquipment/OrganizationIdentifier eq 7&$select=Identifier,Name,ParentEquipmentIdentifier&$orderby=Identifier&$top=100
    
    

    5.1.3 Lister les périmètres de supervision

    Cette requête retourne jusqu’à 100 périmètres appartenant directement à l’organisation 7. Elle demande leur identifiant, leur nom et leur identifiant d’organisation, par identifiant croissant. Elle ne charge pas les instances associées à ces périmètres :

    GET {{server}}/odata/SupervisionScopes?$filter=OrganizationIdentifier eq 7&$select=Identifier,Name,OrganizationIdentifier&$orderby=Identifier&$top=100
    
    

    5.1.4 Limiter les instances à une famille

    Cette requête conserve uniquement les instances de la famille 12 dont l’organisation est 7. Les deux conditions doivent être remplies. Elle retourne jusqu’à 100 instances, triées par identifiant, avec les mêmes propriétés que la liste des instances précédente :

    GET {{server}}/odata/EquipmentInstances?$filter=ParentEquipment/OrganizationIdentifier eq 7 and ParentEquipmentIdentifier eq 12&$select=Identifier,Name,ParentEquipmentIdentifier&$orderby=Identifier&$top=100
    
    

    Le filtre suit une relation avec /. Il n’est pas nécessaire d’ajouter $expand pour filtrer sur une propriété du parent.

    Les options OData de sélection, expansion, filtre, tri et pagination sont disponibles. $top est limité à 200 ; cela ne signifie pas que toutes les collections sont automatiquement paginées par blocs de 200. Pour la deuxième page de 100 éléments, utilisez par exemple $orderby=Identifier&$top=100&$skip=100. Si la réponse fournit @odata.nextLink, suivez ce lien.

    5.2 Retrouver un objet métier

    Cherchez une famille par son nom à l’intérieur de l’organisation :

    GET {{server}}/odata/Equipments?$filter=OrganizationIdentifier eq 7 and Name eq 'Capteur de température'&$select=Identifier,Name,OrganizationIdentifier&$top=2
    
    

    Pour une instance, vous pouvez rechercher son nom ou une référence externe :

    GET {{server}}/odata/EquipmentInstances?$filter=ParentEquipment/OrganizationIdentifier eq 7 and InteroperabilityReference eq 'GTB-TEMP-001'&$select=Identifier,Name,ParentEquipmentIdentifier&$top=2
    
    

    Exigez un résultat unique avant de réutiliser son identifiant. Ne présumez pas qu’une référence externe est unique sans vérifier les résultats. En l’absence de résultat, ne créez un nouvel objet que si cette création fait partie du traitement attendu.

    5.3 Vérifier une cible avant modification ou suppression

    Pour une cible dont l’identifiant est connu, combinez cet identifiant avec le filtre d’organisation :

    GET {{server}}/odata/Equipments?$filter=Identifier eq 12 and OrganizationIdentifier eq 7&$select=Identifier,Name,OrganizationIdentifier
    
    
    GET {{server}}/odata/EquipmentInstances?$filter=Identifier eq 34 and ParentEquipment/OrganizationIdentifier eq 7&$select=Identifier,Name,ParentEquipmentIdentifier&$expand=ParentEquipment($select=Identifier,OrganizationIdentifier)
    
    
    GET {{server}}/odata/SupervisionScopes?$filter=Identifier eq 56 and OrganizationIdentifier eq 7&$select=Identifier,Name,OrganizationIdentifier
    
    

    Chaque requête doit retrouver exactement un objet. Si value est vide, arrêtez l’opération : ne retirez pas le filtre d’organisation pour trouver une cible de remplacement.

    5.4 Lire les relations

    GET {{server}}/odata/EquipmentInstances(34)/ParentEquipment
    GET {{server}}/odata/EquipmentInstances(34)/SupervisionScopes
    GET {{server}}/odata/SupervisionScopes(56)/EquipmentInstances
    
    

    Utilisez ces routes après avoir contrôlé l’appartenance de l’objet de départ. Elles permettent de retrouver la famille d’une instance et de consulter les objets associés. Une collection peut être vide.

    Pour conserver le filtre d’organisation sur les objets retournés par les associations :

    GET {{server}}/odata/SupervisionScopes(56)/EquipmentInstances?$filter=ParentEquipment/OrganizationIdentifier eq 7&$select=Identifier,Name,ParentEquipmentIdentifier
    
    
    GET {{server}}/odata/EquipmentInstances(34)/SupervisionScopes?$filter=OrganizationIdentifier eq 7&$select=Identifier,Name,OrganizationIdentifier
    
    

    5.5 Aller plus loin avec des requêtes OData complexes

    Les exemples suivants conservent le filtre d’organisation. Ils utilisent la famille 12 et les périmètres 56 et 57, à remplacer par les identifiants de votre environnement. Vérifiez au préalable que les périmètres utilisés appartiennent à l’organisation choisie. Dans ces requêtes, OrganizationIdentifier et SupervisionScopeIdentifier désignent deux types d’objets différents.

    5.5.1 Trouver les instances d’une famille présentes dans un périmètre

    Cette requête retourne les instances de la famille 12, dans l’organisation 7, qui possèdent au moins une association avec le périmètre 56 :

    GET {{server}}/odata/EquipmentInstances?$filter=ParentEquipment/OrganizationIdentifier eq 7 and ParentEquipmentIdentifier eq 12 and SupervisionScopeEquipmentInstances/any(s:s/SupervisionScopeIdentifier eq 56)&$select=Identifier,Name,ParentEquipmentIdentifier&$orderby=Identifier&$top=100
    
    

    SupervisionScopeEquipmentInstances est la collection des associations de chaque instance. any(...) vérifie qu’au moins une association satisfait le test. s est un nom local représentant une association pendant ce test ; s/SupervisionScopeIdentifier eq 56 vérifie son périmètre. Ce filtre sélectionne des instances et ne charge pas automatiquement leurs associations.

    5.5.2 Trouver les instances présentes dans l’un de deux périmètres

    Cette variante retourne les instances de l’organisation 7 associées au périmètre 56 ou au périmètre 57. Une instance appartenant aux deux n’est retournée qu’une fois :

    GET {{server}}/odata/EquipmentInstances?$filter=ParentEquipment/OrganizationIdentifier eq 7 and SupervisionScopeEquipmentInstances/any(s:s/SupervisionScopeIdentifier eq 56 or s/SupervisionScopeIdentifier eq 57)&$select=Identifier,Name&$orderby=Identifier&$top=100
    
    

    Pour exiger une présence dans les deux périmètres, utilisez deux tests distincts reliés par and :

    GET {{server}}/odata/EquipmentInstances?$filter=ParentEquipment/OrganizationIdentifier eq 7 and SupervisionScopeEquipmentInstances/any(s:s/SupervisionScopeIdentifier eq 56) and SupervisionScopeEquipmentInstances/any(s:s/SupervisionScopeIdentifier eq 57)&$select=Identifier,Name&$orderby=Identifier&$top=100
    
    

    Chaque test peut correspondre à une association différente. Écrire les deux égalités avec and à l’intérieur d’un seul any demanderait à une même association de porter simultanément deux identifiants de périmètre différents.

    5.5.3 Trouver les instances sans périmètre

    Cette requête recherche, dans l’organisation 7, les instances dont la collection d’associations est vide :

    GET {{server}}/odata/EquipmentInstances?$filter=ParentEquipment/OrganizationIdentifier eq 7 and not SupervisionScopeEquipmentInstances/any()&$select=Identifier,Name,ParentEquipmentIdentifier&$orderby=Identifier&$top=100
    
    

    any() sans condition teste l’existence d’au moins une association ; not inverse le résultat. Ce contrôle aide à repérer les instances restant à affecter à un périmètre. La syntaxe des tests sur les collections est détaillée dans les exemples d’opérateurs OData.

    5.5.4 Filtrer les instances et charger leur famille dans le même appel

    Cette requête sélectionne les instances actives de l’organisation 7 présentes dans le périmètre 56, retourne leur nom et leur identifiant, puis ajoute les informations de leur famille :

    GET {{server}}/odata/EquipmentInstances?$filter=ParentEquipment/OrganizationIdentifier eq 7 and IsEnabled eq true and SupervisionScopeEquipmentInstances/any(s:s/SupervisionScopeIdentifier eq 56)&$select=Identifier,Name,ParentEquipmentIdentifier&$expand=ParentEquipment($select=Identifier,Name,OrganizationIdentifier)&$orderby=Identifier&$top=100&$count=true
    
    

    Dans la réponse, chaque instance contient un objet ParentEquipment avec les trois propriétés demandées. IsEnabled eq true teste ici l’état d’activation de l’instance ; pour exiger aussi une famille active, ajoutez and ParentEquipment/IsEnabled eq true au filtre.

    $count=true ajoute @odata.count, le nombre total d’instances correspondant au filtre avant $top et $skip. Le tableau value contient au plus 100 instances pour cette page. Cette combinaison permet d’afficher une liste détaillée avec sa pagination.

    6. Créer les objets

    Après avoir retrouvé l’organisation, une création s’effectue avec POST sur la collection. Ne fournissez pas Identifier pour les trois objets principaux : l’identifiant est attribué par le serveur. Les corps ci-dessous montrent les propriétés utiles au scénario ; $metadata décrit le contrat de la version déployée.

    6.1 Créer une famille d’équipement

    POST {{server}}/odata/Equipments
    Authorization: Bearer {{token}}
    Content-Type: application/json
    Accept: application/json
    
    {
      "Name": "Capteur de température",
      "OrganizationIdentifier": 7,
      "IsEnabled": true
    }
    
    

    En cas de création réussie, la réponse est 201 Created. Conservez l’Identifier retourné : il sera nécessaire pour créer des instances de cette famille. Nous supposerons qu’il vaut 12. Le serveur peut renvoyer 409 Conflict s’il détecte un doublon de nom.

    6.2 Créer une instance

    Vérifiez d’abord que la famille 12 appartient à l’organisation 7 avec la requête de contrôle précédente.

    POST {{server}}/odata/EquipmentInstances
    Authorization: Bearer {{token}}
    Content-Type: application/json
    Accept: application/json
    
    {
      "Name": "CAPT-001",
      "ParentEquipmentIdentifier": 12,
      "Location": "Bâtiment A - Local technique",
      "InteroperabilityReference": "GTB-TEMP-001",
      "IsEnabled": true
    }
    
    

    ParentEquipmentIdentifier référence la famille Equipment et détermine ainsi l’organisation de l’instance. InteroperabilityReference est une référence facultative vers un système externe. Elle ne remplace pas l’identifiant OData. Conservez l’Identifier de la réponse, 34 dans la suite de l’exemple.

    6.3 Créer un périmètre de supervision

    POST {{server}}/odata/SupervisionScopes
    Authorization: Bearer {{token}}
    Content-Type: application/json
    Accept: application/json
    
    {
      "Name": "Bâtiment A",
      "OrganizationIdentifier": 7,
      "IsEnabled": true
    }
    
    

    Utilisez l’organisation effectivement retrouvée au début du traitement. Enregistrez l’Identifier de la réponse, 56 dans notre exemple, pour créer ensuite des associations. Un doublon de nom détecté par le serveur entraîne un conflit.

    7. Modifier les objets

    Utilisez PATCH sur la ressource identifiée pour ne changer que les propriétés indiquées. Les propriétés absentes du corps sont conservées. Au début du traitement, retrouvez l’organisation ; avant chaque écriture, vérifiez la cible avec son identifiant et le filtre d’appartenance présenté plus haut.

    PATCH {{server}}/odata/Equipments(12)
    Authorization: Bearer {{token}}
    Content-Type: application/json
    
    {
      "Name": "Capteur thermique"
    }
    
    

    Exemple de modification du nom d’une instance :

    PATCH {{server}}/odata/EquipmentInstances(34)
    Authorization: Bearer {{token}}
    Content-Type: application/json
    
    {
      "Name": "CAPT-001-EST"
    }
    
    

    Exemple de modification du périmètre :

    PATCH {{server}}/odata/SupervisionScopes(56)
    Authorization: Bearer {{token}}
    Content-Type: application/json
    
    {
      "Description": "Supervision du bâtiment A et de ses locaux techniques",
      "IsEnabled": true
    }
    
    

    Après chaque mise à jour, relisez la ressource avec son filtre d’organisation pour vérifier les valeurs enregistrées. Un nom vide est rejeté lors d’une modification et un doublon de nom détecté provoque un conflit.

    7.1 Hiérarchie et changement d’organisation

    ParentIdentifier définit un parent de même type : une autre instance pour une EquipmentInstance, un autre périmètre pour un SupervisionScope. Vérifiez aussi l’organisation du parent envisagé. Pour retirer ce rattachement facultatif, envoyez "ParentIdentifier": null. Les contrôles de hiérarchie refusent les modifications créant une référence circulaire.

    Changer ParentEquipmentIdentifier réaffecte une instance à une autre famille et peut changer son organisation effective. Changer OrganizationIdentifier sur une famille peut affecter toutes ses instances. Ces opérations demandent de recontrôler les objets et leurs associations ; elles ne sont pas nécessaires pour modifier un nom ou une description.

    L’API expose également PUT, qui suit une logique de remplacement. Pour les modifications ciblées de cet article, utilisez PATCH afin de ne pas remettre involontairement des propriétés omises à leur valeur par défaut.

    8. Associer une instance à un périmètre

    Retrouvez d’abord l’organisation et vérifiez les deux extrémités avec les requêtes de contrôle de l’instance 34 et du périmètre 56. Pour ce parcours, les deux doivent appartenir à l’organisation 7.

    La relation est une ressource à part entière. Elle ne comporte pas de champ d’organisation à fournir. Créez-la avec POST sur SupervisionScopeEquipmentInstances :

    POST {{server}}/odata/SupervisionScopeEquipmentInstances
    Authorization: Bearer {{token}}
    Content-Type: application/json
    Accept: application/json
    
    {
      "SupervisionScopeIdentifier": 56,
      "EquipmentInstanceIdentifier": 34
    }
    
    

    Les deux identifiants forment la clé de l’association. Il n’y a pas d’Identifier supplémentaire à récupérer. Le même lien ne peut pas être créé deux fois ; une seconde création renvoie 409 Conflict.

    Après vérification de ses deux extrémités, l’association peut être lue directement :

    GET {{server}}/odata/SupervisionScopeEquipmentInstances(SupervisionScopeIdentifier=56,EquipmentInstanceIdentifier=34)
    
    

    Pour supprimer uniquement le lien entre l’instance 34 et le périmètre 56, contrôlez à nouveau les deux objets dans l’organisation cible, puis appelez :

    DELETE {{server}}/odata/SupervisionScopeEquipmentInstances(SupervisionScopeIdentifier=56,EquipmentInstanceIdentifier=34)
    Authorization: Bearer {{token}}
    
    

    Une autre route de suppression est disponible depuis l’instance :

    DELETE {{server}}/odata/EquipmentInstances(34)/SupervisionScopes(56)
    Authorization: Bearer {{token}}
    
    

    Supprimer cette association ne supprime ni l’instance ni le périmètre. Pour changer le périmètre de rattachement, retirez le lien concerné puis créez une nouvelle association avec le périmètre préalablement vérifié.

    9. Supprimer un objet

    Retrouvez l’organisation, contrôlez l’appartenance de la cible et traitez ses dépendances avant d’utiliser DELETE. Pour nettoyer les objets créés dans l’exemple, retirez d’abord l’association, puis l’instance :

    DELETE {{server}}/odata/EquipmentInstances(34)
    Authorization: Bearer {{token}}
    
    

    La famille peut être supprimée après vérification qu’aucune autre instance ou dépendance ne la référence :

    DELETE {{server}}/odata/Equipments(12)
    Authorization: Bearer {{token}}
    
    

    Le périmètre peut être supprimé après traitement de ses autres associations, de ses éventuels enfants et de ses autres dépendances :

    DELETE {{server}}/odata/SupervisionScopes(56)
    Authorization: Bearer {{token}}
    
    

    10. Réponses et erreurs à traiter

    Réponse Interprétation courante
    200 OK Lecture ou mise à jour réussie, avec représentation de la ressource selon l’opération.
    201 Created Ressource créée ; lire l’identifiant dans la représentation retournée ou l’en-tête Location.
    204 No Content Opération réussie sans corps ; retour attendu des suppressions. Une mise à jour peut aussi ne pas renvoyer de représentation.
    value: [] Aucun objet visible ne correspond au filtre. Arrêter l’écriture qui dépend de cette recherche.
    400 Bad Request Corps invalide, référence d’organisation inexistante lors de la création d’un périmètre, nom vide ou hiérarchie circulaire.
    401 Unauthorized / 403 Forbidden Authentification absente/invalide ou autorisation insuffisante. Une organisation ou une dépendance inaccessible peut aussi conduire à un refus.
    404 Not Found Ressource ou association demandée introuvable.
    409 Conflict Nom déjà utilisé ou association déjà présente.

    Les réponses exactes peuvent varier selon le type d’opération et la version de l’API. Le client doit vérifier le statut HTTP, le nombre de résultats et les valeurs retournées, puis conserver le corps d’erreur pour afficher ou journaliser le détail renvoyé par le serveur. Les droits de lecture et d’écriture peuvent différer : lire un objet ne garantit pas le droit de le modifier.

    11. Parcours complet résumé

    1. S’authentifier et retrouver précisément l’Organization cible.
    2. Conserver son identifiant pour les opérations du traitement.
    3. Lire ou créer une famille Equipment dans cette organisation.
    4. Lire ou créer une EquipmentInstance avec l’identifiant de cette famille.
    5. Lire ou créer un SupervisionScope dans la même organisation.
    6. Contrôler les deux extrémités, puis créer leur association.
    7. Avant toute modification ou suppression, vérifier l’appartenance des cibles à l’organisation.
    8. Relire les données après les écritures ; supprimer séparément les associations et les objets selon le besoin.

    L’organisation définit le périmètre de travail ; les identifiants désignent les ressources utilisées pendant le traitement. Conservez ces deux informations ensemble pour éviter de mélanger les données de plusieurs organisations.