Documentation sur Oracle Cloud Infrastructure

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 et l'humidité. 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

  1. Créer un modèle jumeau numérique avec un modèle de base de capacité
  2. Créer un modèle jumeau numérique pour un capteur
  3. Créer un modèle jumeau numérique pour le capteur Env-III
  4. Créer un modèle jumeau numérique pour l'espace
  5. Créer un adaptateur jumeau numérique pour l'espace
  6. Créer un adaptateur jumeau numérique pour le capteur Env-III
  7. Créer une instance de jumeau numérique avec un adaptateur pour un espace
  8. Créer une instance de jumeau numérique avec un adaptateur pour un capteur Env-III
  9. Créer une relation de jumeau numérique pour connecter les instances de jumeau numérique
  10. Interroger le graphique Digital Twin Relationship à l'aide de SQL

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

  1. 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"
    }
  ]
}

  2. 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

  1. 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"
    }
  ]
}
  2. 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

  1. 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"
    }
  ]
}
  2. 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

  1. 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"
    }
  ]
}
  2. 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 l'espace

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

Lorsque vous créez un adaptateur jumeau numérique, vous pouvez forcer le système à créer des données utiles et des mappages par défaut en ne spécifiant pas les options inbound-envelope ou inbound-routes.

Si le mappage d'enveloppe n'est pas spécifié et contient un timeObserved, receivedTime est utilisé en tant que valeur timeObserved. 

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"
Cet exemple de réponse montre un OCID d'adaptateur de jumeau numérique spécifique et qu'il est associé à un modèle de jumeau numérique spécifique et à un URI DTMI.

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

Étape 6 : 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:m5stack: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 7 : Créer une instance de jumeau numérique avec un adaptateur pour un espace

Utilisez cette commande pour créer une instance de jumeau numérique avec un nom d'affichage qui utilise un secret pour l'authentification et qui est associé à un modèle de jumeau numérique et à un adaptateur de jumeau numérique spécifiques. Pour plus d'informations sur la création d'une clé secrète de chambre forte, voir Création d'une clé secrète. 
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>
Cet exemple de réponse présente l'OCID de l'instance de jumeau numérique spécifique et son adaptateur jumeau numérique associé, 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": "<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>"
}

Étape 8 : 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-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 9 : 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" --content '{"connectionType": "wi-fi"}' --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 10 : 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.
<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)
);