Documentación de Oracle Cloud Infrastructure

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, incluyendo la temperatura y la humedad. 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

  1. Creación de un modelo gemelo digital con un modelo base de capacidades
  2. Crear un modelo gemelo digital para un sensor
  3. Crear un modelo gemelo digital para el sensor Env-III
  4. Crear un modelo gemelo digital para el espacio
  5. Crear un adaptador gemelo digital para el espacio
  6. Cree un adaptador gemelo digital para el sensor Env-III
  7. Creación de una Instancia Gemela Digital con un Adaptador para un Espacio
  8. Creación de una instancia gemela digital con un adaptador para un sensor Env-III
  9. Cree una relación de gemelo digital para conectar las instancias de gemelo digital
  10. Consulta del gráfico de relaciones gemelas digitales mediante SQL

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

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

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

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

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

  1. 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"
    }
  ]
}
  2. 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 gemelo digital para el espacio

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

Al crear un adaptador gemelo digital, puede forzar al sistema a crear una carga útil y asignaciones por defecto sin especificar las opciones inbound-envelope o inbound-routes.

Si no se especifica la asignación de sobre y contiene un valor timeObserved, receivedTime se utiliza como valor 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"
En este ejemplo de respuesta se muestra un OCID de adaptador de gemelo digital específico y que está asociado a un modelo de gemelo digital específico y un URI de 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>"
}

Paso 6: Crear un adaptador digital doble 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:m5stack: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 7: Creación de una Instancia Gemela Digital con un Adaptador para un Espacio

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 y un adaptador de gemelo digital. Para obtener información sobre cómo crear un secreto del almacén, consulte Creación de un secreto. 
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>
En esta respuesta de ejemplo se muestra el OCID de instancia de gemelo digital específico y su adaptador de gemelo digital asociado, 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": "<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>"
}

Paso 8: 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-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 9: 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" --content '{"connectionType": "wi-fi"}' --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 10: Consulta del gráfico de relaciones gemelas digitales mediante 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.
<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)
);