Oracle Cloud Infrastructure-Dokumentation

Szenario: Digitale Zwillingsbeziehung abfragen

Eine digitale Zwillingsinstanz kann digitale Zwillingsmodelle, digitale Zwillingsadapter, Hierarchien und Beziehungen verwenden, um ein virtuelles Modell zu erstellen, das eine echte Umgebung darstellt.

In diesem Szenario wird erläutert, wie Sie eine digitale Zwillingsbeziehung abfragen können, um Fragen zu einem Gerät, Funktionen, Daten und Konnektivität zu beantworten und einen physischen Raum und seine Geräte zu überwachen. In diesem Szenario ist ein Raum ein physischer Bereich, beispielsweise ein Konferenzraum. Dazu dient ein Env-III-Sensor, ein Gerät im Raum, das Umwelteigenschaften einschließlich Temperatur und Feuchtigkeit misst. Mit dieser Hierarchie und der Beziehung servedBy können Anwendungen Folgendes abfragen:
  • Welche Sensoren dienen einem bestimmten Raum?
  • Welche Telemetrie wird von diesen Sensoren gemeldet?
  • Wie werden die Geräte mit Wi-Fi verbunden?

Aufgaben

  1. Erstellen eines digitalen Zwillingsmodells mit einem Funktionsbasismodell
  2. Erstellen eines digitalen Twin-Modells für einen Sensor
  3. Erstellen eines digitalen Zwillingsmodells für den Env-III-Sensor
  4. Erstellen eines digitalen Zwillingsmodells für den Weltraum
  5. Erstellen Sie einen digitalen Twin Adapter für den Weltraum
  6. Digital Twin Adapter für den Env-III Sensor erstellen
  7. Erstellen einer digitalen Zwillingsinstanz mit einem Adapter für einen Arbeitsplatz
  8. Erstellen einer digitalen Zwillingsinstanz mit Adapter für einen Env-III-Sensor
  9. Erstellen einer digitalen Zwillingsbeziehung zum Verbinden der digitalen Zwillingsinstanzen
  10. Digital Twin Relationship Graph mit SQL abfragen

Schritt 1: Erstellen eines digitalen Zwillingsmodells mit einem Funktionsbasismodell

  1. Speichern Sie dieses Code-Snippet als model_capability.json-Datei. Referenzieren Sie diese Datei im nächsten Schritt, wenn Sie ein digitales Zwillingsmodell erstellen. Diese Modellspezifikation definiert die Fähigkeit und fungiert als Basismodell.

    Weitere Informationen zum Referenzieren von Dateien finden Sie unter JSON-Datei für komplexe Eingaben verwenden und Digitales Zwillingsmodell erstellen. 

    {
  "@context": [
    "dtmi:dtdl:context;3"
  ],
  "@id": "dtmi:com:oracle:example:core:Capability:cap;1",
  "@type": "Interface",
  "displayName": "Capability",
  "description": "A Capability indicates capacity to produce and ingest data.",
  "contents": [
    {
      "@type": "Property",
      "name": "lastValueTime",
      "schema": "dateTime"
    }
  ]
}

  2. Verwenden Sie den Befehl oci iot digital-twin-model create und die Parameter, um ein digitales Zwillingsmodell mit einem Funktionsbasismodell zu erstellen.

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

    Diese Beispielantwort zeigt, dass das Modell des digitalen Zwillings aktiv ist und die in der Datei model_capability.json definierte DTMI-URI referenziert:

    dtmi:com:oracle:example:core:Capability:cap;1

    {
  "data": {
    "defined-tags": {
      "Oracle-Tags": {
        "CreatedBy": "default/user@oracle.com",
        "CreatedOn": "2025-09-11T05:56:50.514Z"
      }
    },
    "description": "A aapability indicates capacity to produce and ingest data.",
    "display-name": "Capability",
    "freeform-tags": {},
    "id": "<iot-digital-twin-model-OCID>",
    "iot-domain-id": "<iot-domain-OCID>",
    "lifecycle-state": "ACTIVE",
    "spec-uri": "dtmi:com:oracle:example:core:Capability:cap;1",
    "system-tags": {},
    "time-created": "2025-09-11T05:56:50.587000+00:00",
    "time-updated": "2025-09-11T05:56:50.587000+00:00"
  },
  "etag": "<unique-id>"
}

