Scenario: Sending Unstructured Data Using HTTPs

This scenario explains how to use the Internet of Things Platform to connect a device to send unstructured telemetry data to the cloud using HTTPs, and how to view the data in APEX.

  1. Create an IoT domain group
  2. Create an IoT domain
  3. Create a digital twin instance
  4. Send data
  5. Configure IoT domain to access APEX
  6. Access IoT data in APEX

For each device you want to connect to your Internet of Things, complete the following steps:

Step 1: Create an IoT Domain Group

Use the oci iot domain-group create command and the <compartment-OCID> and the <domain-group-name> required parameters to create an IoT domain group in a specific compartment. Replace the <compartment-OCID>, with the OCID for the compartment where you want to create the domain group. Replace the <domain-group-name> with your domain group name, and optionally replace the <your-sample-description> with a description:

oci iot domain-group create --compartment-id <compartment-OCID> --display-name <domain-group-name> --description <your-sample-description>

Creating a IoT domain group can take a few minutes. This example response shows the domain group is creating and uses this data host URL:

wtmn2xs4ifkba.data.iot.us-phoenix-1.oci.oraclecloud.com

domain group short id: wtmn2xs4ifkba

data-host:<domain-group-short-id>.data.iot.<region>.oci.oraclecloud.com

{
  "data": {
    "compartment-id": "<compartment-OCID>",
    "data-host": "wtmn2xs4ifkba.data.iot.<region>.oci.oraclecloud.com",
    "db-allow-listed-vcn-ids": null,
    "db-connection-string": null,
    "db-token-scope": null,
    "defined-tags": {
      "Oracle-Tags": {
        "CreatedBy": "default/user@oracle.com",
        "CreatedOn": "2025-08-14T16:43:02.950Z"
      }
    },
    "description": "<your-domain-group-description>",
    "display-name": "<your-domain-group-name>",
    "freeform-tags": {},
    "id": "<domain-group-OCID>",
    "lifecycle-state": "CREATING",
    "system-tags": {},
    "time-created": "2025-08-14T16:43:03.307000+00:00",
    "time-updated": "2025-08-14T16:43:03.307000+00:00"
  },
  "etag": "<unique-id>",
  "opc-work-request-id": "<work-request-OCID>"
}
        
Optional step: Get Work Request Updates when Creating an IoT Domain Group
Optional. During the time it takes to create the domain group, use the oci iot work-request get command and required parameter to get the work request updates for the creating a domain group process. Replace the <work-request-id> with the work request OCID from the creating an IoT domain group response:
oci iot work-request get --work-request-id <work-request-OCID>

This example response shows the creating a domain group operation is in progress.

{
  "data": {
    "compartment-id": "<compartment-OCID>",
    "id": "<work-request-OCID>",
    "operation-type": "CREATE_IOT_DOMAIN_GROUP",
    "percent-complete": 50.0,
    "resources": [
      {
        "action-type": "IN_PROGRESS",
        "entity-type": "iotDomainGroup",
        "entity-uri": "/20250531/iotDomainGroups/<iot-domain-group-OCID>",
        "identifier": "<work-request-OCID>",
        "metadata": null
      }
    ],
    "status": "ACCEPTED",
    "time-accepted": "2025-08-14T16:43:03.327000+00:00",
    "time-finished": null,
    "time-started": null,
    "time-updated": "2025-08-14T16:43:22.121000+00:00"
  },
  "etag": "<unique-id>"
}
        
Optional Step: List Work Request Errors when Creating an IoT Domain Group
Optional. During the time it takes to create the domain group, if you want to check for errors you can use the oci iot work-request list-errors command and the required parameter to list any work requests errors for the process of creating a domain group:
oci iot work-request list-errors --work-request-id <work-request-OCID>
Example response:
{
  "data": {
    "items": []
  }
}
Optional Step: List Work Request Logs when Creating an IoT Domain Group
Optional. During the time it takes to create the domain group, if you want to list the logs entries you can use the oci iot work-request list-logs command and the required parameter to list log entries for the work request:
oci iot work-request list-logs --work-request-id <work-request-OCID>

This example response shows the steps to create the IoT domain group and that it's finishing:

