Oracle Cloud Infrastructure-Dokumentation

Szenario: Senden strukturierter Daten in einem Standardformat mit MQTTs

In diesem Szenario erfahren Sie, wie Sie ein digitales Zwillingsmodell erstellen, um historisierte Telemetriedaten von einem Pulsoximeter mit MQTTs zu empfangen und IoT-Daten in APEX anzuzeigen.

  1. DTDL-Spezifikationen für ein digitales Zwillingsmodell erstellen
  2. Erstellen eines digitalen Zwillingsmodells für ein Pulsoximeter
  3. Standard-Digital-Twin-Adapter erstellen
  4. Digitale Zwillingsinstanz erstellen
  5. Daten mit MQTTX veröffentlichen
  6. IoT-Daten in APEX anzeigen
  7. Nachrichten mit MQTTX veröffentlichen
  8. IoT Snapshot-Daten in APEX abfragen

Schritt 1: Erstellen von DTDL-Spezifikationen für ein digitales Zwillingsmodell

Definieren Sie eine digitale Zwillingsmodellspezifikation, bei der nur das Pulsoximeter als historisiert markiert ist.

Speichern Sie diese als Textdatei, um sie im nächsten Schritt zu referenzieren und das digitale Zwillingsmodell basierend auf diesen Spezifikationen zu erstellen.

basierend auf den DTDL v3-Spezifikationen.

{
  "@context": [
    "dtmi:dtdl:context;3",
    "dtmi:dtdl:extension:historization;1"
  ],
  "@id": "dtmi:com:oracle:example:health:po;1",
  "@type": "Interface",
  "displayName": "Pulse Oximeter",
  "description": "This is digital twin model for pulse oximeter",
  "contents": [
    {
      "name": "pulse",
      "displayName": "Heart Rate",
      "@type": [
        "Telemetry",
        "Historized"
      ],
      "schema": "integer"
    },
    {
      "name": "so2",
      "displayName": "Oxygen Saturation",
      "@type": "Telemetry",
      "schema": "integer"
    }
  ]
}

Schritt 2: Erstellen eines digitalen Zwillingsmodells für ein Pulsoximeter

Erstellen Sie ein digitales Zwillingsmodell für ein Pulsoximeter und ersetzen Sie <path-to-definition-file> durch den Speicherort der Datei, in der die Spezifikationen des digitalen Pulsoximeters aus dem vorherigen Schritt definiert sind.

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

oci iot digital-twin-model create --iot-domain-id <iot-domain-OCID> --spec <path-to-definition-file>

Beispielantwort:

{
  "data": {
    "defined-tags": {
      "Oracle-Tags": {
        "CreatedBy": "default/user@oracle.com",
        "CreatedOn": "2025-08-17T14:23:03.379Z"
      }
    },
    "description": "This is digital twin model for pulse oximeter",
    "display-name": "Pulse Oximeter",
    "freeform-tags": {},
    "id": "<digital-twin-OCID>",
    "iot-domain-id": "<iot-domain-OCID>",
    "lifecycle-state": "ACTIVE",
    "spec-uri": "dtmi:com:oracle:example:health:po;1",
    "system-tags": {},
    "time-created": "2025-08-17T14:23:03.449000+00:00",
    "time-updated": "2025-08-17T14:23:03.449000+00:00"
  },
  "etag": "<unique-id>"
}

Schritt 3: Erstellen eines Standard-Digital Twin-Adapters

Verwenden Sie den Befehl oci iot digital-twin-adapter create, um einen standardmäßigen digitalen Zwillingsadapter für das digitale Zwillingsmodell des Pulsoximeters zu erstellen. In diesem Beispiel wird gezeigt, wie Sie einen Standardadapter für digitale Zwillinge erstellen, der nicht ohne Angabe von inbound-envelope oder envelope-mapping angegeben wird. Infolgedessen werden die Daten im Standardformat des Geräts gesendet.

Wenn die Envelope-Zuordnung nicht angegeben ist und einen timeObserved-Wert enthält, wird receivedTime als timeObserved-Wert verwendet. 

