Szenario: Digitale Zwillinge für indirekt verbundene Geräte mit einem Gateway erstellen

Erstellen Sie digitale Zwillingsmodelle, Adapter, ein Gateway, direkte und indirekte digitale Zwillingsinstanzen für Geräte, damit Sie Telemetrie und Befehle über ein gemeinsames Gateway weiterleiten können.

Verwenden Sie dieses Szenario, um ein wiederverwendbares Gateway, ein direkt verbundenes Gerät und mehrere indirekt verbundene Geräte zu erstellen.

Um dieses Szenario zu veranschaulichen, modellieren die Beispiele ein kleines Gebäudeheizungs-, Lüftungs- und Klimatisierungssystem (HVAC), einschließlich:

Ein Gateway mit dem Namen Bosch Gateway 1 authentifiziert sich bei der IoT-Domain und erfasst oder leitet Daten für Geräte wie HLK-Einheiten, Kessel und Entfeuchter weiter.
Die direkt verbundene HVAC-Instanz zeigt ein Gerät an, das seine eigene Telemetrie sendet.
Die indirekt verbundenen HVAC-, Boiler- und Entfeuchterinstanzen zeigen Geräte an, deren Telemetrie und Befehle stattdessen durch das Gateway geleitet werden.

Weitere Konzepte finden Sie unter Häufig gestellte Fragen zu indirekt verbundenen Geräten.

Sehen Sie sich das Diagramm an, um zu verstehen, wie das Gateway, direkt verbundene Geräte und indirekt verbundene Geräte mit den 3 Arten von digitalen Zwillingsinstanzen interagieren.

Aufgaben

Erstellen Sie digitale Zwillingsmodelle.
Erstellen Sie digitale Zwillingsadapter.
Gateway- und Geräteinstanzen erstellen.
Telemetriedaten senden.
Inhalte der digitalen Zwillingsinstanz abrufen.
Rufen Sie Befehle auf.

Weitere Informationen zum Referenzieren von Dateien über die CLI finden Sie unter JSON-Datei für komplexe Eingaben verwenden.

Schritt 1: Digitale Zwillingsmodelle erstellen

Erstellen Sie ein digitales Zwillingsmodell für das Gateway und ein digitales Zwillingsmodell für jeden Gerätetyp im Szenario. Diese Geräte geben strukturierte Daten aus.

Speichern Sie die folgenden Dateien mit den folgenden Snippets: gateway-model.json, hvac-model.json und boiler-model.json.

Verwenden Sie die Konsole, wenn Sie eine gespeicherte Modelldatei hochladen oder die Spezifikation direkt einfügen möchten.

Öffnen Sie auf der Listenseite IoT-Domains die Domain, mit der Sie arbeiten möchten. Wenn Sie Hilfe beim Suchen der Listenseite für IoT-Domains benötigen, finden Sie weitere Informationen unter IoT-Domains auflisten oder Neue IoT-Domain erstellen.
Wählen Sie die Registerkarte Digitale Zwillingsmodelle und dann Erstellen aus.
Geben Sie eine Bezeichnung und eine optionale Beschreibung ein. Geben Sie dabei keine vertraulichen Informationen ein.
Wählen Sie Spezifikation hochladen oder Spezifikation einfügen, und verwenden Sie dann eine der Beispieldateien aus diesem Szenario.
Optional: Fügen Sie Tags hinzu.
Wählen Sie Erstellen.

Verwenden Sie eine der folgenden Dateien, wenn Sie die Spezifikation hochladen oder einfügen.

gateway-model.json

{
  "@context": [
    "dtmi:dtdl:context;3"
  ],
  "@id": "dtmi:com:oracle:example:gateway;1",
  "@type": "Interface",
  "displayName": "Gateway",
  "description": "A digital twin model for Gateway",
  "contents": [
    {
      "@type": "Telemetry",
      "name": "cpuUtilization",
      "schema": "integer"
    },
    {
      "@type": "Telemetry",
      "name": "memoryUtilization",
      "schema": "integer"
    },
    {
      "@type": "Telemetry",
      "name": "storageUtilization",
      "schema": "integer"
    },
    {
      "@type": "Property",
      "name": "firmwareVersion",
      "schema": "string"
    }
  ]
}

hvac-model.json

{
  "@context": [
    "dtmi:dtdl:context;3"
  ],
  "@id": "dtmi:com:oracle:example:hvac;1",
  "@type": "Interface",
  "displayName": "HVAC",
  "description": "A digital twin model for HVAC",
  "contents": [
    {
      "@type": "Telemetry",
      "name": "temperature",
      "schema": "integer"
    },
    {
      "@type": "Telemetry",
      "name": "humidity",
      "schema": "integer"
    }
  ]
}

boiler-model.json

{
  "@context": [
    "dtmi:dtdl:context;3"
  ],
  "@id": "dtmi:com:oracle:example:boiler;1",
  "@type": "Interface",
  "displayName": "Boiler",
  "description": "A digital twin model for Boiler",
  "contents": [
    {
      "@type": "Telemetry",
      "name": "temperature",
      "schema": "integer"
    },
    {
      "@type": "Telemetry",
      "name": "pressure",
      "schema": "integer"
    }
  ]
}

Verwenden Sie den Befehl oci iot digital-twin-model create, um jedes digitale Zwillingsmodell in der IoT-Domain zu erstellen.

Gatewaymodell erstellen

oci iot digital-twin-model create \
  --iot-domain-id <iot-domain-OCID> \
  --spec file://gateway-model.json

HVAC-Modell erstellen

oci iot digital-twin-model create \
  --iot-domain-id <iot-domain-OCID> \
  --spec file://hvac-model.json

Boiler-Modell erstellen

oci iot digital-twin-model create \
  --iot-domain-id <iot-domain-OCID> \
  --spec file://boiler-model.json

In diesem Beispiel speichern Sie diese Snippets in diesen Modelldateien gateway-model.json, hvac-model.json und boiler-model.json.

gateway-model.json

