Escenario: Consulta de una relación gemela digital

Una instancia de gemelo digital puede utilizar modelos de gemelo digital, adaptadores de gemelo digital, jerarquías y relaciones para crear un modelo virtual que represente un entorno real.

En este escenario se explica cómo puede consultar una relación de gemelos digitales para responder preguntas sobre un dispositivo, capacidades, datos y conectividad, para supervisar un espacio físico y sus dispositivos. En este escenario, un espacio es un área física, por ejemplo, una sala de conferencias. Eso es servido por un sensor Env-III que es un dispositivo ubicado en el espacio que mide las características ambientales, incluida la temperatura. Esta jerarquía y la relación servedBy permiten a las aplicaciones realizar consultas:

¿Qué sensores sirven a un espacio específico?
¿Qué telemetría reportan estos sensores?
¿Cómo se conectan los dispositivos con wi-fi?

Tareas

Creación de un modelo gemelo digital con un modelo base de capacidades
Crear un modelo gemelo digital para un sensor
Crear un modelo gemelo digital para el sensor Env-III
Crear un modelo gemelo digital para el espacio
Cree un adaptador gemelo digital para el sensor Env-III
Creación de una instancia gemela digital para un espacio
Creación de una instancia gemela digital con un adaptador para un sensor Env-III
Cree una relación de gemelo digital para conectar las instancias de gemelo digital
Consulta del gráfico de relaciones gemelas digitales mediante SQL

Antes de empezar

Asegúrese de que tiene los permisos necesarios. Un administrador otorga acceso mediante la creación de las políticas necesarias. Para obtener más información, consulte Requisitos y Detalles de política para la plataforma Internet of Things (IoT).

Paso 1: Crear un modelo gemelo digital con un modelo base de capacidad

Guarde este fragmento de código como un archivo model_capability.json. Haga referencia a este archivo en el siguiente paso cuando cree un modelo de gemelo digital. Esta especificación de modelo define la capacidad y actúa como un modelo base.
Para obtener más información sobre las referencias a archivos, consulte Uso de un archivo JSON para entrada compleja y creación de un modelo gemelo digital.
```
{
  "@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"
    }
  ]
}
```

Utilice el comando oci iot digital-twin-model create y los parámetros para crear un modelo gemelo digital con un modelo base de capacidad.

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

Esta respuesta de ejemplo muestra que el modelo de gemelo digital está activo y hace referencia al URI de DTMI definido en el archivo 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>"
}

Paso 2: Crear un modelo gemelo digital para un sensor

Guarde este fragmento de código como un archivo model_sensor.json. Haga referencia a este archivo en el siguiente paso para crear otro modelo de gemelo digital. Definición de sensor que hereda las propiedades y amplía el modelo base de capacidad.

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

Utilice este comando y parámetros para definir las especificaciones para crear un modelo gemelo digital.

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

Esta respuesta de ejemplo muestra que el modelo de gemelo digital está activo y hace referencia al URI de DTMI específico definido en el archivo 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>"
}

Paso 3: Crear un modelo digital gemelo para el sensor Env-III

Guarde este fragmento de código como un archivo model_env.json. Haga referencia a este archivo en el siguiente paso cuando cree otro modelo de gemelo digital.

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

Utilice este comando y parámetros para definir las especificaciones para crear otro modelo de gemelo digital.

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

En este ejemplo, se muestra que el modelo de gemelo digital está activo y hace referencia al URI de DTMI específico definido en el archivo 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>"
}

Paso 4: Crear un modelo gemelo digital para el espacio

Guarde este fragmento de código como un archivo model_space.json y haga referencia a este archivo en el siguiente paso al crear un modelo de gemelo digital para el espacio. El espacio es servedBy el modelo de sensor.

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

Utilice el siguiente comando para crear un modelo de gemelo digital que haga referencia a file://model_space.json para aplicar las especificaciones definidas en el archivo a este modelo de gemelo digital.

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

Esta respuesta de ejemplo muestra que el modelo de gemelo digital está activo y hace referencia a este URI de DTMI específico definido en el archivo 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>"
}

Paso 5: Crear un adaptador digital gemelo para el sensor Env-III

Utilice este comando para crear un adaptador gemelo digital y asociar la especificación de modelo gemelo digital con el URI de DTMI para el sensor 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"

En este ejemplo de respuesta se muestra un OCID de adaptador de gemelo digital específico y está asociado a un modelo de gemelo digital y DTMI específicos.

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

Paso 6: Crear una instancia gemela digital para un espacio

Utilice este comando para crear una instancia de gemelo digital para un espacio. En este ejemplo se muestra cómo asociar un modelo gemelo digital mediante el parámetro URI --digital-twin-model-spec-uri de especificación de DTMI. También puede utilizar el parámetro OCID del modelo de gemelo digital para asociar el modelo de gemelo digital especificando el OCID del modelo de gemelo digital.

Esta instancia de gemelo digital no necesita un adaptador ni autenticación porque no envía ni publica datos a otros sistemas o servicios.

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>

En esta respuesta de ejemplo se muestra el OCID de instancia de gemelo digital específico, el modelo de gemelo digital, el ID de clave externa e incluye el URI de DTMI específico definido para el espacio:

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

Paso 7: Crear una instancia gemela digital con un adaptador para un sensor Env-III

Utilice este comando para crear una instancia de gemelo digital con un nombre mostrado que utilice un secreto para autenticarse y que esté asociada a un modelo de gemelo digital específico, adaptador de gemelo digital y dominio IoT. Sustituya los OCID por los recursos IoT relacionados para su entorno.

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

Esta respuesta de ejemplo muestra que la instancia de gemelo digital está activa y contiene el modelo de gemelo digital relacionado y el adaptador de gemelo digital.

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

Paso 8: Crear una relación gemela digital para conectar dos instancias gemelas digitales

Utilice este comando para crear una relación de gemelo digital entre dos instancias de gemelo digital y para definir la ruta de contenido como servedBy, el tipo de conexión como wi-fi y el nombre mostrado para esta relación de gemelo digital.

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"

En esta respuesta de ejemplo se muestra la ruta de contenido y las instancias de gemelos digitales relacionadas para esta relación de gemelos digitales:

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

Paso 9: Consulta del Gráfico de Relaciones Gemelas Digitales con SQL

Si desea utilizar consultas SQL para ver los datos de IoT en APEX o directamente en la base de datos que necesita configurar una conexión a APEX o configurar una conexión directa a la base de datos.

En APEX o directamente en la base de datos, utilice las siguientes sentencias SQL para buscar los detalles de la relación de gemelos digitales para una instancia de gemelo digital específica. Sustituya <domain-short-id-from-device-host> por el domain short id del host del dispositivo. Sustituya <digital-twin-instance-OCID> por el OCID de instancia de gemelo digital con el que desea trabajar:

Nota

Observe dos guiones bajos en __IOT. Solo las instancias de gemelos digitales y las relaciones con lifecycle_state = ACTIVE aparecen en el gráfico de propiedades.

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

Para buscar las relaciones entre dos instancias de gemelos digitales, utilice la siguiente consulta. Sustituya FROM_DIGITAL-TWIN-INSTANCE-OCID por el OCID de instancia de gemelo digital de origen y TO_DIGITAL-TWIN-INSTANCE-OCID por el OCID de instancia de gemelo digital de destino para el que desea buscar la ruta de contenido:

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

Documentación de Oracle Cloud Infrastructure