CRUD IoT-Objekte mit OData API

In diesem Artikel

    Mehr anzeigen
    Weniger anzeigen

    1. Einleitung

    Dieser Artikel zeigt, wie man IoT-Objekte, die von Immersive RestFrontage freigelegt wurden, liest, erstellt, bearbeitet und löscht: Equipment, EquipmentInstance und SupervisionScope. Diese vier Betriebe bilden die CRUD. Er beschreibt auch die Leitung ihrer Vereinigung, vertreten durch SupervisionScopeEquipmentInstance.

    Die Reise beginnt immer mit der Suche nach demOrganization besorgt. Sein Kenner ermöglicht es dann, die richtigen Ressourcen auszuwählen und deren Eigentum vor jedem Eintrag zu überprüfen. Wir nehmen das Beispiel eines Temperatursensors, der an einem Gebäude befestigt ist.

    2. Objekte verstehen

    Zweck Rolle Hauptbeziehung
    Organization Organisation, die die Daten besitzt. Klang Identifier definiert den Umfang der Verarbeitung.
    Equipment IoT-Gerätefamilie. Sie trägt OrganizationIdentifier und es kann mehrere Instanzen geben.
    EquipmentInstance Tatsächliche Ausrüstung installiert oder verfolgt. Es gehört einer Familie über ParentEquipmentIdentifier. Ihre Organisation ist die dieser Familie.
    SupervisionScope Umfang der Aufsicht, angegliedert an eine Organisation. Ein Perimeter kann mehrere Instanzen enthalten, und eine Instanz kann mit mehreren Scopes verknüpft sein.
    SupervisionScopeEquipmentInstance Verbindung zwischen einem Perimeter und einer Instanz. Ihr Schlüssel besteht aus SupervisionScopeIdentifier und EquipmentInstanceIdentifier.

    Equipment beschreibt das Modell der Ausrüstung, während EquipmentInstance bezeichnet ein konkretes Objekt. Um eine Instanz an einen Perimeter anzuhängen, wird die Assoziation erstellt; die Erstellung des Perimeters oder der Instanz erzeugt diese Verbindung nicht automatisch.

    Ein Objekt Equipment zum Beispiel wird es sein Aufzug, Temperatursensor, Automatische Tür, Einsatzfahrzeug, ...

    Ein Objekt EquipmentInstance zum Beispiel wird es sein Aufzug ATR5910, Sensorhalle der Stufe 0, Automatische Docktür, X312A-Einsatzfahrzeug, ... Über die Beziehung ParentIdentifier Wir können eine Elternschaft zwischen Geräteinstanzen verknüpfen. Zum Beispiel könnte ein elektrischer Schrank als Kind Leistungsschalter, Automaten usw. haben. Ein Objekt EquipmentInstance hat notwendigerweise eine Eigenschaft ParentEquipmentIdentifier Zeigen auf ein Equipment existieren.

    Ein Objekt SupervisionScope zum Beispiel wird es sein IOT-Level-4-Ausrüstung, Verwaltungsgebäude, Bahnhof Raincourt, ...

    SupervisionScopeEquipmentInstance besitzt notwendigerweise die Eigenschaften SupervisionScopeIdentifier und EquipmentInstanceIdentifier und zeigt auf bestehende Objekte.

    Das folgende Diagramm definiert die Beziehung zwischen den verschiedenen Objekten:

    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. Vorbereitung auf Einsätze

    3.1 Authentifizierung

    Die Beispiele verwenden einen Inhaber-Token. Weitergeben Sie den Kopf Authorization bei jeder Anfrage, einschließlich wenn die Beispiellesungen nur die URL anzeigen.

    Für API-Schlüssel-authentifizierte Integration ersetzen Sie diesen Header bei jedem Aufruf durch die folgenden zwei Header:

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

    Der direkte API-Schlüsselzugriff erfordert keine vorherige Anmeldung oder Umwandlung in ein clientseitiges Bearer-Token. Das mit dem Schlüssel verknüpfte Konto bleibt den Organisationszugriffs- und Geschäftsrechten unterworfen. Bewahren Sie den Schlüssel in der sicheren Konfiguration der aufrufenden Anwendung auf; fügen Sie ihn nicht in JavaScript ein, das im Browser verteilt wird.

    3.2 Abfragevorlage und Format

    Die OData-API wird unter /odata. Schauen Sie sich vor der Einarbeitung eines Kunden ihre Vorlage an, um alle Immobilien und deren Typen zu überprüfen:

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

    Schreibvorgänge verwenden JSON. Das Token muss mit einem Konto verknüpft sein, das autorisiert ist, die angeforderten Daten zu lesen oder zu ändern.

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

    In den URLs in diesem Artikel bleiben Filterräume lesbar. Der HTTP-Client muss die Anfrageparameter kodieren. In einer OData-Zeichenkette wird ein Apostroph verdoppelt: Name eq 'L''Atelier'.

    4. Die Organisation vor jeder IoT-Operation zu finden

    4.1 Finde die Zielorganisation

    Beginnen Sie damit, nach der Organisation zu suchen, die für das von Ihnen genutzte Konto zugänglich ist, ohne deren Kennung anzunehmen:

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

    Illustrativer Auszug der Antwort, ohne OData-Anmerkungen:

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

    Die Ergebnisse eines Sammlungslesens sind in der Tabelle zu finden value. Gehen Sie explizit auf diese drei Situationen ein:

    • Keine Ergebnisse : Bearbeitung stoppen. Die Organisation könnte für das verwendete Konto abwesend oder unzugänglich sein.
    • Ein Ergebnis : Überprüfen, ob es mit der erwarteten Organisation übereinstimmt, und behalten Sie dann seine Identifier.
    • Mehrfache Ergebnisse : spezifiziere die Auswahl, zum Beispiel mit dem DistinguishedName erwartet. Wählen Sie nicht willkürlich das erste Ergebnis.

    Die Grenze $top=2 ist ausreichend, um Mehrdeutigkeit zu erkennen. Sie wird nicht verwendet, um eine Organisation auszuwählen.

    Wenn eine Zugangsberechtigung bereits von Ihrer Integrationskonfiguration bereitgestellt wird, überprüfen Sie deren Existenz, Zugänglichkeit und Identität:

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

    In der Fortsetzung, 7 steht für die tatsächlich gefundene Kennung. IDs 12, 34 und 56 repräsentieren jeweils eine Familie, Instanz und Scope, die während der Verarbeitung gefunden oder erstellt wurden.

    4.2 Aufrechterhaltung eines einheitlichen Umfangs

    Ressource Organisationsmitgliedschaftsfilter 7 Bindung an die Schöpfung
    Equipment OrganizationIdentifier eq 7 "OrganizationIdentifier": 7
    EquipmentInstance ParentEquipment/OrganizationIdentifier eq 7 ParentEquipmentIdentifier Muss eine Familie der Organisation benennen 7.
    SupervisionScope OrganizationIdentifier eq 7 "OrganizationIdentifier": 7
    Vereinigung Überprüfe die Instanz und den Umfang. Verwenden Sie beide kontrollierten Zugangsdaten.

    Führen Sie diese Auflösung zu Beginn jedes Geschäftslaufs durch und verwenden Sie dann die bestätigte ID für die Operationen, die dieses Geschäft ausmachen, wieder. Wiederholen Sie das, wenn sich der Zielserver, das Zielkonto oder die Organisation ändert.

    Für Bearer-Aufrufe kann man den Organisationskontext auch mit diesem optionalen Header deklarieren, sobald die Organisation gefunden ist:

    X-Organization-Identifier: 7
    
    

    5. Organisationsobjekte lesen

    5.1 Liste und Filter

    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
    
    

    Um das Lesen auf Familie 12 Instanzen zu beschränken, behalte auch den Organisationsfilter bei:

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

    Der Filter verfolgt eine Beziehung mit /. Es ist nicht notwendig, hinzuzufügen $expand um auf eine übergeordnete Eigenschaft zu filtern.

    OData-Optionen zum Auswählen, Erweitern, Filtern, Sortieren und Paginieren sind verfügbar. $top ist auf 200 begrenzt; das bedeutet nicht, dass alle Sammlungen automatisch in 200-Blöcken paginiert werden. Für die zweite Seite mit 100 Einträgen verwenden Sie zum Beispiel $orderby=Identifier&$top=100&$skip=100. Wenn die Antwort vorsieht @odata.nextLink, folgen Sie diesem Link.

    5.2 Finde ein Geschäftsobjekt

    Suchen Sie innerhalb der Organisation nach einer Familie nach Namen:

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

    Zum Beispiel können Sie nach seinem Namen oder einer externen Referenz suchen:

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

    Verlangen Sie ein eindeutiges Ergebnis, bevor Sie seine Identifikatorin wiederverwenden. Gehen Sie nicht davon aus, dass eine externe Referenz eindeutig ist, ohne die Ergebnisse zu überprüfen. Wenn keine Ergebnisse vorhanden sind, erstellen Sie ein neues Objekt nur, wenn diese Erstellung Teil der erwarteten Verarbeitung ist.

    5.3 Überprüfen Sie ein Ziel, bevor Sie bearbeiten oder löschen

    Für ein Ziel mit bekannter ID kombinieren Sie diese ID mit dem Organisationsfilter:

    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
    
    

    Jede Abfrage muss genau ein Objekt finden. Wenn value ist leer, stoppen Sie die Operation: Entfernen Sie nicht den Organisationsfilter, um ein alternatives Ziel zu finden.

    5.4 Lies die Beziehungen

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

    Nutzen Sie diese Routen, nachdem Sie die Mitgliedschaft des Startobjekts überprüft haben. Sie ermöglichen es Ihnen, die Familie einer Instanz zu finden und die zugehörigen Objekte zu konsultieren. Eine Sammlung kann leer sein.

    Um den Organisationsfilter bei von Assoziationen zurückgegebenen Objekten beizubehalten:

    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. Erstelle die Objekte

    Nachdem er gewesen ist Die Organisation wiederentdeckt, wird eine Schöpfung mit durchgeführt POST auf der Sammlung. Nicht bereitstellen Identifier Für die drei Hauptobjekte: Die Identifikatorin wird vom Server zugewiesen. Die untenstehenden Körper zeigen die für das Szenario nützlichen Eigenschaften; $metadata Beschreibt den Vertrag für die bereitgestellte Version.

    6.1 Eine Gerätefamilie erstellen

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

    Im Falle erfolgreicher Erschaffung lautet die Antwort 201 Created. Behalte dieIdentifier returned: Es wird notwendig sein, Instanzen dieser Familie zu erstellen. Wir nehmen an, dass es 12 sind. Der Server kann zurückgeben 409 Conflict wenn es einen doppelten Namen erkennt.

    6.2 Erstellen Sie eine Instanz

    Überprüfen Sie zunächst, dass Familie 12 zu Organisation 7 mit der vorherigen Steueranfrage gehört.

    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 Beziehen Sie sich auf die Familie Equipment und so die Organisation des Körpers bestimmt. InteroperabilityReference ist eine optionale Referenz auf ein externes System. Sie ersetzt nicht die OData-Kennung. Behalten Sie dieIdentifier von der Antwort 34 in der Fortsetzung des Beispiels.

    6.3 Erstelle einen Überwachungsperimeter

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

    Verwenden Sie die Organisation, die zu Beginn der Behandlung gefunden wurde. Speichern Sie dasIdentifier der Antwort 56 in unserem Beispiel und dann Assoziationen erstellen. Ein vom Server erkannter doppelter Name führt zu einem Konflikt.

    7. Objekte bearbeiten

    Verwendung PATCH auf der identifizierten Ressource, nur die angegebenen Eigenschaften zu ändern. Eigenschaften, die im Körper nicht vorhanden sind, bleiben erhalten. Zu Beginn der Verarbeitung finden Sie die Organisation; vor jedem Schreiben überprüfen Sie das Ziel mit seiner Identifikatorin und dem oben dargestellten Mitgliedschaftsfilter.

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

    Beispiel für die Änderung des Namens einer Instanz:

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

    Beispiel für eine Änderung des Umfangs:

    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
    }
    
    

    Nach jedem Update wird die Ressource mit ihrem Organisationsfilter erneut abgespielt, um die gespeicherten Werte zu überprüfen. Ein leerer Name wird bei einer Änderung abgelehnt, und ein doppelter Name verursacht einen Konflikt.

    7.1 Hierarchie und organisatorischer Wandel

    ParentIdentifier definiert einen Eltern desselben Typs: eine weitere Instanz für eine EquipmentInstance, ein weiterer Umfang für eine SupervisionScope. Überprüfen Sie auch die Organisation des vorgesehenen Elternteils. Um diesen optionalen Anhang zu entfernen, senden Sie "ParentIdentifier": null. Hierarchiekontrollen lehnen Änderungen ab, die eine zirkuläre Referenz erzeugen.

    Veränderung ParentEquipmentIdentifier Es wird eine Instanz einer anderen Familie zugewiesen und kann deren effektive Organisation geändert werden. Änderung OrganizationIdentifier auf einer Familie alle ihre Instanzen beeinflussen kann. Diese Operationen erfordern eine erneute Überprüfung von Objekten und deren Assoziationen; sie müssen keinen Namen oder eine Beschreibung ändern.

    Die API stellt außerdem offen PUT, die einer Override-Logik folgt. Für gezielte Änderungen an diesem Artikel verwenden Sie PATCH damit du nicht unbeabsichtigt weggelassene Eigenschaften auf ihre Standardwerte zurücksetzt.

    8. Verknüpfe eine Instanz mit einem Perimeter

    Zuerst finden Sie die Organisation und überprüfen Sie beide Enden mit den Kontrollabfragen, zum Beispiel 34 und Perimeter 56. Für diese Reise müssen beide zu Organisation 7 gehören.

    Die Beziehung ist eine eigenständige Ressource. Sie hat kein organisatorisches Feld zu bieten. Schaffen Sie sie mit POST auf SupervisionScopeEquipmentInstances :

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

    Die beiden Kennungen bilden den Schlüssel zur Assoziation. Es gibt keineIdentifier um zu holen. Derselbe Link kann nicht zweimal erzeugt werden; eine zweite Schöpfung kehrt zurück 409 Conflict.

    Nach Überprüfung beider Enden kann die Assoziation direkt gelesen werden:

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

    Um nur die Verbindung zwischen Instanz 34 und Perimeter 56 zu entfernen, steuern Sie beide Objekte in der Zielorg erneut und rufen Sie dann auf:

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

    Eine alternative Löschroute ist von der Instanz aus verfügbar:

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

    Das Entfernen dieser Assoziation löscht weder die Instanz noch den Scope. Um den Anwendungsbereich des Anhangs zu ändern, entferne den Link und erstelle dann eine neue Assoziation mit dem zuvor verifizierten Scope.

    9. Löschen Sie ein Objekt

    Finden Sie die Organisation, überprüfen Sie die Mitgliedschaft des Ziels und sprechen Sie deren Abhängigkeiten vor der Nutzung an DELETE. Um die im Beispiel erstellten Objekte zu bereinigen, entferne zuerst die Assoziation und dann die Instanz:

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

    Die Familie kann gelöscht werden, nachdem überprüft wurde, dass keine andere Instanz oder Abhängigkeit auf sie verweist:

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

    Der Umfang kann nach Behandlung seiner anderen Verbindungen, seiner möglichen Kinder und seiner anderen Abhängigkeiten gelöscht werden:

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

    10. Antworten und Fehler, die behoben werden müssen

    Antwort Gängige Auslegung
    200 OK Lesen oder aktualisieren Sie erfolgreich, wobei die Ressource nach Operation repräsentiert wird.
    201 Created Ressource erstellt; die Identifikatorin in der zurückgegebenen Darstellung oder im Header gelesen Location.
    204 No Content Erfolgreicher Betrieb ohne Körper; Löschungen werden erwartet. Ein Update kann auch keine Darstellung zurückgeben.
    value: [] Es gibt keine sichtbaren Objekte, die mit dem Filter übereinstimmen. Hören Sie auf zu schreiben, das hängt von dieser Suche ab.
    400 Bad Request Ungültiger Körper, Organisationsreferenz, die beim Erstellen eines Scopes, eines leeren Namens oder einer zirkulären Hierarchie nicht existiert.
    401 Unauthorized / 403 Forbidden Fehlende/ungültige Authentifizierung oder unzureichende Autorisierung. Eine nicht erreichbare Organisation oder Abhängigkeit kann ebenfalls zu einer Ablehnung führen.
    404 Not Found Ressource oder Vereinigung angefragt nicht gefunden.
    409 Conflict Name bereits verwendet oder Assoziation bereits vorhanden.

    Die genauen Antworten können je nach Art der Operation und API-Version variieren. Der Client muss den HTTP-Status, die Anzahl der Ergebnisse und die zurückgegebenen Werte überprüfen und dann den Fehlerkörper behalten, um die vom Server zurückgegebenen Details anzuzeigen oder zu protokollieren. Lese- und Schreibberechtigungen können unterschiedlich sein: Das Lesen eines Objekts garantiert nicht das Recht, es zu ändern.

    11. Vollständige Karriereübersicht

    1. Authentifiziere dich und finde dieOrganization Ziel.
    2. Um deinen Benutzernamen für die Bearbeitung zu behalten.
    3. Lesen Sie oder gründen Sie eine Familie Equipment in dieser Organisation.
    4. Lesen oder erstellen Sie eine EquipmentInstance mit der Kennung dieser Familie.
    5. Lesen oder erstellen Sie eine SupervisionScope in derselben Organisation.
    6. Kontrolliere beide Enden und schaffe dann ihre Assoziation.
    7. Vor jeglichen Änderungen oder Löschungen überprüfen Sie, dass die Ziele Mitglieder der Organisation sind.
    8. Daten nach Schreibvorgängen erneut abspielen; Assoziationen und Objekte bei Bedarf separat löschen.

    Die Organisation definiert den Arbeitsumfang; Identifikatoren geben die während der Verarbeitung verwendeten Ressourcen an. Halten Sie diese beiden Informationen zusammen, um eine Vermischung von Daten mehrerer Organisationen zu vermeiden.