{
  "@context": [
    "dtmi:dtdl:context;3"
  ],
  "@id": "dtmi:com:oracle:example:gateway;1",
  "@type": "Interface",
  "displayName": "Gateway",
  "description": "A digital twin model for Gateway",
  "contents": [
    {
      "@type": "Telemetry",
      "name": "cpuUtilization",
      "schema": "integer"
    },
    {
      "@type": "Telemetry",
      "name": "memoryUtilization",
      "schema": "integer"
    },
    {
      "@type": "Telemetry",
      "name": "storageUtilization",
      "schema": "integer"
    },
    {
      "@type": "Property",
      "name": "firmwareVersion",
      "schema": "string"
    }
  ]
}

hvac-model.json

{
  "@context": [
    "dtmi:dtdl:context;3"
  ],
  "@id": "dtmi:com:oracle:example:hvac;1",
  "@type": "Interface",
  "displayName": "HVAC",
  "description": "A digital twin model for HVAC",
  "contents": [
    {
      "@type": "Telemetry",
      "name": "temperature",
      "schema": "integer"
    },
    {
      "@type": "Telemetry",
      "name": "humidity",
      "schema": "integer"
    }
  ]
}

boiler-model.json

{
  "@context": [
    "dtmi:dtdl:context;3"
  ],
  "@id": "dtmi:com:oracle:example:boiler;1",
  "@type": "Interface",
  "displayName": "Boiler",
  "description": "A digital twin model for Boiler",
  "contents": [
    {
      "@type": "Telemetry",
      "name": "temperature",
      "schema": "integer"
    },
    {
      "@type": "Telemetry",
      "name": "pressure",
      "schema": "integer"
    }
  ]
}

Führen Sie den Vorgang CreateDigitalTwinModel aus, um ein digitales Zwillingsmodell in der IoT-Domain zu erstellen.

Verwenden Sie dieselbe DTDL-Payload wie in den Beispieldateien des digitalen Zwillingsmodells, wenn Sie die API aufrufen.

Schritt 2: Digitale Twin Adapter erstellen

Erstellen Sie einen Adapter für das Gateway und einen Adapter für jeden strukturierten Gerätetyp, der eine Payload-Zuordnung erfordert.

Speichern Sie die folgenden Dateien mit den Snippets: gateway-envelope.json, gateway-routes.json, hvac-envelope.json, hvac-routes.json, boiler-envelope.json und boiler-routes.json.

Ziel im eingehenden Envelope auflösen

Gatewayadapter können die Zielinstanz des digitalen Zwillings identifizieren, wenn alle weitergeleiteten Gerätenachrichten demselben Thema oder derselben Payload-Konvention folgen. Das Gateway authentifiziert sich selbst. Der Service prüft, ob es sich bei dem aufgelösten Ziel um eine indirekt verbundene digitale Zwillingsinstanz handelt, die mit diesem Gateway verknüpft ist. Anschließend delegiert der Service die Payload an den Adapter des Zielgeräts, wenn eine strukturierte Zuordnung erforderlich ist.

Das Gateway löst target und contentRoot einmal für die gesamte Nachricht auf, bevor Routen ausgeführt werden. Wenn target in einen indirekt verbundenen externen Schlüssel des Geräts aufgelöst wird, wird die Payload an dieses Gerät delegiert. Wenn target leer oder Null ist, wird die Nachricht als Gatewaydaten behandelt.

Verwenden Sie einen digitalen Zwillingsadapter, wenn die eingehende Nutzlast dem Zielmodell des digitalen Zwillings zugeordnet werden muss. Ein digitaler Zwillingsadapter ist nicht erforderlich, wenn das Gerät unstrukturierte Daten sendet, Sie können Daten unverändert weitergeben.

Öffnen Sie auf der Listenseite IoT-Domains die Domain, mit der Sie arbeiten möchten.
Wählen Sie die Registerkarte Digital Twin Adapter und dann Erstellen aus.
Geben Sie einen Namen und eine optionale Beschreibung ein. Geben Sie dabei keine vertraulichen Informationen ein.
Wählen Sie das digitale Zwillingsmodell aus, das mit der Payload übereinstimmt, die Sie zuordnen.
Aktivieren Sie Eingehenden Envelope und Routen angeben, und laden Sie dann die Envelope-JSON hoch, oder fügen Sie sie ein, und leiten Sie JSON für den Adapter weiter.
Optional: Fügen Sie Tags hinzu.
Wählen Sie Erstellen.

Erstellen Sie den Gatewayadapter mit diesen Gatewaydateien.

Gateway-Envelope.json

{
  "referenceEndpoint": "/data",
  "referencePayload": {
    "dataFormat": "JSON",
    "data": {
      "time": 1773768299143534,
      "cpuUtil": 0,
      "memUtil": 0,
      "diskUtil": 0,
      "firmware": "Oracle Linux 9.1"
    }
  },
  "envelopeMapping": {
    "timeObserved": "$.time",
    "target": "${if ([\"boilers\", \"hvacs\", \"dehumidifiers\"] | contains([endpoint(1)])) then endpoint(2) else null end}",
    "contentRoot": "$"
  }
}

gateway-routes.json

[
  {
    "condition": "*",
    "payloadMapping": {
      "$.cpuUtilization": "$.cpuUtil",
      "$.memoryUtilization": "$.memUtil",
      "$.storageUtilization": "$.diskUtil",
      "$.firmwareVersion": "$.firmware"
    }
  }
]

HLK- und Kesseladapter mit den entsprechenden Gerätedateien erstellen.

hvac-envelope.json

{
  "referenceEndpoint": "/telemetry",
  "referencePayload": {
    "dataFormat": "JSON",
    "data": {
      "time": 1773768299143534,
      "temperature": 0,
      "humidity": 0
    }
  },
  "envelopeMapping": {
    "timeObserved": "$.time"
  }
}

hvac-routes.json

[
  {
    "condition": "*",
    "payloadMapping": {
      "$.temperature": "$.temperature",
      "$.humidity": "$.humidity"
    }
  }
]

boiler-envelope.json

{
  "referenceEndpoint": "/telemetry",
  "referencePayload": {
    "dataFormat": "JSON",
    "data": {
      "timestamp": 1773768299143534,
      "temperature": 0,
      "pressure": 0
    }
  },
  "envelopeMapping": {
    "timeObserved": "$.timestamp"
  }
}

boiler-routes.json

[
  {
    "condition": "*",
    "payloadMapping": {
      "$.temperature": "$.temperature",
      "$.pressure": "$.pressure"
    }
  }
]

