Documentación de Oracle Cloud Infrastructure

Creación de un modelo gemelo digital

Cree un modelo de gemelo digital para su Internet of Things (IoT).

Un modelo de gemelo digital define la semántica de un gemelo digital y se basa en las especificaciones de DTDL v3.

Una instancia gemela digital requiere un modelo gemelo digital y un adaptador gemelo digital para recibir datos de un dispositivo que envía datos estructurados. Para ver ejemplos específicos, consulte Escenarios.

Nota

El idioma de definición de gemelos digitales (DTDL) v3 está soportado en GitHub por Digital Twin Consortium. Es importante anotar:
  • Las extensiones MQTT y las propiedades de escritura no están soportadas. Si se incluye una propiedad writable, se debe definir en false.
  • Solo se puede anotar content dentro del componente como historized, lo que indica que la plataforma IoT debe conservar la telemetría de serie temporal de ese sensor. Consulte el ejemplo de modelo gemelo digital dtdl-model-specifications.json a continuación.

Si desea crear una instancia de gemelo digital sin datos ingeribles de un dispositivo, puede crear una instancia de gemelo digital sin un adaptador de gemelo digital y sin el parámetro de ID de autenticación, --auth-id. El modelo gemelo digital asociado no debe contener telemetría ni propiedades. Después de crear una instancia de gemelo digital, puede crear una relación de gemelo digital para simular su entorno de IoT sin la complejidad de los datos ni la autenticación.

    1. En la página de lista Dominios de IoT, seleccione el dominio de IoT con el que desea trabajar. Si necesita ayuda para encontrar la página de lista de dominios de IoT, consulte Listado de dominios de IoT.
    2. Seleccione el separador Modelos gemelos digitales y seleccione Crear.
    3. Introduzca un nombre y, opcionalmente, una descripción fácil de recordar. Evite introducir información confidencial.
    4. Seleccione una opción para agregar la especificación de DTDL del modelo:
      • Para cargar el archivo dtdl-specification.json, seleccione cargar la especificación. Arrastre y suelte o seleccione un archivo .json con la especificación DTDL para este modelo de gemelo digital.
      • Para agregar el valor JSON para el modelo gemelo digital, seleccione pegar especificación.
    5. Etiquetas: (opcional) agregue una o más etiquetas al modelo de gemelo digital. Si tiene permisos para crear un recurso, también los tiene para aplicar etiquetas de formato libre a ese recurso. Para aplicar una etiqueta definida, debe tener permisos para utilizar el espacio de nombres de la etiqueta. Para obtener más información sobre el etiquetado, consulte Etiquetas de recursos. Si no está seguro de si desea aplicar etiquetas, omita esta opción o pregunte a un administrador. Puede aplicar etiquetas más tarde.
    6. Seleccione Crear.

    Vea los detalles del modelo gemelo digital. Copie el OCID de dominio de IoT asociado, el modelo de gemelo digital DTMI o el OCID de modelo de gemelo digital.

    Seleccione el separador relacionado para ver la especificación de DTDL, las instancias de gemelos digitales asociadas, los adaptadores de gemelos digitales asociados o las etiquetas para este modelo de gemelo digital.

  • Utilice el comando oci iot digital-twin-model create y los parámetros necesarios para crear un modelo de gemelo digital en un dominio IoT específico. Proporcione las especificaciones como contenido JSON directamente en la línea de comandos o como archivo al que se hace referencia en la línea de comandos:

    Ejemplo en línea: este ejemplo muestra cómo proporcionar las especificaciones JSON directamente en la línea de comandos:

    oci iot digital-twin-model create --iot-domain-id <iot-domain-OCID> --spec '{"@context": ["dtmi:dtdl:context;3", "dtmi:dtdl:extension:historization;1", "dtmi:dtdl:extension:quantitativeTypes;1", "dtmi:com:oracle:dtdl:extension:validation;1"], "@id": "dtmi:com:oracle:iot:sample:hvac:UgNaNWHbzK;1", "@type": "Interface", "contents": [{"@type": ["Telemetry", "Temperature"], "name": "temperature", "schema": "integer", "unit": "degreeFahrenheit"}, {"@type": ["Telemetry", "Historized", "Validated"], "name": "humidity", "schema": "integer", "minimum": 0, "maximum": 100}, {"@type": ["Property", "Historized"], "name": "location", "schema": "point", "writable": true}, {"@type": ["Property", "Validated"], "name": "serialNumber", "schema": "string", "pattern": "^([0-9]){2}([0-9]){5}([0-9]){6}$"}]}'

    Ejemplo de referencia de archivo: en este ejemplo se muestra cómo crear un archivo dtdl-model-specifications.json que contenga las especificaciones, cómo hacer referencia al archivo .json en el comando. El formato puede variar según el sistema operativo para obtener más información sobre cómo hacer referencia a archivos. Consulte Uso de un archivo JSON para una entrada compleja:

    oci iot digital-twin-model create --iot-domain-id <iot-domain-OCID> --spec file://dtdl-model-specifications.json
    En este fragmento del ejemplo de modelo gemelo digital a continuación:
    • Observe que el valor humidity se anota como telemetría historized, por lo que cada lectura de humedad se almacena como una medición de serie temporal con un registro de hora timeObserved, en lugar de registrar solo el último valor.
    • También está validado para ser un integer en el rango 0–100. Solo el contenido de un componente se puede anotar como aviso histórico de esta declaración @type en el ejemplo siguiente.
    {
  "@type": ["Telemetry","Historized","Validated"],
  "name": "humidity",
  "schema": "integer",
  "minimum": 0,
  "maximum": 100
}
    En este modelo de climatización, dtdl-model-specifications.json
    • Este modelo se basa en la especificación DTDL v3 y contiene un identificador de modelo de gemelo digital (DTMI) como identificador único: @id: "dtmi:com:oracle:iot:sample:hvac:<unique-id>;1"
    • Este modelo de gemelo digital de ejemplo permite la historización, los tipos cualitativos y los contextos de extensión de validación. Consulte DTMI Validation Extension Reference.
    • Como se describe en el fragmento encima de la telemetría humidity se anota como Historized, por lo que las lecturas de humedad se conservan como datos de series temporales y lecturas a lo largo del tiempo.
    • La telemetría location se anota como Historized, por lo que los cambios en la ubicación también se conservan a lo largo del tiempo, registrando el historial de ubicaciones de la propiedad con una pista de auditoría.
    • La telemetría temperature no se anota con Historized, registrando solo el último valor conocido otra persistencia descendente configurada en otro lugar.
    • La propiedad serialNumber se marca como Validated mediante un patrón de expresión regular y no se anota como Histórico, por lo que solo se mantiene el valor actual o el último, no un seguimiento histórico de los cambios.
    {
  "@context": [
    "dtmi:dtdl:context;3",
    "dtmi:dtdl:extension:historization;1",
    "dtmi:dtdl:extension:quantitativeTypes;1",
    "dtmi:com:oracle:dtdl:extension:validation;1"
  ],
  "@id": "dtmi:com:oracle:iot:sample:hvac:UgNaNWHbzK;1",
  "@type": "Interface",
  "contents": [
    {
      "@type": [
        "Telemetry",
        "Temperature"
      ],
      "name": "temperature",
      "schema": "integer",
      "unit": "degreeFahrenheit"
    },
    {
      "@type": [
        "Telemetry",
        "Historized",
        "Validated"
      ],
      "name": "humidity",
      "schema": "integer",
      "minimum": 0,
      "maximum": 100
    },
    {
      "@type": [
        "Property",
        "Historized"
      ],
      "name": "location",
      "schema": "point",
      "writable": false
    },
    {
      "@type": [
        "Property",
        "Validated"
      ],
      "name": "serialNumber",
      "schema": "string",
      "pattern": "^([0-9]){2}([0-9]){5}([0-9]){6}$"
    }
  ]
}

    En este ejemplo de respuesta de la CLI, se muestra que el modelo de gemelo digital se creó para el dominio IoT, con un URI de DTMI: dtmi:com:oracle:iot:sample:hvac:unique-id;1:

    {
  "data": {
    "defined-tags": {
      "Oracle-Tags": {
        "CreatedBy": "default/user",
        "CreatedOn": "2025-08-05T17:43:00.438Z"
      }
    },
    "description": null,
    "display-name": "HVAC",
    "freeform-tags": {},
    "id": "<iot-digital-twin-model-OCID>",
    "iot-domain-id": "<iot-domain-OCID>",
    "lifecycle-state": "ACTIVE",
    "spec-uri": "dtmi:com:oracle:iot:sample:hvac:unique-id;1",
    "system-tags": {},
    "time-created": "2025-08-05T17:43:00.508000+00:00",
    "time-updated": "2025-08-05T17:43:00.508000+00:00"
  },
  "etag": "<unique-id>"
}

    Para obtener una lista completa de los parámetros y valores de los comandos de la CLI, consulte Referencia de comandos de la CLI.

  • Ejecute la operación CreateDigitalTwinModel para crear un modelo de gemelo digital en el dominio IoT específico.

    Ejemplo de solicitud:

    POST /20250531/digitalTwinModels
