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, bei dem es sich um ein Gerät im Raum handelt, das Umwelteigenschaften einschließlich Temperatur 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. Digital Twin Adapter für den Env-III Sensor erstellen
  6. Erstellen einer digitalen Zwillingsinstanz für einen Arbeitsplatz
  7. Erstellen einer digitalen Zwillingsinstanz mit Adapter für einen Env-III-Sensor
  8. Erstellen einer digitalen Zwillingsbeziehung zum Verbinden der digitalen Zwillingsinstanzen
  9. Digital Twin Relationship Graph mit SQL abfragen

Bevor Sie beginnen

Stellen Sie sicher, dass Sie über die erforderlichen Berechtigungen verfügen. Ein Administrator erteilt Zugriff, indem er die erforderlichen Policys erstellt. Weitere Informationen finden Sie unter Voraussetzungen und Policy-Details für die Internet of Things-(IoT-)Plattform.

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 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:stack: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 6: Erstellen einer digitalen Zwillingsinstanz für einen Arbeitsplatz

Mit diesem Befehl können Sie eine digitale Zwillingsinstanz für einen Arbeitsplatz erstellen. Dieses Beispiel zeigt, wie ein digitales Zwillingsmodell mit dem DTMI-Spezifikations-URI-Parameter --digital-twin-model-spec-uri verknüpft wird. Alternativ können Sie den OCID-Parameter des digitalen Zwillingsmodells verwenden, um das digitale Zwillingsmodell zuzuordnen, indem Sie die OCID des digitalen Zwillingsmodells angeben.

Diese digitale Zwillingsinstanz erfordert keinen Adapter oder keine Authentifizierung, da sie keine Daten an andere Systeme oder Dienste sendet oder veröffentlicht.
oci iot digital-twin-instance create --iot-domain-id <iot-domain-OCID> --display-name <device-for-conference-room-103> --digital-twin-model-spec-uri <dtmi:com:oracle:example:core:Space:sp;1>
Diese Beispielantwort zeigt die spezifische OCID der digitalen Zwillingsinstanz, das digitale Zwillingsmodell und die externe Schlüssel-ID und enthält die spezifische DTMI-URI, die für den Speicherplatz definiert ist:

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

{
  "data": {
    "auth-id": null,
    "defined-tags": {
      "Oracle-Tags": {
        "CreatedBy": "default/user@oracle.com",
        "CreatedOn": "2025-09-11T06:12:43.393Z"
      }
    },
    "description": null,
    "digital-twin-adapter-id": 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": "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 7: 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-or-certificate-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 8: 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" --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 9: 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. Im Eigenschaftsdiagramm werden nur digitale Zwillingsinstanzen und Beziehungen mit lifecycle_state = ACTIVE angezeigt.
<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)
);