Scénario : Interroger une relation de jumeau numérique

Une instance de jumeau numérique peut utiliser des modèles de jumeau numérique, des adaptateurs de jumeau numérique, des hiérarchies et des relations pour créer un modèle virtuel qui représente un environnement réel.

Ce scénario explique comment interroger une relation de jumeau numérique pour répondre à des questions sur un appareil, ses capacités, ses données et sa connectivité, afin de surveiller un espace physique et ses appareils. Dans ce scénario, un espace est une zone physique, par exemple une salle de conférence. Cela est servi par un capteur Env-III qui est un dispositif situé dans l'espace qui mesure les caractéristiques environnementales, y compris la température. Cette hiérarchie et la relation servedBy permettent aux applications d'interroger :

Quels capteurs servent un espace spécifique?
Quelle télémétrie est signalée par ces capteurs?
Comment les appareils sont-ils connectés, avec wi-fi?

Tâches

Créer un modèle jumeau numérique avec un modèle de base de capacité
Créer un modèle jumeau numérique pour un capteur
Créer un modèle jumeau numérique pour le capteur Env-III
Créer un modèle jumeau numérique pour l'espace
Créer un adaptateur jumeau numérique pour le capteur Env-III
Créer une instance de jumeau numérique pour un espace
Créer une instance de jumeau numérique avec un adaptateur pour un capteur Env-III
Créer une relation de jumeau numérique pour connecter les instances de jumeau numérique
Interroger le graphique Digital Twin Relationship à l'aide de SQL

Avant de commencer

Assurez-vous que vous disposez des autorisations requises. Un administrateur accorde l'accès en créant les politiques requises. Pour plus d'informations, voir Préalables et Informations détaillées sur les politiques pour la plate-forme Internet of Things (IoT).

Étape 1 : Créer un modèle jumeau numérique avec un modèle de base de capacité

Enregistrez cet extrait de code en tant que fichier model_capability.json. Référencez ce fichier à l'étape suivante lorsque vous créez un modèle de jumeau numérique. Cette spécification de modèle définit la capacité et agit comme un modèle de base.
Pour plus d'informations sur le référencement de fichiers, voir Utilisation d'un fichier JSON pour une entrée complexe et créer un modèle jumeau numérique.
```
{
  "@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"
    }
  ]
}
```

Utilisez la commande et les paramètres oci iot digital-twin-model create pour créer un modèle jumeau numérique avec un modèle de base de capacités.

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

Cet exemple de réponse montre que le modèle de jumeau numérique est actif et référence l'URI DTMI défini dans le fichier model_capability.json :

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>"
}

Étape 2 : Créer un modèle jumeau numérique pour un capteur

Enregistrez cet extrait de code en tant que fichier model_sensor.json. Référencez ce fichier à l'étape suivante pour créer un autre modèle de jumeau numérique. Il s'agit d'une définition de capteur qui hérite des propriétés du modèle de base de capacité et l'étend.

{
  "@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"
    }
  ]
}

Utilisez cette commande et ces paramètres pour définir les spécifications afin de créer un modèle jumeau numérique.

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

Cet exemple de réponse montre que le modèle de jumeau numérique est actif et référence l'URI DTMI spécifique défini dans le fichier model_sensor.json :

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>"
}

Étape 3 : Créer un modèle jumeau numérique pour le capteur Env-III

Enregistrez cet extrait de code en tant que fichier model_env.json. Référencez ce fichier à l'étape suivante lorsque vous créez un autre modèle de jumeau numérique.

{
  "@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"
    }
  ]
}

Utilisez cette commande et ces paramètres pour définir les spécifications afin de créer un autre modèle de jumeau numérique.

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

Cet exemple montre que le modèle de jumeau numérique est actif et référence l'URI DTMI spécifique défini dans le fichier model_env.json :

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>"
}

Étape 4 : Créer un modèle jumeau numérique pour l'espace

Enregistrez cet extrait de code en tant que fichier model_space.json et référencez-le à l'étape suivante lorsque vous créez un modèle de jumeau numérique pour l'espace. L'espace est servedBy le modèle de capteur.

{
  "@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"
    }
  ]
}

