Documentación de Oracle Cloud Infrastructure

Escenario: Envío de datos estructurados en un formato personalizado mediante HTTP

Utilice este escenario para enviar y supervisar datos estructurados desde un dispositivo en un formato personalizado. Si un dispositivo envía datos en un formato personalizado, significa que el dispositivo no se puede programar para cambiar su salida.

En este caso, defina la asignación personalizada de adaptadores gemelos digitales, para traducir los datos entrantes a un formato reconocido por la plataforma IoT.

Un administrador debe agregar una política a su arrendamiento y a los compartimentos que desea utilizar. Para ver ejemplos de políticas y requisitos previos, consulte Policy Details for the Internet of Things (IoT) Platform y IoT Prerequisites.

  1. Crear un grupo de dominios IoT y un dominio IoT
  2. Crear un modelo gemelo digital
  3. Crear un adaptador gemelo digital para un formato personalizado
  4. Crear una instancia de gemelo digital con un adaptador
  5. Enviar datos de telemetría
  6. Ver datos de telemetría

Paso 1: Crear un grupo de dominios IoT y un dominio IoT

Utilice un grupo de dominios IoT y un dominio IoT existentes o cree un grupo de dominios IoT y cree un dominio IoT para utilizarlo en este escenario.

Después de tener el grupo de dominios IoT y el dominio IoT que desea trabajar, siga estos pasos para configurar recursos de gemelos digitales para recibir datos estructurados en un formato personalizado desde un dispositivo. Todos los recursos IoT deben estar en la misma región.

Para obtener el <domain-short-id-from-device-host> para el dominio IoT o para obtener el OCID del dominio IoT, puede obtener los detalles del dominio IoT con el que desea trabajar.