Schritt 2: Erstellen eines digitalen Zwillingsmodells für einen Sensor

  1. Speichern Sie dieses Code-Snippet als model_sensor.json-Datei. Referenzieren Sie diese Datei im nächsten Schritt, um ein weiteres digitales Zwillingsmodell zu erstellen. Dies ist eine Sensordefinition, die die Eigenschaften erbt und das Funktionsbasismodell erweitert.
    {
  "@context": [
    "dtmi:dtdl:context;3"
  ],
  "@id": "dtmi:com:oracle:example:core:Sensor:sen;1",
  "@type": "Interface",
  "extends": "dtmi:com:oracle:example:core:Capability:cap;1",
  "displayName": "Sensor",
  "description": "Capability to detect or measure properties of the physical world.",
  "contents": [
    {
      "@type": "Relationship",
      "displayName": "observes",
      "name": "observes",
      "target": "dtmi:com:oracle:example:core:Space:ex;1"
    }
  ]
}
  2. Verwenden Sie diesen Befehl und Parameter, um die Spezifikationen zum Erstellen eines digitalen Zwillingsmodells zu definieren. 
    oci iot digital-twin-model create --iot-domain-id <iot-domain-OCID> --spec file://model_sensor.json

    Diese Beispielantwort zeigt, dass das Modell des digitalen Zwillings aktiv ist und die spezifische DTMI-URI referenziert, die in der Datei model_sensor.json definiert ist:

    dtmi:com:oracle:example:core:sensor:sen;1

    {
  "data": {
    "defined-tags": {
      "Oracle-Tags": {
        "CreatedBy": "default/user@oracle.com",
        "CreatedOn": "2025-09-11T06:03:25.687Z"
      }
    },
    "description": "Capability to detect or measure properties of the physical world.",
    "display-name": "Sensor",
    "freeform-tags": {},
    "id": "<iot-digital-twin-model-OCID>",
    "iot-domain-id": "<iot-domain-OCID>",
    "lifecycle-state": "ACTIVE",
    "spec-uri": "dtmi:com:oracle:example:core:Sensor:sen;1",
    "system-tags": {},
    "time-created": "2025-09-11T06:03:25.753000+00:00",
    "time-updated": "2025-09-11T06:03:25.753000+00:00"
  },
  "etag": "<unique-id>"
}

Schritt 3: Erstellen eines digitalen Zwillingsmodells für den Env-III-Sensor

  1. Speichern Sie dieses Code-Snippet als model_env.json-Datei. Referenzieren Sie diese Datei im nächsten Schritt, wenn Sie ein anderes digitales Zwillingsmodell erstellen.
    {
  "@context": [
    "dtmi:dtdl:context;3",
    "dtmi:dtdl:extension:quantitativeTypes;1",
    "dtmi:dtdl:extension:historization;1",
    "dtmi:com:oracle:dtdl:extension:validation;1"
  ],
  "@id": "dtmi:com:oracle:example:stack:enviii:ev;2",
  "@type": "Interface",
  "extends": [
    "dtmi:com:oracle:example:core:sensor:sen;1"
  ],
  "displayName": "M5 with EnvIII sensors",
  "description": "Model envIII",
  "contents": [
    {
      "@type": [
        "Telemetry",
        "Historized",
        "Temperature"
      ],
      "name": "room_temp",
      "schema": "double",
      "unit": "degreeCelsius"
    }
  ]
}
  2. Mit diesem Befehl und diesen Parametern können Sie die Spezifikationen definieren, um ein weiteres digitales Zwillingsmodell zu erstellen. 
    oci iot digital-twin-model create --iot-domain-id <iot-domain-OCID> --spec file://model_env.json

    Dieses Beispiel zeigt, dass das digitale Zwillingsmodell aktiv ist und die spezifische DTMI-URI referenziert, die in der Datei model_env.json definiert ist:

    dtmi:com:oracle:example:stack:enviii:ev;2
    {
  "data": {
    "defined-tags": {
      "Oracle-Tags": {
        "CreatedBy": "default/user@oracle.com",
        "CreatedOn": "2025-09-11T06:07:30.882Z"
      }
    },
    "description": "Model envIII",
    "display-name": "M5 with EnvIII sensors",
    "freeform-tags": {},
    "id": "<iot-digital-twin-model-OCID>",
    "iot-domain-id": "<iot-domain-OCID>",
    "lifecycle-state": "ACTIVE",
    "spec-uri": "dtmi:com:oracle:example:stack:enviii:ev;2",
    "system-tags": {},
    "time-created": "2025-09-11T06:07:30.944000+00:00",
    "time-updated": "2025-09-11T06:07:30.944000+00:00"
  },
  "etag": "<unique-id>"
}