oci iot digital-twin-adapter create --iot-domain-id <iot-domain-OCID> --digital-twin-model-spec-uri "dtmi:com:oracle:example:health:po;1" --display-name "<your-pulse-oximeter-name>" --description "<this-is-digital-twin-adapter-for-pulse-oximeter>"
Beispielantwort, die die Werte für die Payload des Geräts und die zugehörige IoT-Domain, das digitale Zwillingsmodell, den digitalen Zwillingsadapter und den DTMI-URI anzeigt.
{
  "data": {
    "defined-tags": {
      "Oracle-Tags": {
        "CreatedBy": "default/user@oracle.com",
        "CreatedOn": "2025-08-17T14:25:51.190Z"
      }
    },
    "description": "<this-is-digital-twin-adapter-for-pulse-oximeter>"
    "digital-twin-model-id": "<iot-digital-twin-model-OCID>",
    "digital-twin-model-spec-uri": "dtmi:com:oracle:example:health:po;1",
    "display-name": "Pulse Oximeter",
    "freeform-tags": {},
    "id": "<iot-digital-twin-adapter-OCID>",
    "inbound-envelope": {
      "envelope-mapping": {
        "time-observed": "$.time"
      },
      "reference-endpoint": "/",
      "reference-payload": {
        "data": {
          "pulse": 0,
          "so2": 0,
          "time": "2025-08-17T14:25:52.184012284Z"
        },
        "data-format": "JSON"
      }
    },
    "inbound-routes": [
      {
        "condition": "*",
        "description": "Default condition",
        "payload-mapping": {
          "$.pulse": "$.pulse",
          "$.so2": "$.so2"
        },
        "reference-payload": null
      }
    ],
    "iot-domain-id": "<iot-domain-OCID>",
    "lifecycle-state": "ACTIVE",
    "system-tags": {},
    "time-created": "2025-08-17T14:25:52.186000+00:00",
    "time-updated": "2025-08-17T14:25:52.186000+00:00"
  },
  "etag": "<unique-id>"
}

Schritt 4: Digitale Zwillingsinstanz erstellen

Verwenden Sie diesen Befehl oci iot digital-twin-instance create, um eine digitale Zwillingsinstanz zu erstellen.

Ersetzen Sie <iot-domain-OCID> und <iot-digital-twin-adapter-OCID>, um diese Instanz des digitalen Zwillings mit den zugehörigen IoT-Ressourcen zu verknüpfen, die in den vorherigen Schritten erstellt wurden.

Ersetzen Sie <vault-secret-OCID> durch ein Vault Secret, das in derselben Region wie die digitale Zwillingsinstanz erstellt wurde. Weitere Informationen finden Sie unter Secret erstellen. 

oci iot digital-twin-instance create --iot-domain-id <iot-domain-OCID> --digital-twin-adapter-id <iot-digital-twin-adapter-OCID> --auth-id <vault-secret-OCID> --display-name "<Pulse Oximeter 1>"
Diese Beispielantwort zeigt die digitale Zwillingsinstanz mit dem zugehörigen digitalen Zwillingsadapter, dem digitalen Zwillingsmodell, einschließlich des DTMI-URI.
{
  "data": {
    "auth-id": "<vault-secret-OCID>",
    "defined-tags": {
      "Oracle-Tags": {
        "CreatedBy": "default/user@oracle.com",
        "CreatedOn": "2025-08-17T14:39:44.292Z"
      }
    },
    "description": null,
    "digital-twin-adapter-id": "<iot-digital-twin-adapter-OCID>",
    "digital-twin-model-id": "<iot-digital-twin-model-OCID>",
    "digital-twin-model-spec-uri": "dtmi:com:oracle:example:health:po;1",
    "display-name": "Pulse Oximeter 1",
    "external-key": "<unique-id>",
    "freeform-tags": {},
    "id": "<iot-digital-twin-instance-OCID>",
    "iot-domain-id": "<iot-domain-OCID>",
    "lifecycle-state": "ACTIVE",
    "system-tags": {},
    "time-created": "2025-08-17T14:39:45.238000+00:00",
    "time-updated": "2025-08-17T14:39:45.238000+00:00"
  },
  "etag": "<unique-id>"
}

Schritt 5: Daten mit MQTTX veröffentlichen

  1. Installieren Sie MQTTX.
    https://mqttx.app/docs/cli/downloading-and-installation
  2. Konfigurieren Sie MQTTX.

    Ersetzen Sie <device-host-from-iot-domain>.

    Ersetzen Sie <external-key> durch die Antwort der digitalen Zwillingsinstanz.

    mqttx init