Paso 2: Crear un modelo gemelo digital

  1. Cree especificaciones mediante el lenguaje de definición de gemelos digitales (DTDL) para su modelo gemelo digital similar a este ejemplo con los datos que desea recopilar.

    Para utilizar este ejemplo, guarde este fragmento de código como un archivo digital-twin-model.json y, a continuación, haga referencia a este archivo en el siguiente paso al crear un modelo de gemelo digital.

    Un modelo gemelo digital requiere un identificador de modelo gemelo digital (DTMI) como identificador único. Por ejemplo: dtmi:com:oracle:example:hvac;1

    {
  "@context": [
    "dtmi:dtdl:context;3"
  ],
  "@id": "dtmi:com:oracle:example:hvac;1",
  "@type": "Interface",
  "displayName": "HVAC",
  "description": "A digital twin model for HVAC",
  "contents": [
    {
      "@type": "Telemetry",
      "name": "temperature",
      "schema": "integer"
    },
    {
      "@type": "Telemetry",
      "name": "humidity",
      "schema": "integer"
    },
    {
      "@type": "Property",
      "name": "power",
      "schema": "boolean"
    },
    {
      "@type": "Property",
      "name": "batteryLevel",
      "schema": "integer"
    }
  ]
}
  2. Utilice el comando oci iot digital-twin-model create con el parámetro necesario para crear un modelo de gemelo digital. Sustituya <iot-domain-OCID> por el OCID del dominio IoT que desea asociar a este modelo de gemelo digital. Haga referencia al archivo digital-twin-model.json creado en el paso anterior o a un archivo de especificaciones para el escenario específico. Para obtener más información sobre la referencia a archivos, consulte Uso de un archivo de JSON para una entrada compleja:
    oci iot digital-twin-model create --iot-domain-id <iot-domain-OCID> --spec file://digital-twin-model.json
    Ejemplo de respuesta mediante el archivo digital-twin-model.json del paso anterior. En esta respuesta de ejemplo se muestra el URI de DTMI y el OCID del modelo gemelo digital IoT:
    {
  "data": {
    "defined-tags": {
      "Oracle-Tags": {
        "CreatedBy": "default/user@oracle.com",
        "CreatedOn": "2025-09-11T05:56:50.514Z"
      }
    },
    "description": "A digital twin model for HVAC",
    "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:example:hvac;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>"
}

Paso 3: Crear un adaptador gemelo digital para un formato personalizado

Si un dispositivo envía datos en un formato personalizado, significa que el dispositivo no se puede programar para cambiar su salida. En este caso, defina el formato personalizado en la asignación de adaptadores gemelos digitales,

Para ello, defina inbound-envelope y inbound-routes en un formato JSON para convertir los datos en un formato con el que desee trabajar en los servicios y aplicaciones de Oracle, de modo que pueda conectarse para ver los datos IoT en diferentes sistemas.

Uso de la CLI

  1. Defina un sobre de entrada file://inbound-envelope.json para especificar cómo extraer metadatos de la carga útil del dispositivo. Para extraer el valor en $.time del JSON entrante y asignarlo al campo timeObserved en el modelo de gemelo digital. Estas asignaciones permiten extraer metadatos específicos, como registros de hora, mediante expresiones JQ.

    En este ejemplo se muestra el punto final del dispositivo, una carga útil de ejemplo y una asignación de sobre entrante que aplica expresiones JQ para extraer o remodelar los datos.

    {
  "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. Cree un archivo file://inbound-routes.json para definir cómo se asignan y direccionan los datos de carga útil específicos de los mensajes de dispositivo a la instancia de gemelo digital.

    Cada ruta incluye una condición que coincide con el punto final, una estructura de carga útil de referencia y instrucciones de asignación para transferir o transformar valores.

    En este ejemplo se muestran 2 condiciones de carga útil definidas.
    Nota

    El máximo de rutas de entrada permitidas es 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. Utilice el comando oci iot digital-twin-adapter create para crear un adaptador gemelo digital. Sustituya <iot-domain-OCID> por el OCID del dominio IoT y sustituya <dtmi:com:oracle:example:hvac> por el URI de DTMI por el URI de DTMI para el modelo de gemelo digital que desea asociar a este adaptador de gemelo digital.

    En el siguiente ejemplo, se utiliza el parámetro URI de DTMI para asociar el modelo gemelo digital. También puede utilizar el parámetro --digital-twin-model-id con el <digital-twin-model-OCID> para el modelo de gemelo digital que desea asociar a este adaptador de gemelo digital.

    Haga referencia a los archivos file://inbound-enevelop.json y file://inbound-enevelop.json creados en el paso 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>
    En esta respuesta de ejemplo se muestra una asignación de carga útil personalizada definida en las opciones --inbound-envelope y --inbound-routes, haciendo referencia a los archivos json y un OCID de adaptador de gemelo digital específico asociado a un modelo de gemelo digital específico con un URI de DTMI único y un OCID de modelo de gemelo digital:

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

Paso 4: Crear una instancia gemela digital con el adaptador

Uso de la CLI

Utilice los parámetros necesarios oci iot digital-twin-instance create, <iot-domain-OCID> y <certificate-or-secret-OCID> para crear una instancia de gemelo digital. Sustituya <certificate-or-secret-OCID> por el OCID de secreto de almacén que desea utilizar y sustituya <iot-domain-OCID> por el OCID del dominio IoT de su entorno.

Si la instancia de gemelo digital está configurada para recibir datos de dispositivo, debe utilizar el parámetro de ID de autenticación con un OCID de certificado o secreto de almacén para que el gemelo digital se pueda autenticar. Para ello, cree un secreto o cree un certificado en la misma región y arrendamiento que cualquier otro recurso IoT relacionado.

En este ejemplo se utiliza la opción --display-name y se sustituye <your-digital-twin-instance-name> por un nombre fácil de recordar para la instancia de gemelo digital.

Sustituya <digital-twin-adapter-OCID> por el adaptador gemelo digital creado en el paso anterior. 
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>
Esta respuesta de ejemplo muestra el adaptador de gemelo digital y el URI de DTMI definidos para el modelo de gemelo digital asociado a esta instancia de gemelo digital.

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

Paso 5: Enviar datos de telemetría

Utilice el siguiente comando curl y <digital-twin-instance-external-key> para enviar o publicar datos. Para obtener más información, consulte Uso de cURL.

Según el tipo de datos que desee enviar, utilice el siguiente ejemplo para enviar telemetría:
curl -u 'digital-twin-instance-external-key:device-password' -H "content-type: application/json" https://<domain-short-id-from-device-host>.device.iot.<region>.oci.oraclecloud.com/telemetry/heartbeat -d '{"temp": 70, "hum": 55}'
Accepted%
curl -i -X POST \
     -u "<digital-twin-instance-external-key>:<device-password>" \
     -H "Content-Type: application/json" \
     "https://<domain-short-id-from-device-host>.device.iot.<region>.oci.oraclecloud.com/telemetry/heartbeat" \
     -d '{
           "digital_twin_instance_id": "<iot-digital-twin-instance-OCID>",
           "received_at": "2024-08-14T06:01:30.432829Z",
           "endpoint": "telemetry/heartbeat",
           "content_type": "application/json",
           "content": {
             "time": "<time>",
             "data": {
               "temp": 70,
               "hum": 65
             }
           }
         }'

Paso 6: Ver datos de telemetría

Uso de la API de datos de Internet of Things para obtener los datos

Si configuró el acceso a los datos de IoT mediante ORDS y tiene el token de autenticación necesario, puede utilizar la API de datos de Internet of Things para obtener los datos que desea supervisar.

En este ejemplo se utilizan HTTP. También puede utilizar MQTT y MQTT en WebSockets. Para ver ejemplos específicos, consulte Escenarios.

Sustituya las variables por los valores de su entorno:
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>\"}]}"

Utilizar sentencias SQL para ver los datos

Si configuró el acceso a la vista de datos directamente en la base de datos o si configuró el acceso para ver los datos en APEX, puede utilizar esta sentencia SQL para ver los datos de telemetría raw:
select * from <domain-short-id-from-device-host>__IOT.RAW_DATA where digital_twin_instance_id = '<iot-digital-twin-OCID>';
Nota

Observe que el nombre del esquema contiene dos caracteres de subrayado: __IOT

O bien, utilice esta sentencia SQL para ver los datos de telemetría rejected. Sustituya <domain-short-id-from-device-host> por el identificador corto de dominio para el dominio IoT y <iot-digital-twin-OCID> por el OCID del gemelo digital desde el que desea ver los datos rechazados:

select * from <domain-short-id-from-device-host>__IOT.REJECTED_DATA where digital_twin_instance_id = '<iot-digital-twin-OCID>';
O bien, utilice esta sentencia SQL para ver los datos de telemetría historizados. Sustituya <domain-short-id-from-device-host> por el ID corto de dominio para el dominio IoT y <iot-digital-twin-OCID> por el OCID para el gemelo digital del que desea ver los datos rechazados:
select * from <domain-short-id>__IOT.DIGITAL_TWIN_HISTORIZED_DATA where digital_twin_id = '<digital-twin-OCID>';