Cenário: Enviando Dados Estruturados em um Formato Personalizado usando HTTPs

1. Defina um envelope de entrada file://inbound-envelope.json para especificar como extrair metadados do payload do dispositivo. Para extrair o valor em $.time do JSON de entrada e mapeá-lo para o campo timeObserved no modelo de gêmeo digital. Esses mapeamentos permitem extrair metadados específicos, como timestamps, usando expressões de JQ.

   Este exemplo mostra o ponto final do dispositivo, um payload de amostra e um mapeamento de envelope de entrada que aplica expressões JQ para extrair ou remodelar os dados.

   {
     "reference-endpoint": "telemetry/health",
     "reference-payload": {
       "dataFormat": "JSON",
       "data": {
         "time": "<timestamp>",
         "data": {
           "temp": 0,
           "hum": 0,
           "power": false,
           "batteryLevel": 0
         }
       }
     },
     "envelope-mapping": {
       "timeObserved": "$.time"
     }
   }

2. Crie um arquivo file://inbound-routes.json para definir como os dados de payload específicos das mensagens do dispositivo são mapeados e roteados para sua instância de gêmeo digital.

   Cada rota inclui uma condição que corresponde ao ponto final, uma estrutura de payload de referência e instruções de mapeamento para transferir ou transformar valores.

   Este exemplo mostra 2 condições de carga útil definidas.
   Observação
   
   O máximo de rotas de entrada permitidas é 128.

   [
     {
       "condition": "${endpoint(2) == \"heartbeat\"}",
       "reference-payload": {
         "data": {
           "temp": 75,
           "hum": 62
         }
       },
       "payload-mapping": {
         "$.temperature": "$.data.temp",
         "$.humidity": "${.data.hum - 5}"
       }
     },
     {
       "condition": "${endpoint(2) == \"health\"}",
       "reference-payload": {
         "data": {
           "power": false,
           "batteryLevel": 60
         }
       },
       "payload-mapping": {
         "$.power": "$.data.power",
         "$.batteryLevel": "${.data.batteryLevel - 5}"
       }
     }
   ]

3. Use o comando oci iot digital-twin-adapter create para criar um adaptador de gêmeo digital. Substitua o <iot-domain-OCID> pelo OCID do seu domínio IoT e substitua o <dtmi:com:oracle:example:hvac> pelo URI DTMI pelo URI DTMI do modelo de gêmeo digital que você deseja associar a este adaptador de gêmeo digital.

   O exemplo a seguir usa o parâmetro DTMI URI para associar o modelo de gêmeo digital. Como alternativa, você pode usar o parâmetro --digital-twin-model-id com o <digital-twin-model-OCID> para o modelo de gêmeo digital que deseja associar a este adaptador de gêmeo digital.

   Consulte os arquivos file://inbound-enevelop.json e file://inbound-enevelop.json criados na etapa anterior.

   oci iot digital-twin-adapter create --iot-domain-id <iot-domain-OCID> --digital-twin-model-spec-uri 'dtmi:com:oracle:example:hvac;1' --inbound-envelope <file://inbound-enevelop.json> --inbound-routes <file://inbound-routes.json>

   Este exemplo de resposta mostra um mapeamento de payload personalizado definido nas opções --inbound-envelope e --inbound-routes, fazendo referência a arquivos json e a um OCID de adaptador de gêmeo digital específico associado a um modelo de gêmeo digital específico com um URI DTMI exclusivo e um OCID de modelo de gêmeo digital exclusivo:

   dtmi:com:oracle:example:core:hvac: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:hvac;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": "telemetry/health",
         "reference-payload": {
           "data": {
             "time": "2025-09-11T06:09:27.878106Z"
           },
           "data-format": "JSON"
         }
       },
       "inbound-routes": [
         {
           "condition": "${endpoint(2) == \"heartbeat\"}",
           "description": null,
           "payload-mapping": {
             "$.humidity": "${.hum-1}",
             "$.temperature": "$.temp"
           },
           "reference-payload": {
             "data": {
               "hum": 62,
               "temp": 75
             },
             "data-format": "JSON"
           }
         },
         {
           "condition": "${endpoint(2) == \"health\"}",
           "description": null,
           "payload-mapping": {},
           "reference-payload": {
             "data": {
               "batteryPercentage": 60,
               "on": false
             },
             "data-format": "JSON"
           }
         }
       ],
       "iot-domain-id": "<iot-domain-OCID>",
       "lifecycle-state": "ACTIVE",
       "system-tags": {},
       "time-created": "2025-09-30T19:55:36.293000+00:00",
       "time-updated": "2025-09-30T19:55:36.293000+00:00"
     },
     "etag": "<unique-id>"
   }
   

