シナリオ: MQTTを使用したデフォルト形式での構造化データの送信
このシナリオを確認して、MQTTを使用してパルス・オキシメータから履歴化されたテレメトリ・データを受信するデジタル・ツイン・モデルを作成する方法と、APEXでIoTデータを表示する方法について学習します。
ステップ1: デジタル・ツイン・モデルのDTDL仕様の作成
パルスオキシメータのみがヒストライズ済としてマークされるデジタルツインモデル仕様を定義します。
これをテキスト・ファイルとして保存し、次のステップで参照して、これらの仕様に基づいてデジタル・ツイン・モデルを作成します。
DTDL v3仕様に基づきます。
{
"@context": [
"dtmi:dtdl:context;3",
"dtmi:dtdl:extension:historization;1"
],
"@id": "dtmi:com:oracle:example:health:po;1",
"@type": "Interface",
"displayName": "Pulse Oximeter",
"description": "This is digital twin model for pulse oximeter",
"contents": [
{
"name": "pulse",
"displayName": "Heart Rate",
"@type": [
"Telemetry",
"Historized"
],
"schema": "integer"
},
{
"name": "so2",
"displayName": "Oxygen Saturation",
"@type": "Telemetry",
"schema": "integer"
}
]
}
ステップ2: パルスオキシメータ用のデジタルツインモデルの作成
パルス・オキシメータのデジタル・ツイン・モデルを作成し、<path-to-definition-file>を、前のステップのパルス・オキシメータ・デジタル・モデル仕様を定義するファイルの場所に置き換えます。
ファイルの参照の詳細は、複合入力へのJSONファイルの使用を参照してください。
oci iot digital-twin-model create --iot-domain-id <iot-domain-OCID> --spec <path-to-definition-file>レスポンスの例:
{
"data": {
"defined-tags": {
"Oracle-Tags": {
"CreatedBy": "default/user@oracle.com",
"CreatedOn": "2025-08-17T14:23:03.379Z"
}
},
"description": "This is digital twin model for pulse oximeter",
"display-name": "Pulse Oximeter",
"freeform-tags": {},
"id": "<digital-twin-OCID>",
"iot-domain-id": "<iot-domain-OCID>",
"lifecycle-state": "ACTIVE",
"spec-uri": "dtmi:com:oracle:example:health:po;1",
"system-tags": {},
"time-created": "2025-08-17T14:23:03.449000+00:00",
"time-updated": "2025-08-17T14:23:03.449000+00:00"
},
"etag": "<unique-id>"
}
ステップ3: デフォルトのデジタル・ツイン・アダプタの作成
oci iot digital-twin-adapter createコマンドを使用して、パルスオキシメータ・デジタル・ツイン・モデルのデフォルトのデジタル・ツイン・アダプタを作成します。この例では、inbound-envelopeまたはenvelope-mappingを指定せずにこれを指定しないデフォルトのデジタル・ツイン・アダプタを作成する方法を示します。その結果、データはデバイスのデフォルト形式で送信されます。
エンベロープ・マッピングが指定されておらず、timeObservedが含まれている場合は、receivedTimeがtimeObserved値として使用されます。
oci iot digital-twin-adapter create --iot-domain-id <iot-domain-OCID> --digital-twin-model-spec-uri "dtmi:com:oracle:example:health:po;1" --display-name "<your-pulse-oximeter-name>" --description "<this-is-digital-twin-adapter-for-pulse-oximeter>"デバイスのペイロードおよび関連するIoTドメイン、デジタル・ツイン・モデル、デジタル・ツイン・アダプタおよびDTMI URIの値を示すレスポンスの例。
{
"data": {
"defined-tags": {
"Oracle-Tags": {
"CreatedBy": "default/user@oracle.com",
"CreatedOn": "2025-08-17T14:25:51.190Z"
}
},
"description": "<this-is-digital-twin-adapter-for-pulse-oximeter>"
"digital-twin-model-id": "<iot-digital-twin-model-OCID>",
"digital-twin-model-spec-uri": "dtmi:com:oracle:example:health:po;1",
"display-name": "Pulse Oximeter",
"freeform-tags": {},
"id": "<iot-digital-twin-adapter-OCID>",
"inbound-envelope": {
"envelope-mapping": {
"time-observed": "$.time"
},
"reference-endpoint": "/",
"reference-payload": {
"data": {
"pulse": 0,
"so2": 0,
"time": "2025-08-17T14:25:52.184012284Z"
},
"data-format": "JSON"
}
},
"inbound-routes": [
{
"condition": "*",
"description": "Default condition",
"payload-mapping": {
"$.pulse": "$.pulse",
"$.so2": "$.so2"
},
"reference-payload": null
}
],
"iot-domain-id": "<iot-domain-OCID>",
"lifecycle-state": "ACTIVE",
"system-tags": {},
"time-created": "2025-08-17T14:25:52.186000+00:00",
"time-updated": "2025-08-17T14:25:52.186000+00:00"
},
"etag": "<unique-id>"
}
ステップ4: デジタル・ツイン・インスタンスの作成
このoci iot digital-twin-instance createコマンドを使用して、デジタル・ツイン・インスタンスを作成します。
<iot-domain-OCID>および<iot-digital-twin-adapter-OCID>を置き換えて、このデジタル・ツイン・インスタンスを、前のステップで作成した関連するIoTリソースに関連付けます。
<vault-secret-OCID>を、デジタル・ツイン・インスタンスと同じリージョンで作成されたボールト・シークレットに置き換えます。詳細は、シークレットの作成に関する項を参照してください。
oci iot digital-twin-instance create --iot-domain-id <iot-domain-OCID> --digital-twin-adapter-id <iot-digital-twin-adapter-OCID> --auth-id <vault-secret-OCID> --display-name "<Pulse Oximeter 1>"このレスポンス例は、関連するデジタル・ツイン・アダプタ、デジタル・ツイン・モデル(DTMI URIを含む)を持つデジタル・ツイン・インスタンスを示しています。
{
"data": {
"auth-id": "<vault-secret-OCID>",
"defined-tags": {
"Oracle-Tags": {
"CreatedBy": "default/user@oracle.com",
"CreatedOn": "2025-08-17T14:39:44.292Z"
}
},
"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:health:po;1",
"display-name": "Pulse Oximeter 1",
"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-08-17T14:39:45.238000+00:00",
"time-updated": "2025-08-17T14:39:45.238000+00:00"
},
"etag": "<unique-id>"
}ステップ5: MQTTXを使用したデータの公開
- MQTTXをインストールします。
https://mqttx.app/docs/cli/downloading-and-installation - MQTTXを構成します。
<device-host-from-iot-domain>を置き換えます。デジタル・ツイン・インスタンス・レスポンスの
<external-key>を置き換えます。mqttx init ? Select MQTTX CLI output mode Text ? Select the default MQTT protocol MQTTS ? Enter the default MQTT broker host <device-host-from-iot-domain> ? Enter the default MQTT port 8883 ? Enter the maximum reconnect times for MQTT connection 10 ? Enter the default username for MQTT connection authentication <external-key> ? Enter the default password for MQTT connection authentication <auth-id-secret-value> Configuration file created/updated at /Users/<user-name>/.mqttx-cli/config - 接続の検証
mqttx conn -h <data-host> -u <external-key> -P '<vault-secret-value>' - サンプル・データを公開します。ノート
-uおよび-Pは、これらがmqtt initでデフォルトとして設定されている場合にのみ必要です。
ステップ6: APEXでのIoTデータの表示
APEXでIoTデータを表示する場合は、APEXへの接続を構成する必要があります。
構成の設定後、次のステップに従ってAPEXでIoTデータベース・スキーマを表示できます:
- データ・ホストのドメイン・グループ短縮IDを含むAPEX URLに移動します:
https://<domain-group-short-id-from-data-host>.data.iot.<region>.oci.oraclecloud.com/ords/r/apex - APEXにログインするには、デバイス・ホストのドメイン短縮IDを使用します:APEXで、次を使用してログインします。
device-host:<domain-short-id-from-device-host>.device.iot.<region>.oci.oraclecloud.com- データベース:
<domain-short-id-from-device-host>__WKSP - ユーザー名:
<domain-short-id-from-device-host>__WKSP - CLIコマンドを使用してAPEX用のIoTドメインのデータ・アクセスを構成する場合の初期パスワード・セット:
<initial-apex-password>
- データベース:
「SQLワークショップ」に移動します。「SQLコマンド」を使用して、IoTデータを問い合せます。
select * from <iot-domain-short-id-from-device-host>__IOT.SNAPSHOT_DATA where digital_twin_instance_id='<iot-digital-twin-instance-OCID>';DIGITAL_TWIN_INSTANCE_ID CONTENT_PATH VALUE TIME_OBSERVED <iot-digital-twin-instance-OCID> so2 95 17-AUG-25 03.15.56.000205 PM <iot-digital-twin-instance-OCID> pulse 75 17-AUG-25 03.15.56.000205 PMselect * from <iot-domain-short-id-from-device-host>__IOT.HISTORIZED_DATA where digital_twin_instance_id='ocid1.iotdigitaltwininstance.oc1.<region>.<unique-id>';ID DIGITAL_TWIN_INSTANCE_ID CONTENT_PATH VALUE TIME_OBSERVED 87 <iot-digital-twin-instance-OCID> pulse 75 17-AUG-25 03.15.56.000205 PM
ステップ7: MQTTXを使用したメッセージの公開
再度公開して、接続が確立され、メッセージがパブリッシュされたことを確認します。
前のステップでデジタル・ツイン・インスタンスを作成したときに、ボールト・シークレットを認証IDとして指定した場合、OCIボールトに格納されているそのシークレットのコンテンツを取得し、<vault-secret-content>をシークレットのコンテンツに置き換えることができます。
mqttx pub -t "/data" -m '{ "pulse": 76, "so2": 94}' -u <external-key> -P '<vault-secret-content>'
ステップ8: APEXでのIoTスナップショット・データの問合せ
- APEXでは、この文を使用してスナップショット・データを問い合せます。スキーマ名の2つのアンダースコアに注意してください。
select * from <iot-domain-short-id-from-device-host>__IOT.SNAPSHOT_DATA where digital_twin_instance_id='<iot-digital-twin-instance-ocid>'; - 各デジタル・ツイン・インスタンスについて最後に更新された既知の値を表示します。
DIGITAL_TWIN_INSTANCE_ID CONTENT_PATH VALUE TIME_OBSERVED ocid1.iotdigitaltwininstance.oc1.<region>.<unique-id> so2 94 17-AUG-25 03.22.34.000753 PM ocid1.iotdigitaltwininstance.oc1.<region>.<unique-id> pulse 76 17-AUG-25 03.22.34.000753 PM - APEXでは、この文の問合せ履歴データを使用します。
select * from <iot-domain-short-id-from-device-host>__IOT.HISTORIZED_DATA where digital_twin_instance_id='<iot-digital-twin-instance-OCID>'; - 前のステップのデジタル・ツイン・モデルで履歴化済とマークされたパルス・オキシメータのみが結果として、パルス・オキシメータのみが時系列履歴データを示していることを確認します。
ID DIGITAL_TWIN_INSTANCE_ID CONTENT_PATH VALUE TIME_OBSERVED 87 <iot-digital-twin-instance-OCID> pulse 75 17-AUG-25 03.15.56.000205 PM 88 <iot-digital-twin-instance-OCID> pulse 76 17-AUG-25 03.22.34.000753 PM
ステップ9: SDKの使用
Internet of Things SDKのJavaScriptファイルとして使用できる、この高度なデータのシミュレーションを確認します。
/**
* MQTTX Scenario file example
*
* This script generates random pulse and so2 to simulate pulse oximeter.
*/
function generator(faker, options) {
return {
// If no topic is returned, use the topic in the command line parameters.
// Topic format: 'mqttx/simulate/myScenario/' + clientId,
message: JSON.stringify({
pulse: faker.number.int({ min: 60, max: 120 }), // Generate a random pulse between 60 and 120.
so2: faker.number.int({ min: 90, max: 100 }), // Generate a random so2 between 90 and 100.
})
}
}
// Export the scenario module
module.exports = {
name: 'Pulse Oximeter Scenario', // Name of the scenario
generator, // Generator function
}
mqttx simulateコマンドを使用し、ファイルを参照する例。mqttx simulate --file <path-to-above-script-file> -u <external-key> -P '<vault-secret-content>'
❯ Starting publish simulation, scenario: Pulse Oximeter Scenario, connections: 1, req interval: 10ms, message interval: 1000ms
✔ [1/1] - Connected
✔ Created 1 connections in 1.198s
Published total: 10, message rate: 1/s
^C after 10 (or how much every you want)
ステップ10: APEXのIoTデータの問合せ
- APEXでは、パルス・オキシメータのスナップショット・データを問い合せることができます。
select * from <iot-domain-short-id>__IOT.SNAPSHOT_DATA where digital_twin_instance_id = 'ocid1.iotdigitaltwininstance.oc1.<region>.<unique-id>';ocid1.iotdigitaltwininstance.oc1.<region>.<unique-id> so2 90 17-AUG-25 03.29.19.000429 PM ocid1.iotdigitaltwininstance.oc1.<region>.<unique-id> pulse 90 17-AUG-25 03.29.19.000429 PM - 問合せ履歴データ。
select * from <iot-domain-short-id>__IOT.HISTORIZED_DATA where digital_twin_instance_id = 'ocid1.iotdigitaltwininstance.oc1.<region>.<unique-id>'; - パルスオキシメータの時系列データを確認します。
ID DIGITAL_TWIN_INSTANCE_ID CONTENT_PATH VALUE TIME_OBSERVED 94 <iot-digital-twin-instance-OCID> pulse 81 17-AUG-25 03.29.15.000424 PM 96 <iot-digital-twin-instance-OCID> pulse 116 17-AUG-25 03.29.17.000430 PM 92 <iot-digital-twin-instance-OCID> pulse 105 17-AUG-25 03.29.13.000416 PM 89 <iot-digital-twin-instance-OCID> pulse 87 17-AUG-25 03.29.10.000409 PM 97 <iot-digital-twin-instance-OCID> pulse 112 17-AUG-25 03.29.18.000429 PM 91 <iot-digital-twin-instance-OCID> pulse 73 17-AUG-25 03.29.12.000411 PM 93 <iot-digital-twin-instance-OCID> pulse 70 17-AUG-25 03.29.14.000413 PM 87 <iot-digital-twin-instance-OCID> pulse 75 17-AUG-25 03.15.56.000205 PM 88 <iot-digital-twin-instance-OCID> pulse 76 17-AUG-25 03.22.34.000753 PM 90 <iot-digital-twin-instance-OCID> pulse 74 17-AUG-25 03.29.11.000409 PM