Documentation Oracle Cloud Infrastructure

Scénario : requête d'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, les capacités, les données et la 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 desservent un espace spécifique ?
  • Quelle télémétrie ces capteurs rapportent-ils ?
  • Comment les appareils sont-ils connectés, en utilisant le wi-fi ?

Tâches

  1. Créer un modèle de jumeau numérique avec un modèle de base de capacité
  2. Création d'un modèle de jumeau numérique pour un capteur
  3. Créer un modèle de jumeau numérique pour le capteur Env-III
  4. Créer un modèle de 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éation d'une instance de jumeau numérique avec un adaptateur pour un espace
  8. Création d'une instance de jumeau numérique avec un adaptateur pour un capteur Env-III
  9. Création d'une relation de jumeau numérique pour connecter les instances de jumeau numérique
  10. Interroger le graphique relationnel des jumeaux numériques à l'aide de SQL

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

  1. Enregistrez ce fragment 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 des fichiers, reportez-vous à Utilisation d'un fichier JSON pour les entrées complexes et à Création d'un modèle de 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 de 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 de jumeau numérique pour un capteur

  1. Enregistrez ce fragment 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 et étend le modèle de base de capacité.
    {
  "@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 permettant de créer un modèle de 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 de jumeau numérique pour le capteur Env-III

  1. Enregistrez ce fragment 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>"
}

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

  1. Enregistrez ce fragment 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 afin d'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>"
}

Etape 5 : Créer un adaptateur jumeau numérique pour l'espace

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 de l'espace.

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

Si le mapping d'enveloppe n'est pas spécifié et contient une valeur timeObserved, receivedTime est utilisé comme 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 de jumeau numérique spécifique et qu'il est associé à un modèle de jumeau numérique et un URI DTMI spécifiques.

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 de modèle jumeau numérique à l'URI DTMI pour le 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 de jumeau numérique spécifique et il est associé à un modèle de 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>"
}

Etape 7 : création d'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 une clé secrète pour l'authentification et qui est associée à un modèle de jumeau numérique et un adaptateur de jumeau numérique spécifiques. Pour plus d'information sur le processus de création d'une clé secrète du coffre, reportez-vous à 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 montre l'OCID d'instance de jumeau numérique spécifique et son adaptateur de jumeau numérique associé, son modèle de jumeau numérique et son ID de 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>"
}

Etape 8 : création d'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, un adaptateur de jumeau numérique et un domaine IoT spécifiques. Remplacez les OCID par les ressources IoT associées de 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 et l'adaptateur de jumeau numérique associés.
{
  "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>"
}

Etape 9 : création d'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 en tant que servedBy, le type de connexion en tant que 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 associées 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>"
}

Etape 10 : interroger le graphique relationnel des jumeaux numériques à l'aide de SQL

Si vous voulez utiliser des requêtes SQL pour visualiser vos données IoT dans APEX ou directement dans la base de données, qui nécessitent la configuration d'une connexion à APEX ou la configuration d'une connexion de base de données directe.

Dans APEX ou directement dans la base de données, utilisez les instructions SQL suivantes pour rechercher les détails de relation de jumeau numérique d'une instance de jumeau numérique spécifique. Remplacez <domain-short-id-from-device-host> par l'ID abrégé de domaine de l'hôte du périphérique. Remplacez <digital-twin-instance-OCID> par l'OCID d'instance de jumeau numérique avec lequel vous voulez travailler :

Remarque

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 la requête suivante. Remplacez FROM_DIGITAL-TWIN-INSTANCE-OCID par l'OCID d'instance de jumeau numérique source et TO_DIGITAL-TWIN-INSTANCE-OCID par l'OCID d'instance de jumeau numérique cible pour lequel rechercher 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)
);