Schritt 4: Erstellen eines digitalen Zwillingsmodells für den Weltraum

  1. Speichern Sie dieses Code-Snippet als Datei model_space.json, und referenzieren Sie diese Datei im nächsten Schritt, wenn Sie ein digitales Zwillingsmodell für den Bereich erstellen. Der Raum ist servedBy das Sensormodell.
    {
  "@context": [
    "dtmi:dtdl:context;3"
  ],
  "@id": "dtmi:com:oracle:example:core:Space:sp;1",
  "@type": "Interface",
  "displayName": "Space",
  "description": "Model Space",
  "contents": [
    {
      "@type": "Relationship",
      "displayName": "served by",
      "name": "servedBy",
      "target": "dtmi:com:oracle:example:core:sensor:sen;1"
    }
  ]
}
  2. Verwenden Sie den folgenden Befehl, um ein Modell für digitale Zwillinge zu erstellen, das die file://model_space.json referenziert, um die in der Datei definierten Spezifikationen auf dieses Modell für digitale Zwillinge anzuwenden. 
    oci iot digital-twin-model create --iot-domain-id <iot-domain-OCID> --spec file://model_space.json

    Diese Beispielantwort zeigt, dass das digitale Zwillingsmodell aktiv ist und diese spezifische DTMI-URI referenziert, die in der Datei model_space.json definiert ist:

    dtmi:com:oracle:example:core:Space:sp;1
    {
  "data": {
    "defined-tags": {
      "Oracle-Tags": {
        "CreatedBy": "default/user@oracle.com",
        "CreatedOn": "2025-09-11T06:06:45.538Z"
      }
    },
    "description": "Model Space",
    "display-name": "Space",
    "freeform-tags": {},
    "id": "<iot-digital-twin-model-OCID>",
    "iot-domain-id": "<iot-domain-OCID>",
    "lifecycle-state": "ACTIVE",
    "spec-uri": "dtmi:com:oracle:example:core:Space:sp;1",
    "system-tags": {},
    "time-created": "2025-09-11T06:06:45.574000+00:00",
    "time-updated": "2025-09-11T06:06:45.574000+00:00"
  },
  "etag": "<unique-id>"
}

Schritt 5: Erstellen eines digitalen Twin-Adapters für den Weltraum

Verwenden Sie diesen Befehl, um einen digitalen Zwillingsadapter zu erstellen und die Spezifikation des digitalen Zwillingsmodells mit dem DTMI-URI für den Speicherplatz zu verknüpfen.

Wenn Sie einen digitalen Zwillingsadapter erstellen, können Sie das System zwingen, eine Standard-Payload und Mappings zu erstellen, indem Sie die Optionen inbound-envelope oder inbound-routes nicht angeben.

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:core:space:sp;1"
Diese Beispielantwort zeigt eine bestimmte Adapter-OCID für digitale Zwillinge und dass sie mit einem bestimmten digitalen Zwillingsmodell und einem DTMI-URI verknüpft ist.

dtmi:com:oracle:example:core:Space: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:core:Space:sp;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": "/",
      "reference-payload": {
        "data": {
          "time": "2025-09-11T06:09:27.878106Z"
        },
        "data-format": "JSON"
      }
    },
    "inbound-routes": [
      {
        "condition": "*",
        "description": "default condition",
        "payload-mapping": {},
        "reference-payload": null
      }
    ],
    "iot-domain-id": "<iot-domain-OCID>",
    "lifecycle-state": "ACTIVE",
    "system-tags": {},
    "time-created": "2025-09-11T06:09:27.879000+00:00",
    "time-updated": "2025-09-11T06:09:27.879000+00:00"
  },
  "etag": "<unique-id>"
}

Schritt 6: Erstellen eines digitalen Twin Adapters für den Env-III Sensor

Verwenden Sie diesen Befehl, um einen digitalen Zwillingsadapter zu erstellen und die Spezifikation des digitalen Zwillingsmodells mit dem DTMI-URI für den Env-III-Sensor zu verknüpfen. 
oci iot digital-twin-adapter create --iot-domain-id <iot-domain-OCID> --digital-twin-model-spec-uri "dtmi:com:oracle:room:m5stack:enviii:ev;2"
Diese Beispielantwort zeigt eine bestimmte OCID des digitalen Zwillingsadapters und ist mit einem bestimmten digitalen Zwillingsmodell und DTMI verknüpft.