? Select MQTTX CLI output mode Text
? Select the default MQTT protocol MQTTS
? Enter the default MQTT broker host <device-host-from-iot-domain>
? Enter the default MQTT port 8883
? Enter the maximum reconnect times for MQTT connection 10
? Enter the default username for MQTT connection authentication <external-key>
? Enter the default password for MQTT connection authentication <auth-id-secret-value>
Configuration file created/updated at /Users/<user-name>/.mqttx-cli/config
  3. Verbindung validieren.
    mqttx conn -h <data-host> -u <external-key> -P '<vault-secret-value>'
  4. Die Beispieldaten veröffentlichen
    Hinweis

    -u und -P sind nur erforderlich, wenn diese als Standard in mqtt init festgelegt sind.

Schritt 6: IoT-Daten in APEX anzeigen

Wenn Sie Ihre IoT-Daten in APEX anzeigen möchten, müssen Sie die Verbindung zu APEX konfigurieren.

Nachdem die Konfiguration eingerichtet wurde, können Sie das IoT-Datenbankschema in APEX wie folgt anzeigen:

  1. Gehen Sie zur APEX-URL mit der Domaingruppen-Kurz-ID vom Datenhost: 
    https://<domain-group-short-id-from-data-host>.data.iot.<region>.oci.oraclecloud.com/ords/r/apex
  2. Melden Sie sich mit der Domain-Kurz-ID, die vom Gerätehost stammt, bei APEX an: 
    device-host:<domain-short-id-from-device-host>.device.iot.<region>.oci.oraclecloud.com
    Melden Sie sich unter APEX an:

  3. Gehen Sie zu SQL Workshop. Verwenden Sie SQL-Befehle, um Ihre IoT-Daten abzufragen. 

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

    
DIGITAL_TWIN_INSTANCE_ID	        CONTENT_PATH	VALUE	TIME_OBSERVED
<iot-digital-twin-instance-OCID>	so2	           95	  17-AUG-25 03.15.56.000205 PM
<iot-digital-twin-instance-OCID>	pulse	        75	  17-AUG-25 03.15.56.000205 PM

    select * from <iot-domain-short-id-from-device-host>__IOT.HISTORIZED_DATA where digital_twin_instance_id='ocid1.iotdigitaltwininstance.oc1.<region>.<unique-id>';

    
ID	DIGITAL_TWIN_INSTANCE_ID	        CONTENT_PATH	VALUE	TIME_OBSERVED
87	<iot-digital-twin-instance-OCID>	pulse	        75	  17-AUG-25 03.15.56.000205 PM

Schritt 7: Nachrichten mit MQTTX veröffentlichen

Erneut veröffentlichen, um die Verbindung und Veröffentlichung der Nachricht zu bestätigen.

Wenn Sie die Instanz des digitalen Zwillings im vorherigen Schritt erstellt haben und das Vault Secret als Authentifizierungs-ID angegeben haben, können Sie den Inhalt dieses Secrets abrufen, das in einem OCI-Vault gespeichert ist, und <vault-secret-content> durch den Inhalt des Secrets ersetzen.

mqttx pub -t "/data" -m '{ "pulse": 76, "so2": 94}' -u <external-key> -P '<vault-secret-content>'

Schritt 8: Snapshot-Daten in APEX abfragen IoT

  1. Verwenden Sie diese Anweisung in APEX zum Abfragen der Snapshot-Daten. Beachten Sie die beiden Unterstriche im Schemanamen.
    select * from <iot-domain-short-id-from-device-host>__IOT.SNAPSHOT_DATA where digital_twin_instance_id='<iot-digital-twin-instance-ocid>';
  2. Zeigen Sie die letzten bekannten Werte an, die für jede digitale Zwillingsinstanz aktualisiert wurden. 
    DIGITAL_TWIN_INSTANCE_ID	CONTENT_PATH	VALUE	TIME_OBSERVED
ocid1.iotdigitaltwininstance.oc1.<region>.<unique-id>	so2	  94	17-AUG-25 03.22.34.000753 PM
ocid1.iotdigitaltwininstance.oc1.<region>.<unique-id>	pulse	76	17-AUG-25 03.22.34.000753 PM
  3. Verwenden Sie in APEX diese Anweisungsabfrage mit historisierten Daten.
    select * from <iot-domain-short-id-from-device-host>__IOT.HISTORIZED_DATA where digital_twin_instance_id='<iot-digital-twin-instance-OCID>';
  4. Beobachten Sie nur das Pulsoximeter zeigt Zeitreihen historisierte Daten, da nur das Pulsoximeter markiert als historisiert im digitalen Zwillingsmodell aus dem vorherigen Schritt.
    
