Criando um Modelo Digital Twin

Crie um modelo de gêmeo digital para sua Internet of Things (IoT).

Um modelo de gêmeo digital define a semântica de um gêmeo digital e se baseia nas especificações DTDL v3. Um modelo de gêmeo digital usa um Digital Twin Model Identifier (DTMI) como um identificador exclusivo.

Por exemplo: dtmi:com:oracle:iot:connectable;1

Uma instância de gêmeo digital requer um modelo de gêmeo digital e um adaptador de gêmeo digital para receber dados de dispositivo estruturado. Para obter exemplos específicos, consulte Cenários.

Observação

O Digital Twins Definition Language (DTDL) v3 é suportado no GitHub pelo Digital Twin Consortium. É importante observar que as extensões MQTT e as propriedades graváveis não são suportadas.

Se uma propriedade writable for incluída, ela deverá ser definida como false.

Use o comando oci iot digital-twin-model create e os parâmetros necessários para criar um modelo de gêmeo digital em um domínio IoT específico. Forneça as especificações como conteúdo JSON diretamente na linha de comando ou como um arquivo referenciado na linha de comando:

Este exemplo mostra como fornecer as especificações JSON diretamente na linha de comando:

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}$"}]}'

Este exemplo mostra como criar um arquivo dtdl-specifications.json que contenha as suas especificações e faça referência ao arquivo no comando. Para obter mais informações sobre como fazer referência a arquivos, consulte Usando um Arquivo JSON para Entrada Complexa:

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

Arquivo de exemplo dtdl-specifications.json baseado na especificação DTDL v3 que contém um Identificador de Modelo Digital Twin (DTMI) como um identificador exclusivo.

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

Este exemplo de resposta mostra que o modelo de gêmeo digital foi criado para o domínio IoT, com um URI 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 obter uma lista completa de parâmetros e valores para comandos CLI, consulte Referência de Comando da CLI

Execute a operação CreateDigitalTwinModel para criar um modelo de gêmeo digital no domínio IoT específico.

Exemplo de solicitação:

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": true},
        {"@type": "Property", "name": "serialNumber", "schema": "string"} 
    ]
}

Exemplo de resposta:

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

Documentação do Oracle Cloud Infrastructure

Criando um Modelo Digital Twin