Verwenden Sie den Befehl oci iot digital-twin-adapter create, um jeden Adapter in der IoT-Domain zu erstellen.

Gatewayadapter erstellen

Mit diesem Befehl erstellen Sie einen digitalen Zwillingsadapter. Dieses Beispiel zeigt, wie das digitale Zwillingsmodell mit dem DTMI verknüpft wird und wie der Envelope und die Routen mit .json-Dateien definiert werden.

oci iot digital-twin-adapter create \
  --iot-domain-id <iot-domain-OCID> \
  --digital-twin-model-spec-uri "dtmi:com:oracle:example:gateway;1" \
  --inbound-envelope file://gateway-envelope.json \
  --inbound-routes file://gateway-routes.json

Gateway-Envelope.json

{
  "referenceEndpoint": "/data",
  "referencePayload": {
    "dataFormat": "JSON",
    "data": {
      "time": 1773768299143534,
      "cpuUtil": 0,
      "memUtil": 0,
      "diskUtil": 0,
      "firmware": "Oracle Linux 9.1"
    }
  },
  "envelopeMapping": {
    "timeObserved": "$.time",
    "target": "${if ([\"boilers\", \"hvacs\", \"dehumidifiers\"] | contains([endpoint(1)])) then endpoint(2) else null end}",
    "contentRoot": "$"
  }
}

gateway-routes.json

[
  {
    "condition": "*",
    "payloadMapping": {
      "$.cpuUtilization": "$.cpuUtil",
      "$.memoryUtilization": "$.memUtil",
      "$.storageUtilization": "$.diskUtil",
      "$.firmwareVersion": "$.firmware"
    }
  }
]

HVAC-Adapter erstellen

oci iot digital-twin-adapter create \
  --iot-domain-id <iot-domain-OCID> \
  --digital-twin-model-spec-uri "dtmi:com:oracle:example:hvac;1" \
  --inbound-envelope file://hvac-envelope.json \
  --inbound-routes file://hvac-routes.json

hvac-envelope.json

{
  "referenceEndpoint": "/telemetry",
  "referencePayload": {
    "dataFormat": "JSON",
    "data": {
      "time": 1773768299143534,
      "temperature": 0,
      "humidity": 0
    }
  },
  "envelopeMapping": {
    "timeObserved": "$.time"
  }
}

hvac-routes.json

[
  {
    "condition": "*",
    "payloadMapping": {
      "$.temperature": "$.temperature",
      "$.humidity": "$.humidity"
    }
  }
]

Boiler-Adapter erstellen

oci iot digital-twin-adapter create \
  --iot-domain-id <iot-domain-OCID> \
  --digital-twin-model-spec-uri "dtmi:com:oracle:example:boiler;1" \
  --inbound-envelope file://boiler-envelope.json \
  --inbound-routes file://boiler-routes.json

boiler-envelope.json

{
  "referenceEndpoint": "/telemetry",
  "referencePayload": {
    "dataFormat": "JSON",
    "data": {
      "timestamp": 1773768299143534,
      "temperature": 0,
      "pressure": 0
    }
  },
  "envelopeMapping": {
    "timeObserved": "$.timestamp"
  }
}

boiler-routes.json

[
  {
    "condition": "*",
    "payloadMapping": {
      "$.temperature": "$.temperature",
      "$.pressure": "$.pressure"
    }
  }
]

Weitere Informationen zum Referenzieren von Dateien über die CLI finden Sie unter JSON-Datei für komplexe Eingaben verwenden.

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

Verwenden Sie dieselben eingehenden Envelope- und eingehenden Routen-Payloads wie in den Beispieldateien.

Schritt 3: Gateway- und Device-Instanzen erstellen

Erstellen Sie zuerst das Gateway, damit Sie es wiederverwenden können, wenn Sie die indirekt verbundenen Geräte erstellen.

Authentifizierungs-ID-Optionen:

Wenn Sie beim Testen von digitalen Zwillingsinstanzen die Secret-OCID als Authentifizierungs-ID verwenden, verwenden Sie den Gerätenamen als externen Schlüssel und den Secret-Inhalt im Klartext als Gerätekennwort. Anweisungen dazu finden Sie unter Secret erstellen in Schritt 7. Informationen zu Secrets, die bereits erstellt wurden, finden Sie unter Inhalte eines Secrets abrufen.
Verwenden Sie für digitale Zwillingsinstanzen in der Produktion die OCID des mTLS-Zertifikats anstelle eines Vault Secrets als Authentifizierungs-ID. Wenn Sie ein mTLS-Zertifikat verwenden, müssen Sie den allgemeinen Namen aus den Zertifikatsdetails als externen Schlüssel verwenden: --external-key <common-name-from-certificate-details>

Verwenden Sie die Konsole, um ein Gateway zu erstellen und mehrere Geräte damit zu verknüpfen.
In der Konsole gibt es zwei Möglichkeiten, ein Gateway für die IoT-Domain zu erstellen. Sie können ein Gateway auf der Registerkarte Digitale Zwillingsinstanz erstellen, indem Sie den Gatewaytyp auswählen, wenn Sie eine digitale Zwillingsinstanz erstellen. Sie können auch die Registerkarte Gateway auswählen, um das Gateway zu erstellen.
1. Öffnen Sie auf der Listenseite IoT-Domains die IoT-Domain, mit der Sie arbeiten möchten.
2. Wählen Sie die Registerkarte Gateways aus, und wählen Sie Erstellen aus, um eine Bosch-Gatewayinstanz zu erstellen, damit sie für indirekte Geräte verfügbar ist.
  - Geben Sie einen Namen für das Gateway und eine Beschreibung ein.
  - Geben Sie das externe Schlüssel-gateway1 ein.
  - Wählen Sie den Adapter aus, der gateway-envelope.json und gateway-routes.json verwendet, die in Schritt 2 erstellt wurden.
  - Wählen Sie die Authentifizierungs-ID aus, oder fügen Sie die OCID der Authentifizierungs-ID ein, und wählen Sie Erstellen aus.