dtmi:com:oracle:example:stack:enviii:ev;2

{
  "data": {
    "defined-tags": {
      "Oracle-Tags": {
        "CreatedBy": "default/user@oracle.com",
        "CreatedOn": "2025-09-11T06:10:23.303Z"
      }
    },
    "description": null,
    "digital-twin-model-id": "<iot-digital-twin-model-OCID>",
    "digital-twin-model-spec-uri": "dtmi:com:oracle:example:stack:enviii:ev;2",
    "display-name": "<digital-twin-adapter-display-name>",
    "freeform-tags": {},
    "id": "<iot-digital-twin-adapter-OCID>",
    "inbound-envelope": {
      "envelope-mapping": {
        "time-observed": "$.time"
      },
      "reference-endpoint": "/",
      "reference-payload": {
        "data": {
          "sht_temp": 0.0,
          "time": "2025-09-11T06:10:26.127416Z"
        },
        "data-format": "JSON"
      }
    },
    "inbound-routes": [
      {
        "condition": "*",
        "description": "Default condition",
        "payload-mapping": {
          "$.sht_temp": "$.sht_temp"
        },
        "reference-payload": null
      }
    ],
    "iot-domain-id": "<iot-domain-OCID>",
    "lifecycle-state": "ACTIVE",
    "system-tags": {},
    "time-created": "2025-09-11T06:10:27.204000+00:00",
    "time-updated": "2025-09-11T06:10:27.204000+00:00"
  },
  "etag": "<unique-id>"
}

Schritt 7: Erstellen einer digitalen Zwillingsinstanz mit einem Adapter für einen Raum

Mit diesem Befehl können Sie eine digitale Zwillingsinstanz mit einem Anzeigenamen erstellen, der ein Secret zur Authentifizierung verwendet und einem bestimmten digitalen Zwillingsmodell und einem digitalen Zwillingsadapter zugeordnet ist. Informationen zum Erstellen eines Vault Secrets finden Sie unter Secrets erstellen. 
oci iot digital-twin-instance create --auth-id <vault-secret-OCID> --iot-domain-id <iot-domain-OCID> --digital-twin-adapter-id <iot-digital-twin-adapter-OCID> --display-name <your-display-name>
Diese Beispielantwort zeigt die spezifische OCID der digitalen Zwillingsinstanz und den zugehörigen digitalen Zwillingsadapter, das digitale Zwillingsmodell und die externe Schlüssel-ID. Sie enthält die spezifische DTMI-URI, die für den Speicherplatz definiert ist:

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

{
  "data": {
    "auth-id": "<vault-secret-OCID>",
    "defined-tags": {
      "Oracle-Tags": {
        "CreatedBy": "default/user@oracle.com",
        "CreatedOn": "2025-09-11T06:12:43.393Z"
      }
    },
    "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:core:Space:sp;1",
    "display-name": "device for conference room 103",
    "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-09-11T06:12:44.178000+00:00",
    "time-updated": "2025-09-11T06:12:44.178000+00:00"
  },
  "etag": "<unique-id>"
}

Schritt 8: Erstellen einer digitalen Zwillingsinstanz mit Adapter für einen Env-III-Sensor

Mit diesem Befehl können Sie eine digitale Zwillingsinstanz mit einem Anzeigenamen erstellen, der ein Secret zur Authentifizierung verwendet und mit einem bestimmten digitalen Zwillingsmodell, einem digitalen Zwillingsadapter und einer IoT-Domain verknüpft ist. Ersetzen Sie die OCID durch die zugehörigen IoT-Ressourcen für Ihre Umgebung.

oci iot digital-twin-instance create --auth-id <vault-secret-OCID> --iot-domain-id <iot-domain-OCID> --digital-twin-adapter-id <iot-digital-twin-adapter-OCID> --display-name "<your-display-name>"
Diese Beispielantwort zeigt, dass die digitale Zwillingsinstanz aktiv ist und das zugehörige digitale Zwillingsmodell und den digitalen Zwillingsadapter enthält.
{
  "data": {
    "auth-id": "<vault-secret-OCID>",
    "defined-tags": {
      "Oracle-Tags": {
        "CreatedBy": "default/user@oracle.com",
        "CreatedOn": "2025-09-11T06:14:33.493Z"
      }
    },
    "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:stack:enviii:ev;2",
    "display-name": "Envii device 2",
    "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-09-11T06:14:34.821000+00:00",
    "time-updated": "2025-09-11T06:14:34.821000+00:00"
  },
  "etag": "<unique-id>"
}

