Documentação do Oracle Cloud Infrastructure

Cenário: Consultar um Relacionamento Digital Twin

Uma instância de gêmeo digital pode usar modelos de gêmeos digitais, adaptadores de gêmeos digitais, hierarquias e relacionamentos para criar um modelo virtual que represente um ambiente real.

Este cenário explica como você pode consultar um relacionamento de gêmeos digitais para responder a perguntas sobre um dispositivo, recursos, dados e conectividade, para monitorar um espaço físico e seus dispositivos. Neste cenário, um espaço é uma área física, por exemplo, uma sala de conferências. Isso é servido por um sensor Env-III que é um dispositivo localizado no espaço que mede as características ambientais, incluindo temperatura e umidade. Essa hierarquia e o relacionamento servedBy permitem que os aplicativos consultem:
  • Quais sensores servem um espaço específico?
  • Que telemetria é relatada por esses sensores?
  • Como os dispositivos são conectados, usando wi-fi?

Tarefas

  1. Criar um Modelo Digital Twin com um Modelo de Base de Capacidade
  2. Criar um Modelo Digital Twin para um Sensor
  3. Crie um Modelo Digital Twin para o Sensor Env-III
  4. Crie um Modelo Digital Twin para o Espaço
  5. Crie um Adaptador Digital Twin para o Espaço
  6. Crie um adaptador digital duplo para o sensor Env-III
  7. Criar uma Instância Digital Twin com um Adaptador para um Espaço
  8. Criar uma Instância Digital Twin com um Adaptador para um Sensor Env-III
  9. Criar um Relacionamento Digital Twin para Conectar as Instâncias Digital Twin
  10. Consultar o Digital Twin Relationship Graph usando SQL

Antes de Começar

Certifique-se de ter as permissões necessárias. Um administrador concede acesso criando as políticas necessárias. Para obter mais informações, consulte Pré-requisitos e Detalhes da Política da Plataforma Internet of Things (IoT).

Etapa 1: Criar um Modelo Digital Twin com um Modelo de Base de Capacidade

  1. Salve este trecho de código como um arquivo model_capability.json. Consulte esse arquivo na próxima etapa ao criar um modelo de gêmeo digital. Esta especificação de modelo define a capacidade e atua como um modelo base.

    Para obter mais informações sobre como fazer referência a arquivos, consulte Usando um Arquivo JSON para Entrada Complexa e crie um modelo de gêmeo 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. Use o comando e os parâmetros oci iot digital-twin-model create para criar um modelo de gêmeo digital com um modelo base de recurso.

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

    Este exemplo de resposta mostra que o modelo de gêmeo digital está ativo e faz referência ao URI DTMI definido no arquivo 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>"
}

Etapa 2: Criar um Modelo Digital Twin para um Sensor

  1. Salve este trecho de código como um arquivo model_sensor.json. Consulte este arquivo na próxima etapa para criar outro modelo de gêmeo digital. Esta é uma definição de sensor que herda as propriedades e estende o modelo base de capacidade.
    {
  "@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. Use este comando e parâmetros para definir as especificações para criar um modelo de gêmeo digital. 
    oci iot digital-twin-model create --iot-domain-id <iot-domain-OCID> --spec file://model_sensor.json

    Este exemplo de resposta mostra que o modelo de gêmeo digital está ativo e faz referência ao URI DTMI específico definido no arquivo 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>"
}

Etapa 3: Criar um Modelo Digital Twin para o Sensor Env-III

  1. Salve este trecho de código como um arquivo model_env.json. Consulte esse arquivo na próxima etapa ao criar outro modelo de gêmeo 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. Use este comando e parâmetros para definir as especificações para criar outro modelo de gêmeo digital. 
    oci iot digital-twin-model create --iot-domain-id <iot-domain-OCID> --spec file://model_env.json

    Este exemplo mostra que o modelo de gêmeo digital está ativo e faz referência ao URI DTMI específico definido no arquivo 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>"
}