content-type: application/json+ld
{
    "@context": ["dtmi:dtdl:context;3"],
    "@id": "dtmi:com:oracle:labauto:SmartSpecimenVault;1",
    "@type": "Interface",
    "extends": "dtmi:com:oracle:iot:connectable;1",
    "displayName": "HVAC",
    "contents": [
        {"@type": "Telemetry", "name": "temperature", "schema": "integer"},
        {"@type": "Telemetry", "name": "humidity", "schema": "integer", "minimum":0, "maximum": 100},
        {"@type": "Property", "name": "desiredTemperature", "schema": "integer", "writable": false},
        {"@type": "Property", "name": "serialNumber", "schema": "string"} 
    ]
}

    Ejemplo de respuesta:

    header:
content-type: application/json
Body:
{
    "id": "<digital-twin-model-OCID>"
    "displayName": "<your-HVAC-display-name>",
    "description": "<digital-twin-model-for-HVAC>"
    "lifecycleState": "ACTIVE",
    "freeformTags": {},
    "definedTags": {
       "Oracle-Tags": {
         "CreatedBy": "default/user@oracle.com",
         "CreatedOn": "2024-07-22T10:24:53.446Z"
       }
    },
    "specUri": "dtmi:com:oracle:labauto:SmartSpecimenVault;1"
    "timeCreated": "2025-01-13T10:24:53Z",
    "timeUpdated": "2025-01-14T17:15:21Z"
}