Szenario: Strukturierte Daten mit HTTPs in einem benutzerdefinierten Format senden

1. Definieren Sie einen eingehenden Envelope file://inbound-envelope.json, um anzugeben, wie Metadaten aus der Payload des Geräts extrahiert werden sollen. So extrahieren Sie den Wert unter $.time aus der eingehenden JSON, und ordnen Sie ihn dem Feld timeObserved im digitalen Zwillingsmodell zu. Mit diesen Mappings können Sie bestimmte Metadaten wie Zeitstempel mit JQ-Ausdrücken extrahieren.

   Dieses Beispiel zeigt den Geräteendpunkt, eine Beispiel-Payload und eine eingehende Envelope-Zuordnung, die JQ-Ausdrücke zum Extrahieren oder Umformen der Daten anwendet.

   {
     "reference-endpoint": "telemetry/health",
     "reference-payload": {
       "dataFormat": "JSON",
       "data": {
         "time": "<timestamp>",
         "data": {
           "temp": 0,
           "hum": 0,
           "power": false,
           "batteryLevel": 0
         }
       }
     },
     "envelope-mapping": {
       "timeObserved": "$.time"
     }
   }

2. Erstellen Sie eine file://inbound-routes.json-Datei, um zu definieren, wie bestimmte Payload-Daten aus Gerätenachrichten zugeordnet und an die Instanz des digitalen Zwillings weitergeleitet werden.

   Jede Route enthält eine Bedingung, die mit dem Endpunkt übereinstimmt, eine Referenz-Payload-Struktur und Zuordnungsanweisungen zum Übertragen oder Transformieren von Werten.

   Dieses Beispiel zeigt 2 definierte Payload-Bedingungen.
   Hinweis
   
   Die maximal zulässige Anzahl an eingehenden Routen beträgt 128.

   [
     {
       "condition": "${endpoint(2) == \"heartbeat\"}",
       "reference-payload": {
         "data": {
           "temp": 75,
           "hum": 62
         }
       },
       "payload-mapping": {
         "$.temperature": "$.data.temp",
         "$.humidity": "${.data.hum - 5}"
       }
     },
     {
       "condition": "${endpoint(2) == \"health\"}",
       "reference-payload": {
         "data": {
           "power": false,
           "batteryLevel": 60
         }
       },
       "payload-mapping": {
         "$.power": "$.data.power",
         "$.batteryLevel": "${.data.batteryLevel - 5}"
       }
     }
   ]

3. Verwenden Sie den Befehl oci iot digital-twin-adapter create, um einen digitalen Zwillingsadapter zu erstellen. Ersetzen Sie <iot-domain-OCID> durch die OCID für die IoT-Domain, und ersetzen Sie <dtmi:com:oracle:example:hvac> durch die DTMI-URI durch die DTMI-URI für das digitale Zwillingsmodell, das Sie mit diesem digitalen Zwillingsadapter verknüpfen möchten.

   Im folgenden Beispiel wird der DTMI-URI-Parameter verwendet, um das digitale Zwillingsmodell zu verknüpfen. Alternativ können Sie den Parameter --digital-twin-model-id mit der <digital-twin-model-OCID> für das digitale Zwillingsmodell verwenden, das Sie diesem digitalen Zwillingsadapter zuordnen möchten.

   Referenzieren Sie die Dateien file://inbound-enevelop.json und file://inbound-enevelop.json, die im vorherigen Schritt erstellt wurden.

   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://inbound-enevelop.json> --inbound-routes <file://inbound-routes.json>

   Diese Beispielantwort zeigt eine benutzerdefinierte Payload-Zuordnung, die in den Optionen --inbound-envelope und --inbound-routes definiert ist, indem sie json-Dateien referenziert, sowie eine bestimmte OCID des digitalen Zwillingsadapters, die mit einem bestimmten digitalen Zwillingsmodell mit einer eindeutigen DTMI-URI und einer eindeutigen Modell-OCID des digitalen Zwillings verknüpft ist:

   dtmi:com:oracle:example:core:hvac:sp;1

   {
     "data": {
       "defined-tags": {
         "Oracle-Tags": {
           "CreatedBy": "default/user@oracle.com",
           "CreatedOn": "2025-09-11T06:09:27.323Z"
         }
       },
       "description": null,
       "digital-twin-model-id": "<iot-digital-twin-model-OCID>",
       "digital-twin-model-spec-uri": "dtmi:com:oracle:example:hvac;1",
       "display-name": "<digital-twin-adapter-display-name>",
       "freeform-tags": {},
       "id": "<iot-digital-twin-adapter-OCID>",
       "inbound-envelope": {
         "envelope-mapping": {
           "time-observed": "$.time"
         },
         "reference-endpoint": "telemetry/health",
         "reference-payload": {
           "data": {
             "time": "2025-09-11T06:09:27.878106Z"
           },
           "data-format": "JSON"
         }
       },
       "inbound-routes": [
         {
           "condition": "${endpoint(2) == \"heartbeat\"}",
           "description": null,
           "payload-mapping": {
             "$.humidity": "${.hum-1}",
             "$.temperature": "$.temp"
           },
           "reference-payload": {
             "data": {
               "hum": 62,
               "temp": 75
             },
             "data-format": "JSON"
           }
         },
         {
           "condition": "${endpoint(2) == \"health\"}",
           "description": null,
           "payload-mapping": {},
           "reference-payload": {
             "data": {
               "batteryPercentage": 60,
               "on": false
             },
             "data-format": "JSON"
           }
         }
       ],
       "iot-domain-id": "<iot-domain-OCID>",
       "lifecycle-state": "ACTIVE",
       "system-tags": {},
       "time-created": "2025-09-30T19:55:36.293000+00:00",
       "time-updated": "2025-09-30T19:55:36.293000+00:00"
     },
     "etag": "<unique-id>"
   }
   