{
  "data": {
    "items": [
      {
        "message": "Generating database credentials",
        "timestamp": "2025-08-14T16:43:12.150000+00:00"
      },
      {
        "message": "Creating database",
        "timestamp": "2025-08-14T16:43:18.156000+00:00"
      },
      {
        "message": "Provisioning database",
        "timestamp": "2025-08-14T16:43:22.121000+00:00"
      },
      {
        "message": "Enabling data guard",
        "timestamp": "2025-08-14T16:48:25.138000+00:00"
      },
      {
        "message": "Configuring admin secret rotation ",
        "timestamp": "2025-08-14T16:53:59.878000+00:00"
      },
      {
        "message": "Generating DNS record(s)",
        "timestamp": "2025-08-14T16:54:05.318000+00:00"
      },
      {
        "message": "Configuring routing policy",
        "timestamp": "2025-08-14T16:54:06.455000+00:00"
      },
      {
        "message": "Finishing work request",
        "timestamp": "2025-08-14T16:54:58.139000+00:00"
      }
    ]
  }
}
Optional Step: Get Work Request to Confirm Creating IoT Domain Group Completed
  1. Optional. Use the oci iot work-request get command and the required parameter to get the work request update for the domain group. Replace the <work-request-id> with the work request OCID:
    oci iot work-request get --work-request-id <work-request-OCID>

    This example response shows creating the IoT domain group is successful.

    {
      "data": {
        "compartment-id": "<compartment-OCID>",
        "id": "<work-request-OCID>",
        "operation-type": "CREATE_IOT_DOMAIN_GROUP",
        "percent-complete": 100.0,
        "resources": [
          {
            "action-type": "CREATED",
            "entity-type": "iotDomainGroup",
            "entity-uri": "/20250531/iotDomainGroups/<domain-group-OCID>",
            "identifier": "<domain-group-OCID>",
            "metadata": null
          }
        ],
        "status": "SUCCEEDED",
        "time-accepted": "2025-08-14T16:43:03.327000+00:00",
        "time-finished": "2025-08-14T16:54:58.139000+00:00",
        "time-started": "2025-08-14T16:43:12.131000+00:00",
        "time-updated": "2025-08-14T16:54:58.139000+00:00"
      },
      "etag": "<unique-id>"
    }
    

Optional Step: Get the IoT Domain Group Details

Use the oci iot domain-group get command and the required parameter to get the IoT domain group details including the domain group's database connection details, if configured. Replace the <iot-domain-group-OCID> with the OCID for your IoT domain group:

oci iot domain-group get --iot-domain-group-id <iot-domain-group-OCID>
This example response shows the domain group is active, "lifecycleState": "ACTIVE" and uses the following data host: wtmn2xs4ifkba.data.iot.us-phoenix-1.oci.oraclecloud.com. In this example, the wtmn2xs4ifkba is the IoT domain group short id.
{
  "data": {
    "compartment-id": "<compartment-OCID>",
    "data-host": "wtmn2xs4ifkba.data.iot.<region>.oci.oraclecloud.com",
    "db-allow-listed-vcn-ids": null,
    "db-connection-string": null,
    "db-token-scope": null,
    "defined-tags": {
      "Oracle-Tags": {
        "CreatedBy": "default/user@oracle.com",
        "CreatedOn": "2025-08-14T16:43:02.950Z"
      }
    },
    "description": "This is a sample domain group",
    "display-name": "Sample Domain Group",
    "freeform-tags": {},
    "id": "<iot-domain-group-OCID>",
    "lifecycle-state": "ACTIVE",
    "system-tags": {},
    "time-created": "2025-08-14T16:43:03.307000+00:00",
    "time-updated": "2025-08-14T16:54:58.187000+00:00"
  },
  "etag": "<unique-id>"
}

Step 2: Create an IoT Domain

Use the oci iot domain create command and the required <domain-group-OCID> and <compartment-OCID> parameters to create an Internet of Things domain. Replace the <domain-group-OCID> with the OCID for the domain group that you want to associate with this IoT domain. Replace <your-sample-description> with a description for your IoT domain.

oci iot domain create --compartment-id <compartment-OCID> --iot-domain-group-id <domain-group-OCID> --display-name <your-iot-domain-name> --description <your-iot-domain-description>

Creating a domain can take a few minutes. In this example response, you see the device host URL with the domain short id:

"device-host": "cuay2mrhlgrrg.device.iot.<region>.oci.oraclecloud.com"

domain short id: cuay2mrhlgrrg