3. Wählen Sie auf der Seite IoT-Domain die Registerkarte Digitale Zwillingsinstanzen aus, wählen Sie Erstellen aus, und wählen Sie dann direkt oder indirekt als Typ aus, um die digitalen Zwillingsinstanzen für diese Geräte zu erstellen. Verwenden Sie dazu das Modell und die Adapter, die in Schritt 1 und Schritt 2 erstellt wurden für:
  - direkt mit dem externen Schlüssel hvac1 verbundene LG HVAC-Instanz.
  - indirekt verbundene HVAC-Instanz mit dem externen Schlüssel hvac2
  - indirekt verbundene Boilerinstanz mit dem externen Schlüssel boiler1.
  - indirekt verbundene Entfeuchterinstanz mit dem externen Schlüssel dehumidifier1. Der Luftentfeuchter verwendet keinen digitalen Zwillingsadapter oder ein digitales Zwillingsmodell, da er unstrukturierte Rohtelemetrie sendet, die keine strukturierte Nutzlastzuordnung benötigt. Sie kann auch raw-Befehle über das Gateway empfangen.
  Hinweis
  
  Wenn Sie keinen externen Schlüssel eingeben, wird er generiert.
4. Wählen Sie für die direkt verbundene und die Gatewayinstanz eine Authentifizierungs-ID aus.
5. Bei einer indirekt verbundenen Instanz wählen Sie mindestens ein vorhandenes Gateways aus, anstatt Zugangsdaten für die Geräteauthentifizierung hinzuzufügen. Wählen Sie mehrere Gateways aus, wenn ein drahtloses Gerät zwischen Gateways durchlaufen kann.
6. Optional: Fügen Sie Tags hinzu.
7. Prüfen Sie die Zusammenfassung der digitalen Zwillingsinstanz, und wählen Sie Erstellen aus.
Nachdem Sie die digitalen Zwillingsinstanzen erstellt haben, zeigen Sie auf der Seite Gatewaydetails an, welche Geräte vom Gateway abhängig sind und mit diesem verknüpft sind.
- Suchen Sie die Gatewaydetails auf der Seite "IoT-Domain", indem Sie die Registerkarte Gateway auswählen, um die Gatewayliste anzuzeigen. Wählen Sie ein Gateway aus, um zur Seite "Gatewaydetails" zu gelangen.
- Auf der Registerkarte Digitale Zwillingsinstanz können Sie nach Typ suchen, um die verschiedenen digitalen Zwillingsinstanztypen für eine IoT-Domain anzuzeigen.
- Zeigen Sie die direkt und indirekt verbundenen Geräte auf der Detailseite der digitalen Zwillingsinstanz an.
Eine vollständige Liste der Einstellungen finden Sie unter Digitale Zwillingsinstanzen erstellen, Digitale Zwillingsinstanzen auflisten und Instanzdetails eines digitalen Zwillings abrufen.
Mit dem Befehl oci iot digital-twin-instance create können Sie das Gateway und die direkt verbundenen und indirekt verbundenen Geräteinstanzen erstellen.

Direkt verbundene HVAC-Instanz erstellen
Mit diesem Befehl können Sie eine digitale Zwillingsinstanz erstellen, die mit einer bestimmten IoT-Domain verknüpft ist und direkt mit einem externen Schlüssel hvac1 verbunden ist.
```
oci iot digital-twin-instance create \
  --iot-domain-id <iot-domain-OCID> \
  --connectivity-type DIRECT \
  --display-name "LG HVAC 1" \
  --auth-id <certificate-or-secret-OCID> \
  --digital-twin-adapter-id <hvac-adapter-OCID> \
  --external-key hvac1
```
Gatewayinstanz erstellen
Verwenden Sie diesen Befehl, um eine digitale Zwillingsinstanz zu erstellen, die mit einer bestimmten IoT-Domain verknüpft ist. Verwenden Sie den erforderlichen Parameter --connectivity-type mit dem Wert GATEWAY, um eine digitale Zwillingsinstanz zu erstellen, die ein Gateway ist. Der externe Schlüssel ist gateway1.
```
oci iot digital-twin-instance create \
  --iot-domain-id <iot-domain-OCID> \
  --connectivity-type GATEWAY \
  --display-name "Bosch Gateway 1" \
  --auth-id <certificate-or-secret-OCID> \
  --digital-twin-adapter-id <gateway-adapter-OCID> \
  --external-key gateway1
```
Indirekt verbundene HVAC-Instanz erstellen
Verwenden Sie diesen Befehl und den erforderlichen Parameter --connectivity-type INDIRECT, um einen digitalen Zwilling zu erstellen, der ein indirekt verbundenes Gerät ist. In diesem Szenario wird eine Gatewayverknüpfung pro Gerät angezeigt. Wenn Ihr Deployment Roaming unterstützt, verknüpfen Sie das indirekt verbundene Gerät mit mehr als einem Gateway, damit es zwischen ihnen wechseln kann, ohne die Instanz des digitalen Zwillings zu ändern.
Hinweis

Wenn Sie ein indirekt verbundenes Gerät mit dem erforderlichen Parameter --gateways erstellen, handelt es sich um einen komplexen Typ, der ein JSON-Array verwenden muss. Beispiel: --gateways '["<gateway-instance-OCID>"]' oder für Roaming verwenden Sie --gateways '["<gateway-instance-1-OCID>","<gateway-instance-2-OCID>"]'. Alternativ können Sie eine .json-Datei verwenden.
```
oci iot digital-twin-instance create \
  --iot-domain-id <iot-domain-OCID> \
  --connectivity-type INDIRECT \
  --display-name "LG HVAC 2" \
  --gateways '["<gateway-instance-OCID>"]' \
  --digital-twin-adapter-id <hvac-adapter-OCID> \
  --external-key hvac2
```
Indirekt verbundene Boiler-Instanz erstellen
Verwenden Sie diesen Befehl und den erforderlichen Parameter --connectivity-type INDIRECT, um einen digitalen Zwilling zu erstellen, der ein indirekt verbundenes Gerät ist.
```
oci iot digital-twin-instance create \
  --iot-domain-id <iot-domain-OCID> \
  --connectivity-type INDIRECT \
  --display-name "GE Boiler 1" \
  --gateways '["<gateway-instance-OCID>"]' \
  --digital-twin-adapter-id <boiler-adapter-OCID> \
  --external-key boiler1
```
Indirekt verbundene Entfeuchterinstanz erstellen
Verwenden Sie diesen Befehl und den erforderlichen Parameter --connectivity-type INDIRECT, um einen digitalen Zwilling zu erstellen, der ein indirekt verbundenes Gerät ist.
```
oci iot digital-twin-instance create \
  --iot-domain-id <iot-domain-OCID> \
  --connectivity-type INDIRECT \
  --display-name Danby Dehumidifier 1 \
  --gateways '["<gateway-instance-OCID>"]' \
  --external-key dehumidifier1
```
Führen Sie den Vorgang CreateDigitalTwinInstance aus, um eine Gatewayinstanz, eine direkt verbundene Instanz und eine indirekt verbundene Instanz zu erstellen.