Utilisez la commande suivante pour créer un modèle de jumeau numérique référençant file://model_space.json pour appliquer les spécifications définies dans le fichier à ce modèle de jumeau numérique.

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

Cet exemple de réponse montre que le modèle de jumeau numérique est actif et référence cet URI DTMI spécifique défini dans le fichier model_space.json :

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>"
}

Étape 5 : Créer un adaptateur jumeau numérique pour le capteur Env-III

Utilisez cette commande pour créer un adaptateur jumeau numérique et associer la spécification du modèle jumeau numérique à l'URI DTMI du capteur Env-III.

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"

Cet exemple de réponse montre un OCID d'adaptateur jumeau numérique spécifique et il est associé à un modèle jumeau numérique et à un DTMI spécifiques.

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>"
}

Étape 6 : Créer une instance de jumeau numérique pour un espace

Utilisez cette commande pour créer une instance de jumeau numérique pour un espace. Cet exemple montre comment associer un modèle jumeau numérique à l'aide du paramètre URI --digital-twin-model-spec-uri de la spécification DTMI. Vous pouvez également utiliser le paramètre OCID du modèle de jumeau numérique pour associer le modèle de jumeau numérique en spécifiant l'OCID du modèle de jumeau numérique.

Cette instance de jumeau numérique ne nécessite pas d'adaptateur ou d'authentification car elle n'envoie ni ne publie de données à d'autres systèmes ou services.

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>

Cet exemple de réponse présente l'OCID de l'instance de jumeau numérique spécifique, le modèle de jumeau numérique, l'ID clé externe et inclut l'URI DTMI spécifique défini pour l'espace :

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>"
}

Étape 7 : Créer une instance de jumeau numérique avec un adaptateur pour un capteur Env-III

Utilisez cette commande pour créer une instance de jumeau numérique avec un nom d'affichage qui utilise une clé secrète pour l'authentification et qui est associée à un modèle de jumeau numérique spécifique, à un adaptateur de jumeau numérique et à un domaine IoT. Remplacez les OCID par les ressources IoT connexes pour votre environnement.

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>"

Cet exemple de réponse montre que l'instance de jumeau numérique est active et contient le modèle de jumeau numérique associé et l'adaptateur de jumeau numérique.

{
  "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>"
}

Étape 8 : Créer une relation de jumeau numérique pour connecter deux instances de jumeau numérique

Utilisez cette commande pour créer une relation de jumeau numérique entre deux instances de jumeau numérique et pour définir le chemin de contenu servedBy, le type de connexion wi-fi et le nom d'affichage de cette relation de jumeau numérique.

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"

Cet exemple de réponse montre le chemin de contenu et les instances de jumeau numérique connexes pour cette relation de jumeau numérique :

{
  "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>"
}

Étape 9 : Interroger le graphique Digital Twin Relationship à l'aide de SQL

Si vous voulez utiliser des interrogations SQL pour voir vos données IoT dans APEX ou directement dans la base de données qui nécessite la configuration d'une connexion à APEX ou la configuration d'une connexion directe à la base de données.

Dans APEX ou directement dans la base de données, utilisez les énoncés SQL suivants pour rechercher les détails de la relation de jumeau numérique pour une instance de jumeau numérique spécifique. Remplacez <domain-short-id-from-device-host> par l'ID court de domaine de l'hôte de l'appareil. Remplacez <digital-twin-instance-OCID> par l'OCID de l'instance de jumeau numérique à utiliser :

Note

Notez deux traits de soulignement dans __IOT. Seules les instances de jumeau numérique et les relations avec lifecycle_state = ACTIVE apparaissent dans le graphique de propriétés.

<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)
);

Pour rechercher les relations entre deux instances de jumeau numérique, utilisez l'interrogation suivante. Remplacez FROM_DIGITAL-TWIN-INSTANCE-OCID par l'OCID de l'instance de jumeau numérique source et TO_DIGITAL-TWIN-INSTANCE-OCID par l'OCID de l'instance de jumeau numérique cible pour lequel vous voulez trouver le chemin de contenu :

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)
);

Documentation sur Oracle Cloud Infrastructure