"device-host": "<domain-short-id>.device.iot.<region>.oci.oraclecloud.com"

{
  "data": {
    "compartment-id": "<compartment-OCID>",
    "data-retention-periods-in-days": {
      "historized-data": 30,
      "raw-command-data": 16,
      "raw-data": 16,
      "rejected-data": 16
    },
    "db-allow-listed-identity-group-names": null,
    "db-allowed-identity-domain-host": null,
    "defined-tags": {
      "Oracle-Tags": {
        "CreatedBy": "default/user@oracle.com",
        "CreatedOn": "2025-08-14T16:57:03.140Z"
      }
    },
    "description": "<your-iot-domain-description>",
    "device-host": "cuay2mrhlgrrg.device.iot.<region>.oci.oraclecloud.com",
    "display-name": "<your-iot-domain-name>",
    "freeform-tags": {},
    "id": "<iot-domain-OCID>",
    "iot-domain-group-id": "<iot-domain-group-OCID>",
    "lifecycle-state": "CREATING",
    "system-tags": {},
    "time-created": "2025-08-14T16:57:03.384000+00:00",
    "time-updated": "2025-08-14T16:57:03.384000+00:00"
  },
  "etag": "<unique-id>",
  "opc-work-request-id": "<work-request-OCID>"
}
Optional Step: Get Work Request when Creating an IoT Domain

Optional. During the time it takes to create the domain, use the oci iot work-request get command and the required parameter to get the work request update for creating the domain. Replace the <work-request-id> with the work request id from the previous response:

oci iot work-request get --work-request-id <work-request-OCID>

The example response shows the create an IoT domain is accepted and in progress.

{
  "data": {
    "compartment-id": "<iot-domain-OCID>",
    "id": "<work-request-OCID>",
    "operation-type": "CREATE_IOT_DOMAIN",
    "percent-complete": 50.0,
    "resources": [
      {
        "action-type": "IN_PROGRESS",
        "entity-type": "iotDomain",
        "entity-uri": "/20250531/iotDomains/<iot-domain-OCID>",
        "identifier": "<iot-domain-OCID>",
        "metadata": null
      }
    ],
    "status": "ACCEPTED",
    "time-accepted": "2025-08-14T16:57:03.413000+00:00",
    "time-finished": null,
    "time-started": null,
    "time-updated": "2025-08-14T16:57:23.124000+00:00"
  },
  "etag": "<unique-id>"
}
Optional Step: Get Work Request Logs
Optional. During the time it takes to create the domain, if you want to list the log entries for the work request you can use the oci iot work-request list-logs command and the required parameter to list log entries for the create an IoT domain work request:
oci iot work-request list-logs --work-request-id <work-request-OCID>

This example response shows the steps to create the IoT domain and that it's finishing:

{
  "data": {
    "items": [
      {
        "message": "Generating DNS record(s)",
        "timestamp": "2025-08-14T16:57:22.148000+00:00"
      },
      {
        "message": "Onboarding domain schema(s)",
        "timestamp": "2025-08-14T16:57:23.124000+00:00"
      },
      {
        "message": "Successfully onboarded domain schemas",
        "timestamp": "2025-08-14T16:58:43.508000+00:00"
      },
      {
        "message": "Finishing work request",
        "timestamp": "2025-08-14T16:58:43.771000+00:00"
      }
    ]
  }
}
Optional Step: Get Work Request when Creating IoT Domain
Optional. Use the oci iot work-request get command and required parameters to get the work request update for creating the domain. Replace the <work-request-id> with the work request OCID:
oci iot work-request get --work-request-id <work-request-OCID>

This example response shows creating the IoT domain succeeded.

"status": "SUCCEEDED",

{
  "data": {
    "compartment-id": "<compartment-OCID>",
    "id": "<work-request-OCID>",
    "operation-type": "CREATE_IOT_DOMAIN",
    "percent-complete": 100.0,
    "resources": [
      {
        "action-type": "CREATED",
        "entity-type": "iotDomain",
        "entity-uri": "/20250531/iotDomains/<iot-domain-OCID>",
        "identifier": "<iot-domain-OCID>",
        "metadata": null
      }
    ],
    "status": "SUCCEEDED",
    "time-accepted": "2025-08-14T16:57:03.413000+00:00",
    "time-finished": "2025-08-14T16:58:43.771000+00:00",
    "time-started": "2025-08-14T16:57:22.147000+00:00",
    "time-updated": "2025-08-14T16:58:43.771000+00:00"
  },
  "etag": "<unique-id>"
}

