Oracle Cloud Infrastructure-Dokumentation

Digital Twin Adapter erstellen

Erstellen Sie einen digitalen Zwillingsadapter, um Rohdaten-Payloads, die von und zu einem physischen Gerät oder einem externen System kommen, in normalisierte Telemetriedaten basierend auf dem digitalen Zwillingsmodell zu konvertieren.

Die Daten werden als JSON-Objekt mit den Daten und dem Mapping an den digitalen Zwillingsadapter übergeben.

Konzepte

Bei der Arbeit mit strukturierten Daten ist ein digitaler Zwillingsadapter erforderlich.

Es gibt zwei Möglichkeiten, einen digitalen Zwillingsadapter zu verwenden, je nachdem, ob das Gerät, mit dem Sie arbeiten, so programmiert werden kann, dass Daten gesendet werden:

  • Standardadapterformat: Wenn das Gerät so programmiert werden kann, dass Daten in dem Format gesendet werden, mit dem Sie arbeiten möchten, erstellen Sie einen digitalen Zwillingsadapter, ohne inbound-envelope oder inbound-routes anzugeben. Die Antwort enthält Daten im Standardformat des Geräts. Wenn die Envelope-Zuordnung angegeben ist und einen timeObserved enthält, wird receivedTime als timeObserved-Wert verwendet. Ein bestimmtes Beispiel finden Sie unter Szenario: Gesendete strukturierte Daten in einem Standardformat mit HTTPs.
  • Benutzerdefiniertes Adapterformat: Für Geräte, die nicht so programmiert werden können, dass Daten gesendet werden, können Sie einen benutzerdefinierten digitalen Zwillingsadapter erstellen, indem Sie einen benutzerdefinierten inbound-envelope- und envelope-mapping-Adapter definieren, der die Payload und Metadaten transformiert, um die Ausgabe abzurufen, mit der Sie arbeiten möchten. Ein bestimmtes Beispiel finden Sie unter Szenario: Senden strukturierter Daten in einem benutzerdefinierten Format mit HTTPs.
  • Authentifizierungs-ID: Wenn Sie einen digitalen Zwillingsadapter erstellen, wenn Sie ein Gerät verbinden, muss die zugehörige digitale Zwillingsinstanz einen Authentifizierungs-ID-Parameter mit einem Zertifikat oder Secret verwenden, um das Gerät zu authentifizieren.
  • Externer Schlüssel: Nachdem Sie einen Digital Twin Adapter erstellt haben, können Sie den Digital Twin Adapter aktualisieren, um den externen Schlüssel für ein Gerät zu ändern. Wenn Sie Daten senden, verwenden Sie den externen Schlüssel als Benutzernamen für das Gerät.
  • Limit: Die maximale Anzahl eingehender Routen für einen Digital Twin Adapter beträgt 128.
Beispiel für Geräte-Payload-Eingabe, JSON-Zuordnung und transformiertes Ergebnis

Sie können die Adapterzuordnung in JQ-Playground versuchen, indem Sie die Payload als Abfrageeingabe einfügen, die JSON-Zuordnung im JSON-Abschnitt hinzufügen und dann das Ausgabeergebnis anzeigen.

Beispiel für Geräte-Payload-JSON:

{ "time": "<timestamp>", "temp": 65, "hum": 55 }

Verwenden Sie entweder einen JQ-Ausdruck oder JsonPath Notation, um eine JSON-Zuordnungsausgabe für Adapter-Payloads zu erstellen.

In diesem Beispiel wird ein JQ-Ausdruck verwendet: 
{ "temperature": ".temp", "humidity": ".hum", "timeObserved": ".time" }
In diesem Beispiel wird die JSON-Zuordnungsausgabe der Adapter-Payload mit JsonPath Notation erstellt:
{ "temperature": "$.temp", "humidity": "$.hum", "timeObserved": "$.time" }
Transformiertes Ausgabeergebnis:
{ "temperature": 65, "humidity": 55, "timeObserved": "<timestamp>" }