Verwenden Sie die Parameter oci iot digital-twin-instance create, <iot-domain-OCID> und <certificate-or-secret-OCID>, um eine digitale Zwillingsinstanz zu erstellen. Ersetzen Sie <certificate-or-secret-OCID> durch die gewünschte Vault-Secret-OCID, und ersetzen Sie <iot-domain-OCID> durch die OCID für die IoT-Domain für Ihre Umgebung.

Wenn die digitale Zwillingsinstanz für den Empfang von Gerätedaten eingerichtet ist, müssen Sie den Parameter für die Authentifizierungs-ID mit einem Vault Secret oder einer Zertifikats-OCID verwenden, damit sich der digitale Zwilling authentifizieren kann. Dazu erstellen Sie ein Secret oder erstellen Sie ein Zertifikat in derselben Region und demselben Mandanten wie alle anderen zugehörigen IoT-Ressourcen.

In diesem Beispiel wird die Option --display-name verwendet. Ersetzen Sie <your-digital-twin-instance-name> durch einen benutzerfreundlichen Namen für die Instanz des digitalen Zwillings.

oci iot digital-twin-instance create --iot-domain-id <iot-domain-OCID> --display-name <your-digital-twin-instance-name> --auth-id <certificate-or-secret-OCID> --digital-twin-adapter-id <digital-twin-adapter-OCID>

dtmi:com:oracle:example:hvac;1

{
  "data": {
    "auth-id": "<vault-secret-OCID>",
    "defined-tags": {
      "Oracle-Tags": {
        "CreatedBy": "default/user@oracle.com",
        "CreatedOn": "2025-08-14T17:41:11.973Z"
      }
    },
    "description": null,
    "digital-twin-adapter-id": "<iot-digital-twin-adapter-OCID>",
    "digital-twin-model-id": "<digital-twin-model-OCID>",
    "digital-twin-model-spec-uri": "dtmi:com:oracle:example:hvac;1",
    "display-name": "<your-digital-twin-instance-name>",
    "external-key": "<digital-twin-instance-external-key>",
    "freeform-tags": {},
    "id": "<digital-twin-instance-OCID>",
    "iot-domain-id": "<iot-domain-OCID>",
    "lifecycle-state": "ACTIVE",
    "system-tags": {},
    "time-created": "2025-08-14T17:41:13.638000+00:00",
    "time-updated": "2025-08-14T17:41:13.638000+00:00"
  },
  "etag": "<unique-id>"
}

In diesem Beispiel werden HTTPs verwendet. Alternativ können Sie MQTT und MQTT über WebSockets verwenden. Spezielle Beispiele finden Sie unter Szenarios.

curl -H "Authorization: Bearer <token>" \
     -X GET "https://<domain-group-short-id>.data.iot.<region>.oci.oraclecloud.com/ords/<domain-short-id>/20250531/rawData?q={\"$and\":[{\"digital_twin_instance_id\":\"<iot-digital-twin-OCID>\"}]}"

select * from <domain-short-id-from-device-host>__IOT.RAW_DATA where digital_twin_instance_id = '<iot-digital-twin-OCID>';

Oder verwenden Sie diese SQL-Anweisung, um die Telemetriedaten rejected anzuzeigen. Ersetzen Sie <domain-short-id-from-device-host> durch die Domainkurz-ID für Ihre IoT-Domain und <iot-digital-twin-OCID> durch die OCID des digitalen Zwillings, von der Sie abgelehnte Daten anzeigen möchten:

select * from <domain-short-id-from-device-host>__IOT.REJECTED_DATA where digital_twin_instance_id = '<iot-digital-twin-OCID>';

select * from <domain-short-id>__IOT.DIGITAL_TWIN_HISTORIZED_DATA where digital_twin_id = '<digital-twin-OCID>';