Optional Step: Get the IoT Domain Details

To confirm the domain is active, use the oci iot domain get command and the required parameter to get a domain's details. Replace the <iot-domain-OCID> with the OCID for your IoT domain.
oci iot domain get --iot-domain-id <iot-domain-OCID>

This example response shows the domain is active: "lifecycle-state": "ACTIVE" and the device host URL with the domain short id:

<domain-short-id>.device.iot.<region>.oci.oraclecloud.com

{
  "data": {
    "compartment-id": "<compartment-OCID>",
    "data-retention-periods-in-days": {
      "historized-data": 30,
      "raw-command-data": 16,
      "raw-data": 16,
      "rejected-data": 16
    },
    "db-allow-listed-identity-group-names": null,
    "db-allowed-identity-domain-host": null,
    "defined-tags": {
      "Oracle-Tags": {
        "CreatedBy": "default/user@oracle.com",
        "CreatedOn": "2025-08-14T16:57:03.140Z"
      }
    },
    "description": "<your-iot-domain-description>",
    "device-host": "<domain-short-id>.device.iot.<region>.oci.oraclecloud.com",
    "display-name": "<your-iot-domain-name>",
    "freeform-tags": {},
    "id": "<iot-domain-OCID>",
    "iot-domain-group-id": "<iot-domain-group-OCID>",
    "lifecycle-state": "ACTIVE",
    "system-tags": {},
    "time-created": "2025-08-14T16:57:03.384000+00:00",
    "time-updated": "2025-08-14T16:58:43.789000+00:00"
  },
  "etag": "<unique-id>"
}

Step 3: Create a Digital Twin Instance

Use the oci iot digital-twin-instance create command and the required <iot-domain-OCID>parameter to create a digital twin instance for an associated IoT domain. When you create a digital twin instance requires and authentication ID. Use either a certificate or secret, see Creating a Secret.

