CRUD des objets IoT avec l’API OData
- Type non défini
Dans cet article
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.
Les exemples utilisent les noms de propriétés OData tels qu’ils sont exposés par l’API (PascalCase). Remplacez {{server}} par l’adresse HTTPS du serveur sans barre oblique finale, {{token}} par un jeton d’accès valide, et les identifiants d’exemple par ceux réellement obtenus. Les requêtes sont illustratives : ne réutilisez pas les identifiants d’un autre environnement.
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.
EquipmentInstance ne possède pas de propriété OrganizationIdentifier à renseigner. Son organisation se retrouve par ParentEquipment.OrganizationIdentifier. Son éventuel ParentIdentifier désigne une autre instance dans une hiérarchie ; il ne remplace pas ParentEquipmentIdentifier.
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.
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
- Tutoriel OData de prise en main : lectures, relations et opérations CRUD avec des requêtes HTTP.
- Exemples d’utilisation des options OData : filtres, opérateurs et recherches dans une collection avec
anyetall. - Tutoriel OData avancé : notions complémentaires, dont les types dérivés et les requêtes groupées.
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é.
OrganizationsInScope est une WebAPI, pas une route OData. Elle renvoie directement un tableau JSON d’organisations, sans enveloppe value. Ne lui ajoutez pas les options OData présentées plus haut. C’est une alternative utile pour proposer un choix lorsque le compte possède plusieurs organisations dans son périmètre ; elle n’est pas un préalable obligatoire au parcours OData.
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
DistinguishedNameattendu. 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
L’en-tête d’organisation n’est ni une autorisation supplémentaire ni un remplacement des filtres OData et des propriétés JSON. Pour le parcours par clé API, conservez les deux en-têtes de clé et sélectionnez explicitement l’organisation dans les filtres et les corps de requête.
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.
Ce contrôle évite de cibler par erreur un objet d’une autre organisation accessible au même compte. Les autorisations restent vérifiées par le serveur. La lecture préalable et l’écriture sont deux requêtes distinctes ; elles ne constituent pas une transaction atomique.
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.
Une réponse à une création porte la ressource créée, contrairement à une lecture de collection enveloppée dans value. Récupérez les identifiants dans les réponses réelles. Une recherche préalable ne garantit pas qu’une autre application ne créera pas un objet concurrent avant votre POST.
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}}
Ne supposez pas une suppression en cascade. Des contraintes de données peuvent empêcher la suppression : vérifiez notamment les instances d’une famille, les associations d’une instance et les hiérarchies. Traitez l’erreur avant de réessayer. Ne supprimez pas une famille ou un périmètre préexistant simplement pour nettoyer votre essai.
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é
- S’authentifier et retrouver précisément l’
Organizationcible. - Conserver son identifiant pour les opérations du traitement.
- Lire ou créer une famille
Equipmentdans cette organisation. - Lire ou créer une
EquipmentInstanceavec l’identifiant de cette famille. - Lire ou créer un
SupervisionScopedans la même organisation. - Contrôler les deux extrémités, puis créer leur association.
- Avant toute modification ou suppression, vérifier l’appartenance des cibles à l’organisation.
- 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.