Scenario: Sending Structured Data in a Default Format using HTTPs

Use the oci iot digital-twin-adapter create command to create a digital twin adapter. Replace the <iot-domain-OCID> with your IoT domain OCID. To associate the digital twin model, use either the DTMI URI parameter --digital-twin-model-spec-urior the digital twin OCID --digital-twin-model-id parameter to associate the digital twin model to this digital twin adapter.

This example uses the command with the --digital-twin-model-spec-uri parameter. Replace the dtmi:com:oracle:example:hvac;1 with the DTMI URI for the digital twin model you want to associate to this digital twin adapter:

oci iot digital-twin-adapter create --iot-domain-id <iot-domain-OCID> --digital-twin-model-spec-uri "dtmi:com:oracle:example:hvac;1"

oci iot digital-twin-adapter create --iot-domain-id <iot-domain-OCID> --digital-twin-model-id <digital-twin-model-OCID>

{
  "data": {
    "defined-tags": {
      "Oracle-Tags": {
        "CreatedBy": "default/user",
        "CreatedOn": "2025-09-10T17:45:41.318Z"
      }
    },
    "description": null,
    "digital-twin-model-id": "<digital-twin-model-OCID>",
    "digital-twin-model-spec-uri": "dtmi:com:oracle:example:hvac;1",
    "display-name": "<your-digital-twin-adapter-name>",
    "freeform-tags": {},
    "id": "<digital-twin-adapter-OCID>",
    "inbound-envelope": {
      "envelope-mapping": {
        "time-observed": "$.time"
      },
      "reference-endpoint": "/",
      "reference-payload": {
        "data": {
          "humidity": 0,
          "location": {
            "coordinates": [0.0, 0.0],
            "type": "Point"
          },
          "temperature": 0,
          "time": "2025-09-10T17:45:41.387069258Z"
        },
        "data-format": "JSON"
      }
    },
    "inbound-routes": [
      {
        "condition": "*",
        "description": "Default condition",
        "payload-mapping": {
          "$.humidity": "$.humidity",
          "$.location": "$.location",
          "$.temperature": "$.temperature"
        },
        "reference-payload": null
      }
    ],
    "iot-domain-id": "<iot-domain-OCID>",
    "lifecycle-state": "ACTIVE",
    "system-tags": {},
    "time-created": "2025-09-10T17:45:41.389000+00:00",
    "time-updated": "2025-09-10T17:45:41.389000+00:00"
  },
  "etag": "<unique-id>"
}

Use the oci iot digital-twin-instance create and the <iot-domain-OCID>, the <vault-secret-OCID>, and the <digital-twin--adapter-OCID> required parameters to create a digital twin instance for structured data.

Replace the <iot-domain-OCID> with the OCID for your IoT domain you want to update. Optionally, you can include the display parameter and replace the <display-name> with a user friendly name for the digital twin instance.

Replace the <digital-twin--adapter-OCID> with the digital twin adapter OCID created in the previous step. Replace the <vault-secret-OCID> with a secret that's in the same region as your other digital twin resources. Oracle recommends using a unique secret for each digital twin instance. For more information, see Creating a Secret.

oci iot digital-twin-instance create --iot-domain-id <iot-domain-OCID> --display-name <display_name> --auth-id <vault-secret-OCID> --digital-twin-adapter-id <digital-twin-adapter-OCID>

{
  "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:hvac;1",
    "display-name": "your display name",
    "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>"
}

For more information, see the Internet of Things (IoT) Data API documentation.

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

This example uses HTTPs. Alternatively, you can use MQTT and MQTT over WebSockets. For specific examples, see Scenarios.

Use this SQL statement to view the rejected telemetry data. Replace the <domain-short-id-from-device-host> with the domain short id from your device host, and replace the <digital-twin-OCID> with the digital twin's OCID that you want to view the rejected data from:

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

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

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

To get the <domain-short-id-from-device-host> for the IoT domain, get the details for the IoT domain you want to work with.