Replace the <iot-domain-OCID> with the IoT domain's OCID for the digital twin instance. This example command includes the optional display name, replace <display-name> with a user-friendly name for your digital twin instance:
oci iot digital-twin-instance create --iot-domain-id <iot-domain-OCID> --auth-id <vault-secret-OCID> --display-name <display-name>
Example response:
{
  "data": {
    "auth-id": "<vault-secret-OCID>",
    "defined-tags": {
      "Oracle-Tags": {
        "CreatedBy": "default/user@oracle.com",
        "CreatedOn": "2025-08-14T06: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>"
}

Step 4: Send Data

Send data using the device host URL from the previous step.

You can send as much data as you want to send. This example shows sending 2 plain text data messages. The first example shows the command using values from this scenario. The second command shows the value names. For more information, see Using cURL.

Replace the <domain-short-id> and the <region> with the values for your environment:

https://<domain-short-id>.device.iot.<region>.oci.oraclecloud.com/sampletopic

This example curl command includes the device host URL and shows the values based on this scenario and includes a sample topic:
curl -u '9K7F8Y3HJGX1FA1GFG9QVV9E2C<vault-secret-OCID>' https://<domain-short-id>.device.iot.us-phoenix-1.oci.oraclecloud.com/sampletopic -H 'Content-Type: plain-text' -d "sample data 2"
This example curl command shows the name of the values without the example values from this scenario:
curl -u '<external-key>:<vault-secret-OCID>' https://<domain-short-id>.device.iot.<region>.oci.oraclecloud.com/sampletopic -H 'Content-Type: plain-text' -d "sample data 1"

Step 5: Configure IoT Domain's Access to APEX

To view your data in APEX requires configuring access to view your IoT data in APEX, a step in that process uses the following command to add the APEX password to the IoT domain so it can access APEX.

Use the oci iot domain configure-apex-data-access command and the required parameters to configure an IoT domain's access to APEX. Replace the <your-initial-apex-password> and the <iot-domain-OCID> with the values for your environment:
oci iot domain configure-apex-data-access --iot-domain-id <iot-domain-OCID> --db-workspace-admin-initial-password <your-inital-apex-password>

Example response:

{
  "opc-work-request-id": "<work-request-OCID>"
}
Optional Step: Get Work Request for Data Access

Optional. During the time it takes to configure access to APEX, use the oci iot work-request get command and the required parameter to get the work request update. Replace the <work-request-id> with the work request id from the previous response:

oci iot work-request get --work-request-id <work-request-OCID>

Example response:

{
  "data": {
    "compartment-id": "<compartment-OCID>",
    "id": "<work-request-OCID>",
    "operation-type": "CONFIGURE_DOMAIN_DATA_ACCESS",
    "percent-complete": 0.0,
    "resources": [
      {
        "action-type": "IN_PROGRESS",
        "entity-type": "iotDomain",
        "entity-uri": "/20250531/iotDomains/<iot-domain-OCID>",
        "identifier": "<iot-domain-OCID>",
        "metadata": null
      }
    ],
    "status": "ACCEPTED",
    "time-accepted": "2025-08-14T17:44:44.716000+00:00",
    "time-finished": null,
    "time-started": null,
    "time-updated": "2025-08-14T17:44:44.716000+00:00"
  },
  "etag": "<unique-id>"
}
Optional Step: List Work Request Logs
Optional. During the time it takes to configure access to APEX for the domain, if you want to list the log entries you can use the oci iot work-request list-logs command and the required parameter to list log entries for the work request:
oci iot work-request list-logs --work-request-id <work-request-OCID>

This example response shows the access to APEX for the domain is in progress and that it's finishing:

{
  "data": {
    "items": [
      {
        "message": "Configuring domain data access is in Progress",
        "timestamp": "2025-08-14T17:45:19.708000+00:00"
      },
      {
        "message": "Finishing work request",
        "timestamp": "2025-08-14T17:45:19.978000+00:00"
      }
    ]
  }
}
Optional Step: List Work Request Errors
Optional. During the time it takes to configure access to APEX for the domain, if you want to check for errors you can use the oci iot work-request list-errors command and the required parameter to list work requests errors:
oci iot work-request list-errors --work-request-id <work-request-OCID>
Example response:
{
  "data": {
    "items": []
  }
}
Optional Step: Get Work Request
Optional. To confirm the configuration for APEX access finished, use the oci iot work-request get command and the required parameter to get the work request. Replace the <work-request-id> with the work request id:
oci iot work-request get --work-request-id <work-request-OCID>

This example response shows the configuring access to APEX for the IoT domain is updated:

"status": "SUCCEEDED"

{
  "data": {
    "compartment-id": "<compartment-OCID>",
    "id": "<work-request-OCID>",
    "operation-type": "CONFIGURE_DOMAIN_DATA_ACCESS",
    "percent-complete": 100.0,
    "resources": [
      {
        "action-type": "UPDATED",
        "entity-type": "iotDomain",
        "entity-uri": "/20250531/iotDomains/<iot-domain-OCID>",
        "identifier": "<iot-domain-OCID>",
        "metadata": null
      }
    ],
    "status": "SUCCEEDED",
    "time-accepted": "2025-08-14T17:44:44.716000+00:00",
    "time-finished": "2025-08-14T17:45:19.978000+00:00",
    "time-started": "2025-08-14T17:45:19.708000+00:00",
    "time-updated": "2025-08-14T17:45:19.978000+00:00"
  },
  "etag": "<unique-id>"
}

Step 6: Access IoT Data in APEX

  1. Use the domain short id that comes from the device host to log in to APEX:

    https://<domain-group-short-id-from-data-host>.data.iot.<region>.oci.oraclecloud.com/ords/r/apex

    device-host:<domain-short-id>.device.iot.<region>.oci.oraclecloud.com

    In APEX log in using:
    Note

    Use only capital letters for the <domain-short-id-from-device-host> and notice the two underscores: __WKSP
  2. To query the IoT data, select the <domain-short-id-from-device-host>__IOT schema. Select SQL Workshop and then select Object Browser.

    SQL workshop URL:

    https://<domain-group-short-id-from-data-host>.data.iot.<region>.oci.oraclecloud.com/ords/r/apex/sql-workshop
  3. Query IoT data by entering and running an SQL command. Confirm you selected the correct schema for the database table you want to query, run the following command:
    select * from RAW_DATA

    Now, you can see the database views, schemas, and raw data for your Internet of Things connected device.

    To view a larger screenshot, right click and open the image in a new browser window.

APEX IoT