Wenn Sie eine indirekt verbundene Instanz erstellen, stellen Sie sicher, dass die Anforderung die Gatewayverknüpfung enthält.

Schritt 4: Telemetriedaten senden

Diese Beispiele zeigen drei Datenpfade. Ein direkt verbundenes Gerät, wie hvac1, authentifiziert sich mit einem eigenen externen Schlüssel und sendet Daten an seine eigene digitale Zwillingsinstanz. Das Gateway, gateway1, authentifiziert sich auch mit seinem eigenen externen Schlüssel, wenn es seine eigene CPU-, Speicher-, Speicher- und Firmware-Telemetrie sendet.

Indirekt verbundene Geräte authentifizieren sich nicht bei der IoT-Domain. Das Gateway authentifiziert sich als gateway1, und der Endpunktpfad, wie hvacs/hvac2, boilers/boiler1 oder dehumidifiers/dehumidifier1, identifiziert das Zielgerät hinter dem Gateway.

Installieren und konfigurieren Sie MQTTX.
Verwenden Sie <digital-twin-instance-external-key> als Gerätenamen. Wenn Sie den externen Schlüssel der digitalen Instanz finden müssen, können Sie Instanzdetails eines digitalen Zwillings abrufen.
Stellen Sie eine Verbindung zu <domain-short-id>.device.iot.<region>.oci.oraclecloud.com auf Port 8883 her, aktivieren Sie SSL/TLS, und verwenden Sie eine saubere Session.

Telemetrie von der direkt verbundenen HVAC-Instanz senden:

mqttx pub \
  -h '<domain-short-id>.device.iot.<region>.oci.oraclecloud.com' \
  -p 8883 \
  -l mqtts \
  -t 'data' \
  -m '{
    "temperature": 70,
    "humidity": 60
  }' \
  -u hvac1 \
  -P '<secret-contents>'

Telemetrie von der Gatewayinstanz senden:

mqttx pub \
  -h '<domain-short-id>.device.iot.<region>.oci.oraclecloud.com' \
  -p 8883 \
  -l mqtts \
  -t 'data' \
  -m '{
    "cpuUtil": 30,
    "memUtil": 25,
    "diskUtil": 20,
    "firmware": "Oracle Linux 9.1"
  }' \
  -u gateway1 \
  -P '<secret-contents>'

Telemetrie für die indirekt verbundene HVAC-Instanz über das Gateway senden:

mqttx pub \
  -h '<domain-short-id>.device.iot.<region>.oci.oraclecloud.com' \
  -p 8883 \
  -l mqtts \
  -t 'hvacs/hvac2' \
  -m '{
    "temperature": 75,
    "humidity": 65
  }' \
  -u gateway1 \
  -P '<secret-contents>'

Telemetrie für die indirekt verbundene Boilerinstanz über das Gateway senden:

mqttx pub \
  -h '<domain-short-id>.device.iot.<region>.oci.oraclecloud.com' \
  -p 8883 \
  -l mqtts \
  -t 'boilers/boiler1' \
  -m '{
    "temperature": 80,
    "pressure": 90
  }' \
  -u gateway1 \
  -P '<secret-contents>'

Telemetrie für die indirekt verbundene Entfeuchterinstanz über das Gateway senden:

mqttx pub \
  -h '<domain-short-id>.device.iot.<region>.oci.oraclecloud.com' \
  -p 8883 \
  -l mqtts \
  -t 'dehumidifiers/dehumidifier1' \
  -m 'humidity=50,fanSpeed=medium' \
  -u gateway1 \
  -P '<secret-contents>'

Verwenden Sie curl, um Telemetrie über HTTPS zu senden. In diesen Beispielen wird die HTTP-Basisauthentifizierung mit dem externen Schlüssel der Digital Twin Instance und dem Klartext-Secret-Content verwendet.

Verwenden Sie den externen Schlüssel der digitalen Zwillingsinstanz als Benutzernamen. Beispiel: Verwenden Sie für die direkt verbundene Telemetrie den externen Schlüssel der Instanz, wie hvac1.
Verwenden Sie den Secret-Inhalt im Klartext als Kennwort.
Senden Sie die Anforderung an https://<domain-short-id>.device.iot.<region>.oci.oraclecloud.com/<endpoint-path>.
Bei indirekt verbundenen Geräten authentifizieren Sie sich als Gatewayinstanz und verwenden den Endpunktpfad, um das Zielgerät zu identifizieren, wie hvacs/hvac2 oder boilers/boiler1.

Telemetrie von der direkt verbundenen HVAC-Instanz senden:

curl -i -u "hvac1:<secret-contents>" \
  -H "Content-Type: application/json" \
  -X POST \
  "https://<domain-short-id>.device.iot.<region>.oci.oraclecloud.com/data" \
  -d '{
    "temperature": 70,
    "humidity": 60
  }'

Telemetrie von der Gatewayinstanz senden:

curl -i -u "gateway1:<secret-contents>" \
  -H "Content-Type: application/json" \
  -X POST \
  "https://<domain-short-id>.device.iot.<region>.oci.oraclecloud.com/data" \
  -d '{
  "cpuUtil": 30,
  "memUtil": 25,
  "diskUtil": 20,
  "firmware": "Oracle Linux 9.1"
}'

Telemetrie für die indirekt verbundene HVAC-Instanz über das Gateway senden:

curl -i -u "gateway1:<secret-contents>" \
  -H "Content-Type: application/json" \
  -X POST \
  "https://<domain-short-id>.device.iot.<region>.oci.oraclecloud.com/hvacs/hvac2" \
  -d '{
    "temperature": 75,
    "humidity": 65
  }'