ID	DIGITAL_TWIN_INSTANCE_ID              CONTENT_PATH	VALUE	TIME_OBSERVED
87	<iot-digital-twin-instance-OCID>	pulse	       75	   17-AUG-25 03.15.56.000205 PM
88	<iot-digital-twin-instance-OCID>	pulse	       76	   17-AUG-25 03.22.34.000753 PM

Schritt 9: Verwenden des SDK

Prüfen Sie diese erweiterte Simulation von Daten, die Sie als JavaScript-Datei im Internet of Things-SDK verwenden können.
/**
 * MQTTX Scenario file example
 *
 * This script generates random pulse and so2 to simulate pulse oximeter.
 */
function generator(faker, options) {
  return {
    // If no topic is returned, use the topic in the command line parameters.
    // Topic format: 'mqttx/simulate/myScenario/' + clientId,
    message: JSON.stringify({
      pulse: faker.number.int({ min: 60, max: 120 }), // Generate a random pulse between 60 and 120.
      so2: faker.number.int({ min: 90, max: 100 }), // Generate a random so2 between 90 and 100.
    })
  }
}
// Export the scenario module
module.exports = {
  name: 'Pulse Oximeter Scenario', // Name of the scenario
  generator, // Generator function
}
Beispiel für die Verwendung des Befehls mqttx simulate und die Referenzierung der Datei.
mqttx simulate --file <path-to-above-script-file>  -u <external-key> -P '<vault-secret-content>'
❯  Starting publish simulation, scenario: Pulse Oximeter Scenario, connections: 1, req interval: 10ms, message interval: 1000ms
✔  [1/1] - Connected
✔  Created 1 connections in 1.198s
Published total: 10, message rate: 1/s
^C after 10 (or how much every you want)

Schritt 10: IoT-Daten in APEX abfragen

  1. In APEX können Sie jetzt die Snapshot-Daten für das Pulsoximeter abfragen. 
    select * from <iot-domain-short-id>__IOT.SNAPSHOT_DATA where digital_twin_instance_id  = 'ocid1.iotdigitaltwininstance.oc1.<region>.<unique-id>';

    ocid1.iotdigitaltwininstance.oc1.<region>.<unique-id>	so2	90	17-AUG-25 03.29.19.000429 PM
ocid1.iotdigitaltwininstance.oc1.<region>.<unique-id>	       pulse	90	17-AUG-25 03.29.19.000429 PM
  2. Historisierte Daten abfragen
    select * from <iot-domain-short-id>__IOT.HISTORIZED_DATA where digital_twin_instance_id  = 'ocid1.iotdigitaltwininstance.oc1.<region>.<unique-id>';
  3. Beobachten Sie die Zeitreihendaten für das Pulsoximeter.
    
ID	DIGITAL_TWIN_INSTANCE_ID	        CONTENT_PATH	VALUE	TIME_OBSERVED
94	<iot-digital-twin-instance-OCID>	pulse	       81	 17-AUG-25 03.29.15.000424 PM
96	<iot-digital-twin-instance-OCID>	pulse	       116	17-AUG-25 03.29.17.000430 PM
92	<iot-digital-twin-instance-OCID>	pulse	       105	17-AUG-25 03.29.13.000416 PM
89	<iot-digital-twin-instance-OCID>	pulse	       87	 17-AUG-25 03.29.10.000409 PM
97	<iot-digital-twin-instance-OCID>	pulse	       112	17-AUG-25 03.29.18.000429 PM
91	<iot-digital-twin-instance-OCID>	pulse	       73	 17-AUG-25 03.29.12.000411 PM
93	<iot-digital-twin-instance-OCID>	pulse	       70	 17-AUG-25 03.29.14.000413 PM
87	<iot-digital-twin-instance-OCID>	pulse	       75	 17-AUG-25 03.15.56.000205 PM
88	<iot-digital-twin-instance-OCID>	pulse	       76	 17-AUG-25 03.22.34.000753 PM
90	<iot-digital-twin-instance-OCID>	pulse	       74	 17-AUG-25 03.29.11.000409 PM