Documentação do Oracle Cloud Infrastructure

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 é baseado nas especificações DTDL v3.

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

Observação

Digital Twins Definition Language (DTDL) v3 é suportado no GitHub pelo Digital Twin Consortium. Importante observar:
  • Extensões MQTT e propriedades graváveis não são suportadas. Se uma propriedade writable for incluída, ela deverá ser definida como false.
  • Somente o content dentro do componente pode ser anotado como historized, indicando que a plataforma IoT deve manter a telemetria de série temporal desse sensor. Consulte o exemplo de modelo de gêmeo digital dtdl-model-specifications.json abaixo.

Se quiser criar uma instância de gêmeo digital sem dados ingeríveis de um dispositivo, você poderá criar uma instância de gêmeo digital sem um adaptador de gêmeo digital e sem o parâmetro de ID de autenticação, --auth-id. O modelo de gêmeo digital associado não deve conter telemetria ou propriedades. Depois, você cria uma instância de gêmeo digital e pode criar um relacionamento de gêmeo digital para simular seu ambiente IoT sem a complexidade dos dados ou da autenticação.

    1. Na página de lista Domínios IoT, selecione o domínio IoT com o qual você deseja trabalhar. Se precisar de ajuda para localizar a página de lista de domínios IoT, consulte Listando Domínios IoT.
    2. Selecione a guia Modelos gêmeos digitais e selecione Criar.
    3. Informe um Nome e, opcionalmente, uma Descrição amigável ao usuário. Evite digitar informações confidenciais.
    4. Selecione uma opção para adicionar a especificação DTDL do modelo:
      • Para fazer upload do arquivo dtdl-specification.json, selecione fazer upload da especificação. Arraste e solte ou selecione um arquivo .json com a especificação DTDL para este modelo de gêmeo digital.
      • Para adicionar o JSON do modelo de gêmeo digital, selecione colar especificação.
    5. Tags: (Opcional) Adicione uma ou mais tags ao modelo de gêmeo digital. Se você tiver permissões para criar um recurso, também terá permissões para aplicar tags de formato livre a esse recurso. Para aplicar uma tag definida, você deverá ter permissões para usar o namespace de tag. Para obter mais informações sobre tags, consulte Tags de Recurso. Se você não tiver certeza se deseja aplicar tags, ignore essa opção ou pergunte a um administrador. Você pode aplicar as tags posteriormente.
    6. Selecione Criar.

    Veja os detalhes do modelo de gêmeo digital. Copie o OCID do domínio IoT associado, o modelo de gêmeo digital DTMI ou o OCID do modelo duplo digital.

    Selecione a guia relacionada para exibir a especificação DTDL, as Instâncias de gêmeos digitais associadas, os Adaptadores de gêmeos digitais associados ou as Tags desse modelo de gêmeos digitais.

  • 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:

    Exemplo em linha: 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}$"}]}'

    Exemplo de referência de arquivo: Este exemplo mostra como criar um arquivo dtdl-model-specifications.json que contenha suas especificações, como fazer referência ao arquivo .json no comando. O formato pode variar com base no seu sistema operacional 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-model-specifications.json
    Neste trecho de código do exemplo de modelo de gêmeo digital abaixo:
    • Observe que o valor humidity é anotado como telemetria historized, de modo que cada leitura de umidade é armazenada como uma medição de série temporal com um timestamp timeObserved, em vez de apenas gravar o valor mais recente.
    • Também é validado para ser um integer na faixa 0–100. Somente o conteúdo dentro de um componente pode ser anotado como aviso histórico desta declaração @type no exemplo abaixo.
    {
  "@type": ["Telemetry","Historized","Validated"],
  "name": "humidity",
  "schema": "integer",
  "minimum": 0,
  "maximum": 100
}
    Neste modelo HVAC, dtdl-model-specifications.json
    • Esse modelo é baseado na especificação DTDL v3 e contém um Identificador de Modelo Digital Twin (DTMI) como um identificador exclusivo: @id: "dtmi:com:oracle:iot:sample:hvac:<unique-id>;1"
    • Este exemplo de modelo de gêmeo digital permite a historização, os tipos qualitativos e os contextos de extensão de validação. Consulte Referência de Extensão de Validação DTMI.
    • Conforme descrito no trecho de código acima da telemetria humidity é anotada como Historized, de modo que as leituras de umidade são retidas como dados de série temporal, leituras ao longo do tempo.
    • A telemetria location é anotada como Historized, portanto, as alterações no local também são retidas ao longo do tempo, registrando o histórico de locais da propriedade com uma trilha de auditoria.
    • A telemetria temperature não é anotada com Historized, registrando apenas o último valor conhecido; outra persistência downstream foi configurada em outro lugar.
    • A propriedade serialNumber é marcada como Validated usando um padrão regex e não é anotada como Historizada; portanto, apenas o valor atual ou mais recente é mantido e não um rastreamento histórico de alterações.
    {
  "@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 da CLI 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": false},
        {"@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"
}