Telemetrie für die indirekt verbundene Boilerinstanz über das Gateway senden:

curl -i -u "gateway1:<secret-contents>" \
  -H "Content-Type: application/json" \
  -X POST \
  "https://<domain-short-id>.device.iot.<region>.oci.oraclecloud.com/boilers/boiler1" \
  -d '{
    "temperature": 80,
    "pressure": 90
  }'

Telemetrie für die indirekt verbundene Entfeuchterinstanz über das Gateway senden:

curl -i -u "gateway1:<secret-contents>" \
  -H "Content-Type: text/plain" \
  -X POST \
  "https://<domain-short-id>.device.iot.<region>.oci.oraclecloud.com/dehumidifiers/dehumidifier1" \
  -d 'humidity=50,fanSpeed=medium'

Optionaler Schritt 5: Instanzinhalt eines digitalen Zwillings abrufen

Um zu bestätigen, dass die Daten der Instanz des digitalen Zwillings erfasst werden, verwenden Sie die Konsole, die CLI oder die API, um den Instanzinhalt des digitalen Zwillings anzuzeigen, das sind die neuesten Snapshot-Daten.

Bei einer unstrukturierten digitalen Zwillingsinstanz für Daten verfügt sie in der Regel nicht über ein zugeordnetes digitales Zwillingsmodell. Daher können Sie die Inhalte für eine digitale Zwillingsinstanz abrufen nicht verwenden, um ihre Daten anzuzeigen.

1. Wählen Sie auf der Listenseite Domains die Domain, mit der Sie arbeiten möchten. Informationen zum Suchen der Listenseite für IoT-Domains oder einer IoT-Domain finden Sie unter IoT-Domains auflisten.
2. Wählen Sie die Registerkarte Digital Twin Instances aus.
3. Wählen Sie den Namen der digitalen Zwillingsinstanz aus. Die Detailseite wird geöffnet.
4. Wählen Sie die Registerkarte Daten aus, um die neuesten Snapshot-Daten für diese Instanz anzuzeigen. Weitere Informationen finden Sie unter IoT Domain Database Schema Reference.

Verwenden Sie den Befehl oci iot digital-twin-instance get-content und den erforderlichen Parameter, um den Instanzinhalt eines digitalen Zwillings abzurufen:

Prüfen Sie die direkt verbundene HVAC-Instanz:

oci iot digital-twin-instance get-content \
  --digital-twin-instance-id <lg-hvac-1-OCID>

Gatewayinstanz prüfen:

oci iot digital-twin-instance get-content \
  --digital-twin-instance-id <bosch-gateway-1-OCID>

Prüfen Sie die indirekt verbundene HVAC-Instanz:

oci iot digital-twin-instance get-content \
  --digital-twin-instance-id <lg-hvac-2-OCID>

Prüfen Sie die indirekt verbundene Boilerinstanz:

oci iot digital-twin-instance get-content \
  --digital-twin-instance-id <ge-boiler-1-OCID>

Führen Sie den Vorgang GetDigitalTwinInstanceContent aus, um Inhalt aus einer digitalen Zwillingsinstanz abzurufen.

Schritt 6: Befehle aufrufen

Verwenden Sie für indirekt verbundene Geräte eine at-least-once-Zustellungs-Policy, und erwarten Sie Wiederholungen oder doppelte Zustellung.

Wenn eine Antwort erforderlich ist, konfigurieren Sie einen Antwortendpunkt, damit das Gateway die Antwort im Namen des Zielgeräts veröffentlichen kann.

Verwenden Sie die Konsole, wenn Sie einen Raw-Befehl von der Detailseite der digitalen Zwillingsinstanz senden möchten.
1. Öffnen Sie die IoT-Domain, und wählen Sie die Registerkarte Digitale Zwillingsinstanzen.
2. Wählen Sie die Instanz, die Sie steuern möchten.
3. Wählen Sie im Menü Aktionen die Option Raw-Befehl senden.
4. Geben Sie den Anforderungsendpunkt, die Anforderungsdauer und die Befehls-Payload ein.
5. Optional: Konfigurieren Sie einen Antwortendpunkt und eine Antwortdauer, und wählen Sie Raw-Befehl senden aus. Verwenden Sie die Werte aus diesen Dateien: gateway-command.json, boiler-command.json
gateway-command.json
{ "force": true }
boiler-command.json
{ "hardReset": false }
Verwenden Sie den Befehl oci iot digital-twin-instance invoke-raw-json-command, um die Beispielaktionen in diesem Szenario aufzurufen. Weitere Informationen finden Sie unter Raw-Befehl von einer digitalen Zwillingsinstanz senden.

Gatewayinstanz neu starten
```
oci iot digital-twin-instance invoke-raw-json-command \
  --digital-twin-instance-id <bosch-gateway-1-OCID> \
  --request-endpoint "actions/reboot" \
  --request-data '{"force": true}'
```
Instanz des indirekt verbundenen Boilers zurücksetzen
Geben Sie die --request-endpoint an, in diesem Beispiel die boilers/boiler1/actions/reset.
Geben Sie die --response-endpoint an, in diesem Beispiel die boilers/boiler1/actions/response.
Wenn Sie eine Antwort erwarten, müssen Sie den Parameter --response-duration einschließen. Wenn nicht, geht der Befehl in den Status COMPLETED über, ohne die Antwort zu erhalten. Daher wird die Antwort des Befehls nicht in der Datenbanktabelle RAW_COMMAND_DATA erfasst.
```
oci iot digital-twin-instance invoke-raw-json-command \
  --digital-twin-instance-id <ge-boiler-1-OCID> \
  --request-endpoint "boilers/boiler1/actions/reset" \
  --request-data '{"hardReset": false}' \
  --response-endpoint "boilers/boiler1/actions/response" \
  --response-duration PT10M
```
Boiler-Antwort veröffentlichen
Verwenden Sie den Antwortendpunkt, um die Boilerantwort an diesen Endpunkt zu veröffentlichen: boilers/boiler1/actions/response in diesem Beispiel ist gateway1 der externe Schlüssel und der Gerätename.
```
mqttx pub \
  -h '<domain-short-id>.device.iot.<region>.oci.oraclecloud.com' \
  -p 8883 \
  -l mqtts \
  -t "boilers/boiler1/actions/response" \
  -m '{
    "status": "OK"
  }' \
  -u gateway1 \
  -P '<secret-contents>'
```
Den indirekt angeschlossenen Luftentfeuchter ausschalten
Mit diesem Befehl rufen Sie einen Raw-JSON-Befehl auf dem Gerät auf, das den Lüfter auf dem Entfeuchter abschaltet.
```
oci iot digital-twin-instance invoke-raw-json-command \
  --digital-twin-instance-id <danby-dehumidifier-1-OCID> \
  --request-endpoint "dehumidifiers/dehumidifier1/actions/fanOff" \
  --request-data '{"fanOff": true}'
```
Führen Sie den Vorgang InvokeRawCommand aus, um einen Raw-Befehl auf einem Gerät aufzurufen.