Weitere Beispiele finden Sie unter Referenz: JQ-Ausdrücke für digitale Zwillingsadapter und Szenarios.

  • Wenn das Gerät unstrukturierte Daten sendet oder empfängt, müssen Sie keinen digitalen Zwillingsadapter angeben.

    1. Wählen Sie auf der Listenseite IoT-Domains die IoT-Domain aus, mit der Sie arbeiten möchten. Informationen zum Suchen der Listenseite für IoT-Domains finden Sie unter IoT-Domains auflisten.
    2. Wählen Sie die Registerkarte Digital Twin Adapter aus, und wählen Sie Erstellen aus.
    3. Geben Sie einen Namen und optional eine Beschreibung ein. Geben Sie keine vertraulichen Informationen ein.
    4. So suchen Sie das digitale Zwillingsmodell, das Sie zuordnen möchten:
      • Modell auswählen: So suchen Sie nach dem digitalen Zwillingsmodell nach Namen.
      • Mit Modellspezifikations-URI auswählen: So suchen Sie mit DTMI nach dem digitalen Zwillingsmodell. Beispiel: dtmi:com:example:iot:demo;1
    5. Abhängig davon, ob das Gerät, mit dem Sie arbeiten, so programmiert werden kann, dass Daten in bestimmten Formaten gesendet werden:
      • Wenn das Gerät so programmiert werden kann, dass Daten in einem bestimmten Format gesendet werden, müssen Sie den Envelop und die Routen des Adapters nicht angeben. Der Adapter wird aus der Geräte-Payload generiert.
      • Wenn das Gerät nicht programmiert werden kann, um Daten in dem gewünschten Format zu senden, geben Sie einen Adapter an, um die eingehende Payload in das Datenformat zu übersetzen, mit dem Sie arbeiten möchten. Aktivieren Sie die Option Eingehenden Envelope und Routen angeben:
        • Eingehende Envelope-Datei .json hochladen: Laden Sie eine .json-Datei hoch, die den eingehenden Envelope für diesen Adapter enthält.
        • JSON für eingehenden Envelope einfügen: Fügen Sie diesem Adapter die eingehende Envelope-JSON hinzu.
    6. Spezifikation für eingehende Routen: Fügen Sie eine Liste der Routendefinitionen mit Bedingungen und optionalen Payload-Zuordnungen hinzu. Routen werden in folgender Reihenfolge ausgewertet.
      • JSON-Datei für eingehende Routen hochladen: Laden Sie eingehende Routen in eine .json-Datei hoch.
      • JSON für eingehende Routen einfügen: Fügen Sie die eingehenden Routen im JSON-Format hinzu.
    7. Tags: (Optional) Fügen Sie dem digitalen Zwillingsadapter ein oder mehrere Tags hinzu. Wenn Sie über Berechtigungen zum Erstellen einer Ressource verfügen, sind Sie auch berechtigt, Freiformtags auf diese Ressource anzuwenden. Um ein definiertes Tag zuzuweisen, benötigen Sie die Berechtigungen zum Verwenden des Tag-Namespace. Weitere Informationen zum Tagging finden Sie unter Ressourcentags. Wenn Sie nicht sicher sind, ob Tags angewendet werden sollen, überspringen Sie diese Option, oder fragen Sie einen Administrator. Sie können Tags später anwenden.
    8. Wählen Sie Erstellen.

  • Verwenden Sie den Befehl oci iot digital-twin-adapter create und die erforderlichen Parameter, um einen digitalen Zwillingsadapter zu erstellen.

    So erstellen Sie einen digitalen Zwillingsadapter für strukturierte Daten in einem Standardformat: Wenn das Gerät programmiert werden kann, erstellen Sie einen digitalen Zwillingsadapter, ohne inbound-envelope oder envelope-mapping als Ergebnis anzugeben, dass die Standarddaten, die vom Gerät stammen, in der Antwort akzeptiert werden.

    Zwei Optionen für die Verknüpfung des digitalen Zwillingsmodells:

    • Verwenden von DTMI:

      Im folgenden Beispiel wird der DTMI-URI-Parameter verwendet, um den Adapter mit dem digitalen Zwillingsmodell zu verknüpfen. Ersetzen Sie <digital-twin-model-spec-uri> durch den DTMI-URI für das zugehörige digitale Zwillingsmodell. 
      oci iot digital-twin-adapter create --iot-domain-id <iot-domain-OCID> --digital-twin-model-spec-uri '<digital-twin-model-spec-uri>'
    • OCID des Digital Twin-Modells verwenden:
      Alternativ verwendet das folgende Beispiel den Parameter --digital-twin-model-id mit dem <digital-twin-model-OCID> für das digitale Zwillingsmodell, das Sie einem digitalen Zwillingsadapter zuordnen möchten:
      oci iot digital-twin-adapter create --iot-domain-id <iot-domain-OCID> --digital-twin-model-id <digital-twin-model-OCID>

    So erstellen Sie einen digitalen Zwillingsadapter für strukturierte Daten in einem benutzerdefinierten Format:

    Verwenden Sie den Befehl oci iot digital-twin-adapter create und den erforderlichen Parameter --iot-domain-id. Um einen benutzerdefinierten digitalen Zwillingsadapter zu erstellen, definieren Sie einen bestimmten inbound-envelope- oder inbound-route-Wert, um die Ausgabe abzurufen, mit der Sie arbeiten möchten. Definieren Sie dazu die benutzerdefinierte Payload-Zuordnung für Ihren digitalen Zwilling, indem Sie eine <file://inbound-envelope.json>-Datei und eine <file://inbound-routes.json>-Datei mit JQ-Ausdrücken verwenden.

    Ersetzen Sie <digital-twin-model-spec-uri> durch die DTMI-URI für das zugehörige digitale Zwillingsmodell, und ersetzen Sie <iot-domain-OCID> durch die IoT-Domain-OCID, die Sie mit diesem digitalen Zwillingsadapter verknüpfen möchten:

    oci iot digital-twin-adapter create --iot-domain-id <iot-domain-OCID> --digital-twin-model-spec-uri '<digital-twin-model-spec-uri>' --inbound-envelope <file://inbound-envelope.json> --inbound-routes <file://inbound-routes.json>

    Weitere Informationen zum Referenzieren von Dateien finden Sie unter JSON-Datei für komplexe Eingaben nutzen.

    Eine vollständige Liste der Parameter und Werte für CLI-Befehle finden Sie in CLI-Befehlsreferenz.

  • Führen Sie den Vorgang CreateDigitalTwinAdapter aus, um einen digitalen Zwillingsadapter in der angegebenen IoT-Domain zu erstellen.