Etapa 4: Criar um Modelo Digital Twin para o Espaço

  1. Salve este trecho de código como um arquivo model_space.json e faça referência a ele na próxima etapa ao criar um modelo de gêmeo digital para o espaço. O espaço é servedBy o modelo do 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. Use o comando a seguir para criar um modelo de gêmeo digital que faça referência ao file://model_space.json para aplicar as especificações definidas no arquivo a esse modelo de gêmeo digital. 
    oci iot digital-twin-model create --iot-domain-id <iot-domain-OCID> --spec file://model_space.json

    Este exemplo de resposta mostra que o modelo de gêmeo digital está ativo e faz referência a este URI DTMI específico definido no arquivo 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>"
}

Etapa 5: Criar um Adaptador Digital Twin para o Espaço

Use este comando para criar um adaptador de gêmeo digital e para associar a especificação do modelo de gêmeo digital ao URI DTMI do espaço.

Ao criar um adaptador de gêmeo digital, você pode forçar o sistema a criar um payload e mapeamentos padrão, não especificando as opções inbound-envelope ou inbound-routes.

Se o mapeamento de envelope não for especificado e contiver um timeObserved, receivedTime será usado 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"
Este exemplo de resposta mostra um OCID de adaptador de gêmeo digital específico e que ele está associado a um modelo de gêmeo digital específico e ao URI 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>"
}

Etapa 6: Criar um Adaptador Digital Twin para o Sensor Env-III

Use este comando para criar um adaptador de gêmeo digital e associar a especificação do modelo de gêmeo digital ao URI DTMI para o 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"
Este exemplo de resposta mostra um OCID de adaptador de gêmeo digital específico e está associado a um modelo de gêmeo digital específico e DTMI.

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

Etapa 7: Criar uma Instância Digital Twin com um Adaptador para um Espaço

Use este comando para criar uma instância de gêmeo digital com um nome para exibição que use um segredo para autenticação e esteja associado a um modelo de gêmeo digital específico e a um adaptador de gêmeo digital. Para obter informações sobre como criar um segredo de vault, consulte Criando um Segredo. 
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>
Este exemplo de resposta mostra o OCID da instância de gêmeo digital específico e seu adaptador de gêmeo digital associado, modelo de gêmeo digital, o ID da chave externa e inclui o URI DTMI específico definido para o espaço:

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

Etapa 8: Criar uma Instância Digital Twin com um Adaptador para um Sensor Env-III

Use este comando para criar uma instância de gêmeo digital com um nome para exibição que use um segredo para autenticação e esteja associado a um modelo de gêmeo digital específico, adaptador de gêmeo digital e domínio IoT. Substitua os OCIDs pelos recursos IoT relacionados do seu ambiente.

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>"
Este exemplo de resposta mostra que a instância de gêmeo digital está ativa e contém o modelo de gêmeo digital relacionado e o adaptador de gêmeo 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>"
}

Etapa 9: Criar um Relacionamento Digital Twin para Conectar duas Instâncias Digital Twin

Use este comando para criar um relacionamento de gêmeo digital entre duas instâncias de gêmeo digital e definir o caminho do conteúdo como servedBy, o tipo de conexão como wi-fi e o nome para exibição desse relacionamento de gêmeo 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"
Este exemplo de resposta mostra o caminho de conteúdo e as instâncias de gêmeos digitais relacionadas para este relacionamento de gêmeos digitais:
{
  "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>"
}

Etapa 10: Consultar o Gráfico de Relacionamento Digital Twin usando SQL

Se quiser usar consultas SQL para exibir seus dados IoT no APEX ou diretamente no banco de dados que exija configuração de uma conexão com o APEX ou configuração de uma conexão direta com o banco de dados.

No APEX ou diretamente no banco de dados, use as seguintes instruções SQL para localizar os detalhes do relacionamento de gêmeos digitais de uma instância de gêmeos digitais específica. Substitua o <domain-short-id-from-device-host> pelo id curto do domínio do host do dispositivo. Substitua o <digital-twin-instance-OCID> pelo OCID da instância do gêmeo digital com o qual você deseja trabalhar:

Observação

Observe dois sublinhados em __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 localizar os relacionamentos entre duas instâncias de gêmeos digitais, use a consulta a seguir. Substitua o FROM_DIGITAL-TWIN-INSTANCE-OCID pelo OCID da instância do gêmeo digital de origem e o TO_DIGITAL-TWIN-INSTANCE-OCID pelo OCID da instância do gêmeo digital de destino para o qual você deseja encontrar o caminho de conteúdo:

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