Verwenden Sie einen Antwortendpunkt, wenn der Befehl eine Bestätigung auf Anwendungsebene zurückgeben soll.

Wählen Sie den richtigen Konnektivitätstyp für Ihre Digital Twin Instance

So entscheiden Sie, welcher Konnektivitätstyp für eine digitale Zwillingsinstanz verwendet werden soll:

Direkt vernetzt

Verwenden wenn: Das Gerät stellt eine eigene Verbindung zur IoT-Domain her.
Erforderlicher Parameter: Authentifizierungs-ID. Verwenden Sie zum Testen ein Secret, und verwenden Sie für die Produktion das mTLS-Zertifikat.
Erforderlich für strukturierte Daten: Ein digitaler Zwillingsadapter, der mit dem digitalen Zwillingsmodell übereinstimmt, kann bereitgestellt oder vom Adapter abgeleitet werden. Das Modell muss mindestens eine Telemetrie, Eigenschaft oder einen Befehl enthalten.
Für unstrukturierte Daten: Verwenden Sie keinen digitalen Doppeladapter oder ein digitales Zwillingsmodell.
Optionale Eingabe: Externer Schlüssel. Wenn Sie keinen externen Schlüssel angeben, generiert der Service einen Schlüssel. Für den Gerätenamen verwenden.
Nicht verwenden: Gatewayverknüpfung mit einem direkt verbundenen Gerät.

Gateway

Verwenden wenn: Ein Gerät leitet Daten und Befehle für sich und für andere Geräte weiter.
Erforderliche Parameter: Authentifizierungs-ID und Gatewayadapter. Gatewayinstanzen unterstützen keine unstrukturierte Telemetrie, daher ist der Adapter erforderlich.
Digitales Zwillingsmodell: Das digitale Zwillingsmodell des Gateways kann dem digitalen Zwillingsadapter zugeordnet oder abgeleitet werden, und das Modell muss mindestens eine Telemetrie, Eigenschaft oder einen Befehl enthalten. Sie können eine digitale Zwillingsinstanz mit einem Adapter erstellen, ohne das Modell anzugeben. Ein Modell wird über den Adapter verknüpft.; Für unstrukturierte Daten verwenden Sie in der Regel weder einen Adapter noch ein Modell.
Optionale Eingabe: Externer Schlüssel, wenn Sie keinen angeben, generiert der Service einen Schlüssel.
Empfohlen: Prüfen Sie vor dem Ändern oder Löschen auf der Seite Gatewaydetails, wie viele Geräte vom Gateway abhängig sind.
Nicht: Verknüpfen Sie eine Gatewayinstanz mit einer anderen Gatewayinstanz.

Indirekt verbunden

Verwenden wenn: Ein anderes Gerät, in der Regel ein Gateway, sendet Telemetriedaten und empfängt Befehle im Namen des Geräts.
Erforderlich: Mindestens eine Gatewayverknüpfung ist erforderlich. Verwenden Sie mehr als ein Gateway, wenn ein drahtloses Gerät zwischen Gateways unterwegs sein könnte. Wenden Sie sich an einen Administrator, wenn dies in Ihrer Umgebung funktioniert.
Für strukturierte Daten: Für strukturierte Daten ist ein digitaler Zwillingsadapter erforderlich. Das entsprechende digitale Zwillingsmodell kann durch Angabe des DTMI oder der digitalen Zwillingsmodell-OCID bereitgestellt oder aus dem Adapter abgeleitet werden, wobei das Modell mindestens eine Telemetrie, Eigenschaft oder einen Befehl enthalten muss.
Für unstrukturierte Daten: Verwenden Sie für unstrukturierte Daten keinen digitalen Zwillingsadapter oder ein digitales Zwillingsmodell. Sie können keine Inhalte für unstrukturierte Daten abrufen, da sie kein digitales Zwillingsmodell enthalten.
Optionale Eingabe: Externer Schlüssel. Wenn Sie keinen externen Schlüssel angeben, generiert der Service einen Schlüssel.
Authentifizierungs-ID: Verwenden Sie keine Authentifizierungs-ID für eine indirekt verbundene digitale Zwillingsinstanz.

Nicht angemeldet

Verwenden wenn: Testen einer digitalen Zwillingsinstanz, die Gerätedaten nicht authentifiziert, sendet oder empfängt, sodass Sie digitale Zwillingsbeziehungen testen können, um Ihre IoT-Konfiguration ohne die Komplexität von Daten oder Authentifizierung zu testen.
Erforderlich: Für strukturierte Daten ist ein digitales Zwillingsmodell erforderlich, das keine Telemetrie, Eigenschaften oder Befehle enthalten darf.
Optional: Digitale Zwillingsbeziehungen zum Testen. Weitere Informationen finden Sie unter Digitale Zwillingsbeziehungen.
Nicht verwenden: Authentifizierungs-ID, externer Schlüssel, digitaler Zwillingsadapter, Gatewayverknüpfung oder Gerätedaten auf nicht verbundenen digitalen Zwillingsinstanzen.

Häufig gestellte Fragen (FAQ)

In dieser FAQ werden die in diesem Szenario beschriebenen Gateway-Benutzerberichte beschrieben.

Kann ich eine digitale Zwillingsinstanz so konfigurieren, dass sie indirekt verbunden ist, damit ein anderes Gerät Daten in seinem Namen sendet?