Use os parâmetros necessários oci iot digital-twin-instance create, <iot-domain-OCID> e <certificate-or-secret-OCID> para criar uma instância de gêmeo digital. Substitua o <certificate-or-secret-OCID> pelo OCID do segredo do vault que você deseja usar e substitua o <iot-domain-OCID> pelo OCID do domínio IoT do seu ambiente.

Se a instância do gêmeo digital estiver configurada para receber dados do dispositivo, use o parâmetro de ID de autenticação com um segredo de vault ou OCID de certificado para que o gêmeo digital possa se autenticar. Para fazer isso, crie um segredo ou crie um certificado na mesma região e tenancy que qualquer outro recurso relacionado do IoT.

Este exemplo usa a opção --display-name, substitua <your-digital-twin-instance-name> por um nome amigável para sua instância de gêmeo digital.

oci iot digital-twin-instance create --iot-domain-id <iot-domain-OCID> --display-name <your-digital-twin-instance-name> --auth-id <certificate-or-secret-OCID> --digital-twin-adapter-id <digital-twin-adapter-OCID>

dtmi:com:oracle:example:hvac;1

{
  "data": {
    "auth-id": "<vault-secret-OCID>",
    "defined-tags": {
      "Oracle-Tags": {
        "CreatedBy": "default/user@oracle.com",
        "CreatedOn": "2025-08-14T17:41:11.973Z"
      }
    },
    "description": null,
    "digital-twin-adapter-id": "<iot-digital-twin-adapter-OCID>",
    "digital-twin-model-id": "<digital-twin-model-OCID>",
    "digital-twin-model-spec-uri": "dtmi:com:oracle:example:hvac;1",
    "display-name": "<your-digital-twin-instance-name>",
    "external-key": "<digital-twin-instance-external-key>",
    "freeform-tags": {},
    "id": "<digital-twin-instance-OCID>",
    "iot-domain-id": "<iot-domain-OCID>",
    "lifecycle-state": "ACTIVE",
    "system-tags": {},
    "time-created": "2025-08-14T17:41:13.638000+00:00",
    "time-updated": "2025-08-14T17:41:13.638000+00:00"
  },
  "etag": "<unique-id>"
}

Este exemplo usa HTTPs. Como alternativa, você pode usar MQTT e MQTT em WebSockets. Para obter exemplos específicos, consulte Cenários.

curl -H "Authorization: Bearer <token>" \
     -X GET "https://<domain-group-short-id>.data.iot.<region>.oci.oraclecloud.com/ords/<domain-short-id>/20250531/rawData?q={\"$and\":[{\"digital_twin_instance_id\":\"<iot-digital-twin-OCID>\"}]}"

select * from <domain-short-id-from-device-host>__IOT.RAW_DATA where digital_twin_instance_id = '<iot-digital-twin-OCID>';

Ou use esta instrução SQL para exibir os dados de telemetria rejected. Substitua o <domain-short-id-from-device-host> pelo ID abreviado do domínio do domínio IoT e o <iot-digital-twin-OCID> pelo OCID do gêmeo digital do qual você deseja exibir dados rejeitados:

select * from <domain-short-id-from-device-host>__IOT.REJECTED_DATA where digital_twin_instance_id = '<digital-twin-OCID>';

select * from <domain-short-id-from-device-host>__IOT.HISTORIZED_DATA where digital_twin_id = '<digital-twin-OCID>';