Schritt 9: Erstellen einer digitalen Zwillingsbeziehung, um zwei digitale Zwillingsinstanzen zu verbinden

Mit diesem Befehl können Sie eine digitale Zwillingsbeziehung zwischen zwei digitalen Zwillingsinstanzen erstellen und den Inhaltspfad als servedBy, den Verbindungstyp als wi-fi und den Anzeigenamen für diese digitale Zwillingsbeziehung definieren.
oci iot digital-twin-relationship create --iot-domain-id <iot-domain-OCID> --target-digital-twin-instance-id <iot-digital-twin-instance-OCID> --source-digital-twin-instance-id <iot-digital-twin-instance-OCID> --content-path "servedBy" --content '{"connectionType": "wi-fi"}' --display-name "Env and sensor relationship"
Diese Beispielantwort zeigt den Inhaltspfad und die zugehörigen digitalen Zwillingsinstanzen für diese digitale Zwillingsbeziehung:
{
  "data": {
    "content": {
      "connectionType": "wi-fi"
    },
    "content-path": "servedBy",
    "defined-tags": {
      "Oracle-Tags": {
        "CreatedBy": "default/user@oracle.com",
        "CreatedOn": "2025-09-11T07:40:08.926Z"
      }
    },
    "description": null,
    "display-name": "Env and sensor relationship",
    "freeform-tags": {},
    "id": "<iot-digital-twin-relationship-OCID>",
    "iot-domain-id": "<iot-domain-OCID>",
    "lifecycle-state": "ACTIVE",
    "source-digital-twin-instance-id": "<iot-digital-twin-instance-OCID>",
    "system-tags": {},
    "target-digital-twin-instance-id": "<iot-digital-twin-instance-OCID>",
    "time-created": "2025-09-11T07:40:09.755000+00:00",
    "time-updated": "2025-09-11T07:40:09.755000+00:00"
  },
  "etag": "<unique-id>"
}

Schritt 10: Digital Twin Relationship Graph mit SQL abfragen

Wenn Sie mit SQL-Abfragen Ihre IoT-Daten in APEX oder direkt in der Datenbank anzeigen möchten, für die eine Verbindung zu APEX konfiguriert werden muss oder eine direkte Datenbankverbindung konfiguriert werden muss.

Verwenden Sie in APEX oder direkt in der Datenbank die folgenden SQL-Anweisungen, um die Details der digitalen Zwillingsbeziehung für eine bestimmte digitale Zwillingsinstanz zu suchen. Ersetzen Sie <domain-short-id-from-device-host> durch die Domain-Kurz-ID vom Gerätehost. Ersetzen Sie <digital-twin-instance-OCID> durch die OCID der digitalen Zwillingsinstanz, mit der Sie arbeiten möchten:

Hinweis

Beachten Sie zwei Unterstriche in __IOT.
<domain-short-id-from-device-host>__IOT.DIGITAL_TWINS
SELECT * FROM GRAPH_TABLE(
    <domain-short-id-from-device-host>__IOT.DIGITAL_TWINS
    MATCH (a IS digitalTwinInstance) -[e IS digitalTwinRelationship]-> (b IS digitalTwinInstance)
    WHERE a.id = '<digital-twin-instance-OCID>'
    COLUMNS (a.id as src, e.content_path as rel, b.id as tgt)
);

Um die Beziehungen zwischen zwei digitalen Zwillingsinstanzen zu finden, verwenden Sie die folgende Abfrage. Ersetzen Sie FROM_DIGITAL-TWIN-INSTANCE-OCID durch die OCID der digitalen Zwillingsinstanz der Quelle und TO_DIGITAL-TWIN-INSTANCE-OCID durch die OCID der digitalen Zwillingsinstanz des Ziels, für die Sie den Inhaltspfad suchen möchten:

SELECT * FROM GRAPH_TABLE(
    <domain-short-id-from-device-host>__IOT.DIGITAL_TWINS
    MATCH (a IS digitalTwinInstance) -[e IS digitalTwinRelationship]-> (b IS digitalTwinInstance)
    WHERE a.id = 'FROM_DIGITAL-TWIN-INSTANCE-OCID'AND b.id = 'TO_DIGITAL-TWIN-INSTANCE-OCID'
    COLUMNS (a.id as src, e.content_path as rel, b.id as tgt)
);