Oggetti IoT CRUD con API OData
- Tipo non definito
In questo articolo
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.
Gli esempi utilizzano i nomi delle proprietà OData come esposti dall'API (PascalCase). Sostituire {{server}} tramite l'indirizzo HTTPS del server senza una barra finale, {{token}} con un token di accesso valido e le credenziali di esempio con quelle effettivamente ottenute. Le query sono espressive: non riutilizzare credenziali da un altro ambiente.
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.
EquipmentInstance non possiede alcuna proprietà OrganizationIdentifier da informare. La sua organizzazione si trova da ParentEquipment.OrganizationIdentifier. Possibile suono ParentIdentifier Si riferisce a un'altra istanza in una gerarchia. Non sostituisce ParentEquipmentIdentifier.
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
DistinguishedNamePrevedibile. 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
L'intestazione dell'organizzazione non è né un permesso aggiuntivo né un sostituto dei filtri OData e delle proprietà JSON. Per l'attraversamento delle chiavi API, mantenere entrambe le intestazioni chiave e selezionare esplicitamente l'organizzazione nei filtri e nei corpi delle richieste.
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.
Questo controllo ti impedisce di mirare erroneamente a un oggetto in un'altra organizzazione accessibile dallo stesso account. I permessi sono comunque controllati dal server. Pre-reading e write sono due richieste separate; non sono transazioni atomiche.
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.
Una risposta a un creativo porta con sé l'asset creato, a differenza di una raccolta letta avvolta in value. Recupera gli ID dalle risposte effettive. Una ricerca precedente non garantisce che un'altra applicazione non crei un oggetto concorrente prima del tuo POST.
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}}
Non dare per scontato una cancellazione a cascata. I vincoli sui dati possono impedire la cancellazione, come controllare istanze in una famiglia, associazioni in un'istanza e gerarchie. Gestisci l'errore prima di riprovare. Non cancellare una famiglia o un ambito preesistente solo per ripulire la tua prova.
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
- Autenticati e trova il
Organizationbersaglio. - Per mantenere il tuo nome utente per le operazioni di elaborazione.
- Leggi o crea una famiglia
Equipmentin questa organizzazione. - Leggi o crea un
EquipmentInstancecon l'identificativo di questa famiglia. - Leggi o crea un
SupervisionScopenella stessa organizzazione. - Controlla entrambe le estremità, poi crea la loro associazione.
- Prima di qualsiasi modifica o cancellazione, verifica che i bersagli siano membri dell'organizzazione.
- 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.