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.
- Create an IoT domain group
- Create an IoT domain
- Create a digital twin instance
- Send data
- Configure IoT domain to access APEX
- 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>"
}
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>"
}
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>
{
"data": {
"items": []
}
}
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. 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>
"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. 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>"
}
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"
}
]
}
}
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
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.
<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
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.
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. 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>"
}
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"
}
]
}
}
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>
{
"data": {
"items": []
}
}
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
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:- Database:
<domain-short-id-from-device-host>__WKSP
- Username:
<domain-short-id-from-device-host>__WKSP
- Initial password set when you used the CLI command to configure an IoT domain's data access for APEX:
<initial-apex-password>
Note
Use only capital letters for the<domain-short-id-from-device-host>
and notice the two underscores: __WKSP- Database:
- 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
- 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.