Oggetti IoT CRUD con API OData

In questo articolo

    Mostra altro
    Mostra meno

    1. Introduzione

    Questo articolo mostra come leggere, creare, modificare ed eliminare oggetti IoT esposti da Immersive RestFrontage: Equipment, EquipmentInstance e SupervisionScope. Queste quattro operazioni costituiscono il CRUD. Descrive anche la gestione della loro associazione, rappresentata da SupervisionScopeEquipmentInstance.

    Il viaggio inizia sempre con la ricerca delOrganization preoccupato. Il suo identificatore permette quindi di selezionare le risorse giuste e di verificarne la proprietà prima di ogni voce. Prenderemo l'esempio di un sensore di temperatura collegato a un edificio.

    2. Comprendere gli oggetti

    Scopo Ruolo Relazione principale
    Organization Organizzazione che possiede i dati. Audio Identifier definisce l'ambito dell'elaborazione.
    Equipment Famiglia di apparecchiature IoT. Indossa OrganizationIdentifier e può avere più istanze.
    EquipmentInstance Attrezzature reali installate o tracciate. Appartiene a una famiglia tramite ParentEquipmentIdentifier. La sua organizzazione è quella di questa famiglia.
    SupervisionScope Ambito di supervisione, collegato a un'organizzazione. Un perimetro può contenere più istanze, e un'istanza può essere associata a più ambitivi.
    SupervisionScopeEquipmentInstance Associazione tra un perimetro e un'ista. La sua chiave è composta da SupervisionScopeIdentifier e EquipmentInstanceIdentifier.

    Equipment descrive il modello dell'apparecchiatura, mentre EquipmentInstance designa un oggetto concreto. Per collegare un'istanza a un perimetro, si crea l'associazione; la creazione del perimetro o dell'istanza non crea automaticamente questo collegamento.

    Un oggetto Equipment sarà ad esempio Ascensore, Sensore di temperatura, Porta automatica, Veicolo di emergenza, ...

    Un oggetto EquipmentInstance sarà ad esempio Ascensore ATR5910, Hall del sensore di temperatura di livello 0, Porta automatica del dock, Veicolo di emergenza X312A, ... Attraverso la relazione ParentIdentifier Possiamo collegare una genitorialità tra istanze di apparecchiature. Ad esempio, un armadio elettrico potrebbe avere interruttori automatici, automi, ecc. da bambino. Un oggetto EquipmentInstance ha necessariamente una proprietà ParentEquipmentIdentifier Puntando a un Equipment esistente.

    Un oggetto SupervisionScope sarà ad esempio Equipaggiamento IOT Livello 4, Edificio amministrativo, Stazione di Raincourt, ...

    SupervisionScopeEquipmentInstance ha necessariamente le proprietà SupervisionScopeIdentifier e EquipmentInstanceIdentifier puntando verso oggetti esistenti.

    Il diagramma seguente definisce la relazione tra i diversi oggetti:

    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. Preparazione alle chiamate

    3.1 Autenticazione

    Gli esempi usano un gettone Bearer. Passa l'intestazione Authorization su ogni richiesta, incluso quando le letture di esempio, mostrano solo l'URL.

    Per l'integrazione autenticata con chiave API, sostituisci questa intestazione con le seguenti due intestazioni, per ogni chiamata:

    x-app-name: {{appName}}
    x-api-key: {{apiKey}}
    
    

    L'accesso diretto alla chiave API non richiede un login o conversione preventiva in un token portatore lato client. L'account associato alla chiave rimane soggetto a permessi di accesso organizzativo e business. Mantieni la chiave nella configurazione sicura dell'applicazione chiamante; non inserirla in JavaScript distribuito al browser.

    3.2 Modello e formato della query

    L'API OData è esposta sotto /odata. Dai un'occhiata al loro modello prima di integrare un cliente per controllare tutte le proprietà e i loro tipi:

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

    Le scritture usano JSON. Il token deve essere associato a un account autorizzato a leggere o modificare i dati richiesti.

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

    Negli URL di questo articolo, gli spazi filtro sono lasciati leggibili. Il client HTTP deve codificare i parametri della richiesta. In una stringa OData, un apostrofo è raddoppiato: Name eq 'L''Atelier'.

    4. Trovare l'organizzazione prima di qualsiasi operazione IoT

    4.1 Trova l'organizzazione target

    Inizia cercando l'organizzazione accessibile all'account che stai usando, senza assumerne l'identificativo:

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

    Estratto illustrativo della risposta, senza annotazioni di OData:

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

    I risultati di una raccolta letta si trovano nella tabella value. Affronta esplicitamente queste tre situazioni:

    • Nessun risultato : Interrompere l'elaborazione. L'organizzazione potrebbe essere assente o inaccessibile all'account utilizzato.
    • Un risultato : verifica che corrisponda all'organizzazione prevista, poi mantiene il suo Identifier.
    • Risultati multipli : specificare la selezione, ad esempio usando il DistinguishedName Prevedibile. Non scegliere arbitrariamente il primo risultato.

    Il limite $top=2 è sufficiente a rilevare ambiguità. Non viene utilizzata per scegliere un'organizzazione.

    Se una credenziale è già fornita dalla configurazione di integrazione, verifica la sua esistenza, accessibilità e identità:

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

    Nel sequel, 7 rappresenta l'identificatore effettivamente trovato. Gli ID 12, 34 e 56 rappresenteranno rispettivamente una famiglia, un'istanza e un ambito, trovati o creati durante l'elaborazione.

    4.2 Mantenere un ambito coerente

    Risorsa Filtro Membri dell'Organizzazione 7 Attaccamento alla creazione
    Equipment OrganizationIdentifier eq 7 "OrganizationIdentifier": 7
    EquipmentInstance ParentEquipment/OrganizationIdentifier eq 7 ParentEquipmentIdentifier deve designare una famiglia dell'organizzazione 7.
    SupervisionScope OrganizationIdentifier eq 7 "OrganizationIdentifier": 7
    Associazione Controlla l'istanza e l'ambito. Usa entrambe le credenziali controllate.

    Esegui questa risoluzione all'inizio di ogni run aziendale, poi riutilizza l'ID confermato per le operazioni che compongono quell'azienda. Ripeti se il server target, l'account o l'organizzazione cambiano.

    Per le chiamate Bearer, puoi anche dichiarare il contesto dell'organizzazione con questa intestazione opzionale, una volta trovata l'organizzazione:

    X-Organization-Identifier: 7
    
    

    5. Leggi gli oggetti dell'organizzazione

    5.1 Elenco e filtro

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

    Per limitare la lettura a 12 istanze familiari, mantieni anche il filtro organizzativo:

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

    Il filtro traccia una relazione con /. Non è necessario aggiungere $expand per filtrare in base a una proprietà madre.

    Sono disponibili opzioni OData per selezionare, espandere, filtrare, ordinare e paginare. $top è limitato a 200; ciò non significa che tutte le collezioni siano automaticamente paginate in blocchi da 200. Per la seconda pagina di 100 elementi, usa ad esempio $orderby=Identifier&$top=100&$skip=100. Se la risposta fornisce @odata.nextLink, segui questo link.

    5.2 Trova un oggetto aziendale

    Cerca una famiglia per nome all'interno dell'organizzazione:

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

    Ad esempio, puoi cercare il suo nome o un riferimento esterno:

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

    Richiedi un risultato unico prima di riutilizzare il suo identificatore. Non presumere che un riferimento esterno sia unico senza aver verificato i risultati. Se non ci sono risultati, crea un nuovo oggetto solo se quella creazione fa parte dell'elaborazione attesa.

    5.3 Controlla un target prima di modificare o cancellare

    Per un target con un ID noto, combina quell'ID con il filtro organizzativo:

    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
    
    

    Ogni query deve trovare esattamente un oggetto. Se value è vuoto, ferma l'operazione: Non rimuovere il filtro dell'organizzazione per trovare un obiettivo alternativo.

    5.4 Leggi le relazioni

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

    Usa queste route dopo aver verificato la membership dell'oggetto iniziale. Ti permettono di trovare la famiglia di un'istanza e di consultare gli oggetti associati. Una collezione può essere vuota.

    Per mantenere il filtro organizzativo sugli oggetti restituiti dalle associazioni:

    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
    
    

    6. Crea gli oggetti

    Dopo aver avuto Riscoperta dell'organizzazione, una creazione viene fatta con POST sulla collezione. Non fornire Identifier Per i tre oggetti principali: l'identificatore viene assegnato dal server. I corpi sottostanti mostrano le proprietà utili allo scenario; $metadata Descrive il contratto per la versione distribuita.

    6.1 Crea una famiglia di attrezzature

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

    In caso di creazione riuscita, la risposta è 201 Created. Tieni ilIdentifier returned: Sarà necessario per creare istanze di questa famiglia. Assumeremo che sia 12. Il server può restituire 409 Conflict Se rileva un nome duplicato.

    6.2 Crea un'istanza

    Per prima cosa, verifica che la famiglia 12 appartenga all'Organizzazione 7 con la precedente query di controllo.

    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 Riferimento alla famiglia Equipment e quindi determina l'organizzazione del corpo. InteroperabilityReference è un riferimento opzionale a un sistema esterno. Non sostituisce l'identificatore OData. Mantieni ilIdentifier della risposta, 34 nella continuazione dell'esempio.

    6.3 Creare un perimetro di monitoraggio

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

    Usa l'organizzazione che è stata effettivamente trovata all'inizio del trattamento. Salva ilIdentifier della risposta, 56 nel nostro esempio, e poi creare associazioni. Un nome duplicato rilevato dal server provoca un conflitto.

    7. Modifica oggetti

    Utilizzo PATCH sulla risorsa identificata per modificare solo le proprietà indicate. Le proprietà non presenti nel corpo vengono preservate. All'inizio dell'elaborazione, trova l'organizzazione; prima di ogni scrittura, verifica il target con il suo identificatore e il filtro di appartenenza presentato sopra.

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

    Esempio di cambio del nome di un'istanza:

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

    Esempio di cambiamento nell'ambito:

    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
    }
    
    

    Dopo ogni aggiornamento, riproduci la risorsa con il filtro organizzativo per controllare i valori salvati. Un nome vuoto viene rifiutato quando viene apportata una modifica e un nome duplicato rilevato causa un conflitto.

    7.1 Gerarchia e cambiamento organizzativo

    ParentIdentifier definisce un genitore dello stesso tipo: un'altra istanza per un EquipmentInstance, un altro perimetro per un SupervisionScope. Controlla anche l'organizzazione del genitore previsto. Per rimuovere questo allegato opzionale, invia "ParentIdentifier": null. I controlli della gerarchia rifiutano le modifiche che creano un riferimento circolare.

    Cambiamento ParentEquipmentIdentifier Riassegna un'istanza a un'altra famiglia e può cambiare la sua organizzazione efficace. Modifica OrganizationIdentifier su una famiglia può influenzare tutte le sue istanze. Queste operazioni richiedono di ricontrollare oggetti e le loro associazioni; non sono obbligate a cambiare nome o descrizione.

    L'API esposta anche PUT, che segue una logica di sovrascrittura. Per modifiche mirate a questo articolo, usa PATCH così da non resettare involontariamente le proprietà omesse ai valori predefiniti.

    8. Associa un'istanza a un perimetro

    Prima trova l'organizzazione e controlla entrambe le estremità con le query di controllo per esempio 34 e perimetro 56. Per questo viaggio, entrambe devono appartenere all'organizzazione 7.

    La relazione è una risorsa a sé stante. Non ha un campo organizzativo da fornire. Creala con POST su SupervisionScopeEquipmentInstances :

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

    I due identificatori costituiscono la chiave dell'associazione. Non esisteIdentifier per recuperare. Lo stesso legame non può essere creato due volte; una seconda creazione ritorna 409 Conflict.

    Dopo aver controllato entrambe le estremità, l'associazione può essere letta direttamente:

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

    Per rimuovere solo il collegamento tra l'istanza 34 e il perimetro 56, ricontrollare entrambi gli oggetti nell'organizzazione di destinazione, e poi chiamare:

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

    È disponibile una rotta alternativa di cancellazione dall'istanza:

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

    Rimuovere questa associazione non elimina l'istanza o l'ambito. Per modificare l'ambito dell'allegato, rimuovere il collegamento e poi creare una nuova associazione con l'ambito precedentemente verificato.

    9. Elimina un oggetto

    Trova l'organizzazione, verifica l'appartenenza del target e affronta le sue dipendenze prima di usarlo DELETE. Per pulire gli oggetti creati nell'esempio, prima rimuovi l'associazione, poi rimuovi l'istanza:

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

    La famiglia può essere eliminata dopo aver verificato che nessun'altra istanza o dipendenza la faccia referenza:

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

    Il perimetro può essere eliminato dopo aver trattato le sue altre consegne, i suoi possibili figli e le sue altre dipendenze:

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

    10. Risposte ed errori da correggere

    Risposta Interpretazione comune
    200 OK Leggi o aggiorna con successo, con rappresentazione della risorsa per operazione.
    201 Created Risorsa creata; leggere l'identificatore nella rappresentazione o intestazione restituita Location.
    204 No Content Funzionamento riuscito senza corpo; cancellazioni attese che ritornino. Un aggiornamento potrebbe anche non restituire una rappresentazione.
    value: [] Non ci sono oggetti visibili che corrispondano al filtro. Smetti di scrivere, dipende da questa ricerca.
    400 Bad Request Corpo invalido, riferimento all'organizzazione che non esiste quando si crea un ambito, nome vuoto o gerarchia circolare.
    401 Unauthorized / 403 Forbidden Autenticazione assente/invalida o autorizzazione insufficiente. Un'organizzazione o una dipendenza irraggiungibile possono anche portare a un rifiuto.
    404 Not Found Risorsa o associazione richiesta non trovata.
    409 Conflict Nome già usato o associazione già presente.

    Le risposte esatte possono variare a seconda del tipo di operazione e della versione dell'API. Il client deve verificare lo stato HTTP, il numero di risultati e i valori restituiti, e poi conservare il corpo dell'errore per visualizzare o registrare i dettagli restituiti dal server. I permessi di lettura e scrittura possono differire: leggere un oggetto non garantisce il diritto di modificarlo.

    11. Riepilogo completo della carriera

    1. Autenticati e trova ilOrganization bersaglio.
    2. Per mantenere il tuo nome utente per le operazioni di elaborazione.
    3. Leggi o crea una famiglia Equipment in questa organizzazione.
    4. Leggi o crea un EquipmentInstance con l'identificativo di questa famiglia.
    5. Leggi o crea un SupervisionScope nella stessa organizzazione.
    6. Controlla entrambe le estremità, poi crea la loro associazione.
    7. Prima di qualsiasi modifica o cancellazione, verifica che i bersagli siano membri dell'organizzazione.
    8. Riprodurti i dati dopo le scritture; cancella le associazioni e gli oggetti separatamente se necessario.

    L'organizzazione definisce l'ambito del lavoro; gli identificatori indicano le risorse utilizzate durante l'elaborazione. Mantenere insieme queste due informazioni per evitare di mescolare dati provenienti da più organizzazioni.