Ja. Erstellen Sie die digitale Zwillingsinstanz für das Gerät mit dem Konnektivitätstyp INDIRECT, und verknüpfen Sie sie mit mindestens einer digitalen Zwillingsinstanz des Gateways, anstatt dem Gerät eine eigene Authentifizierungs-ID zu geben.

Wie kann ich feststellen, welche Geräte über ein bestimmtes Gateway verbunden sind, und welche Auswirkungen der Verlust dieses Gateways hat?

Auf der Seite "Gatewaydetails" können Sie die Anzahl der zugehörigen Geräte und die Liste der abhängigen digitalen Zwillingsinstanzen prüfen. Dadurch erhalten Sie die schnellste Ansicht des Explosionsradius des Gateways vor Wartungs-, Migrations- oder Löschvorgängen.

Woher weiß ich, wie viele meiner digitalen Zwillingsinstanzen direkt verbunden, indirekt verbunden oder Gateways sind?

Auf der Listenseite der digitalen Zwillingsinstanz oder der Gatewaylistenseite finden Sie die Liste der Gateways.

Prüfen Sie den Konnektivitätstyp der digitalen Zwillingsinstanz für jeden digitalen Zwilling, und verwenden Sie ein Gateway auf Domänenebene und Topologieansichten, um Einblicke in Ihre Umgebung zu erhalten. In diesem Szenario wird ein direktes Gerät, ein Gateway und mehrere indirekte Geräte angezeigt, sodass Sie die drei Muster vergleichen können.

Wie kann ich einen Adapter für mein Gateway so konfigurieren, dass eingehende Telemetrie an das richtige Zielgerät weitergeleitet wird?

Verwenden Sie einen digitalen Zwillingsadapter für das Gateway, der ein target-Mapping im Envelope enthält. Siehe Schritt 2: Digitale Zwillingsadapter erstellen.

Wann sollte ich target in die eingehenden Routen anstatt in den eingehenden Envelope einfügen?

Nein. Geben Sie target in den eingehenden Umschlag ein.

Was geschieht, wenn target leer oder Null ist?

Die Nachricht wird als Gateway-Daten behandelt, anstatt an ein indirekt verbundenes Gerät delegiert zu werden.

Kann ein Gateway-Adapter sowohl die Gateway-Telemetrie als auch die indirekt verbundene Gerätetelemetrie verarbeiten?

Ja. Das ist der Hauptzweck des Gateway-Routings. Weitergeleitete Gerätenachrichten werden an ein aufgelöstes Ziel weitergeleitet, während nicht zugeordnete oder leere Zieldaten beim Gateway bleiben.

Kann ich ein Gateway über direkt verbundene und indirekt verbundene Geräte wiederverwenden, ohne meine Definitionen zu duplizieren?

Ja. Behandeln Sie das Gateway als wiederverwendbares Asset, erstellen Sie die entsprechenden Adapter einmal, und verknüpfen Sie das Gateway dann mit jedem indirekt verbundenen Gerät, das diese Adapterroutenbedingung verwenden soll.

Kann ich unstrukturierte Telemetrie von indirekt verbundenen Geräten senden?

Ja. Wenn Sie keine strukturierte Payload-Zuordnung für das Zielgerät benötigen, können Sie die Raw Payload über das Gateway senden und den gerätespezifischen Adapter überspringen.

Kann ich unstrukturierte Befehle auf indirekt verbundenen Geräten und auf dem Gateway selbst aufrufen?

Ja. Verwenden Sie Raw-Befehlsendpunkte für beide Muster. Fügen Sie dem unstrukturierten Befehl einen Antwortendpunkt hinzu, wenn das Gateway eine Bestätigung auf Anwendungsebene für das Zielgerät veröffentlichen muss.

--request-endpoint, Beispiel: boilers/boiler1/actions/reset

--response-endpoint, Beispiel: boilers/boiler1/actions/response

Kann ich ein Gerät mit mehreren Gateways verknüpfen, damit es roam kann?

Ja. Ein indirekt verbundenes Gerät kann einem oder mehreren Gateways zugeordnet sein. Dadurch kann ein drahtloses Gerät dieselbe digitale Zwillingsinstanz beibehalten, während es zwischen verfügbaren Gateways wechselt.

In der CLI können Sie Multi-Gateway-Roaming konfigurieren, indem Sie ein Array für die Gatewayverknüpfung des Modells des digitalen Zwillings verwenden.

Verwenden Sie die Option --gateways mit einem JSON-Array von OCIDs für digitale Zwillingsinstanzen des Gateways:

oci iot digital-twin-instance create \
  --iot-domain-id <iot-domain-OCID> \
  --connectivity-type INDIRECT \
  --display-name "Roaming Wireless Device 1" \
  --gateways '["<gateway-instance-1-OCID>","<gateway-instance-2-OCID>"]' \
  --external-key roaming-device1

Wenn Sie Probleme mit Shell-Angeboten vermeiden möchten, fügen Sie die Gatewayliste in eine roaming-device.json-Eingabedatei ein, und verwenden Sie --from-json:

oci iot digital-twin-instance create \
  --from-json file://roaming-device.json

roaming-device.json

{
  "iotDomainId": "<iot-domain-OCID>",
  "connectivityType": "INDIRECT",
  "displayName": "Roaming Wireless Device 1",
  "gateways": [
    "<gateway-instance-1-OCID>",
    "<gateway-instance-2-OCID>"
  ],
  "externalKey": "roaming-device1"
}

Bevor Sie sich in der Produktion auf das Multi-Gateway-Roaming verlassen, bestätigen Sie das Verhalten in Ihrer Testumgebung und validieren Sie das Übergabemuster, das Ihre Gateways verwenden.

Fehlerbehebung

Befehl bleibt im Status "Akzeptiert"

Wenn Sie in Schritt 6: Befehle aufrufen den Parameter --request-data nicht aufnehmen, bleibt der Befehl im Status ACCEPTED und führt zu einem Fehler: Invalid Command Invocation id [unique-id]: [Previous command invocation is not finished yet]

Nächste Schritte

Löschen Sie die Ressourcen, die zum Erstellen dieses Szenarios verwendet werden:

Oracle Cloud Infrastructure-Dokumentation