シナリオ: コマンドの受信とMQTTを使用したレスポンスの送信
このシナリオを使用して、クラウドでコマンドを受信し、Internet of Things (IoT)デバイスと対話するためにMQTTsプロトコルを使用してデバイスにレスポンスを送信します。
タスク
次のステップを完了するには、既存のIoTドメインとIoTドメイン・グループを使用するか、IoTドメイン・グループとIoTドメインを作成してから、次のステップを実行します。
ステップ1: デジタル・ツイン・インスタンスの作成
CLIの使用
- デジタル・ツイン・インスタンスを作成する場合、シークレットまたは証明書を使用して、デジタル・ツイン・インスタンスを安全に認証できます。このシナリオを完了するには、シークレットを作成するか、証明書を作成する必要があります。Oracleでは、デジタル・ツイン・インスタンスごとに1つのシークレットを使用することをお薦めします。また、本番では、デジタル・ツイン・インスタンスで認証にmTLS証明書を使用することをお薦めします。
デジタル・ツインを作成するには、
oci iot digital-twin-instance createコマンドおよび必須パラメータを使用します。次の例は、認証IDパラメータを必要なIoTドメイン・パラメータとともに使用して、IoTドメインをデジタル・ツイン・インスタンスに関連付けるコマンドを示しています。oci iot digital-twin-instance create --auth-id <vault-secret-or-client-certificate-id> --iot-domain-id <iot-domain-OCID>このレスポンス例では、外部キー値に注意してください。この外部キー値を使用して、次のステップで使用できるデバイス・ユーザー名である外部キーを確認します:
"external-key": "<unique-id>"{ "data": { "auth-id": "<vault-secret-or-certificate-OCID>", "defined-tags": { "Oracle-Tags": { "CreatedBy": "default/user@oracle.com", "CreatedOn": "2025-08-05T18:03:15.264Z" } }, "description": null, "digital-twin-adapter-id": null, "digital-twin-model-id": null, "digital-twin-model-spec-uri": null, "display-name": "HVAC-instance", "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-05T18:03:15.870000+00:00", "time-updated": "2025-08-05T18:03:15.870000+00:00" }, "etag": "<unique-id>" }
ステップ2: ブローカ資格証明を使用したMQTTセッションの確立
- MQTTXをダウンロードして設定するには、MQTTXのスタート・ガイドを参照してください。MQTTXを開きます。
- 新しい接続を作成するには「+新規接続」を選択します。接続の名前を入力し、機密情報を入力しないでください。
- 「ユーザー名」として外部キーの
<unique-id>値を入力します。外部キーは、前のステップ1: デジタル・ツイン・インスタンスの作成からoci iot digital-twin-instance createレスポンスで確認できます。"external-key": "<unique-id>" - デバイスのパスワードを入力します。ボールト・シークレットを使用する場合、これはプレーン・テキスト・シークレットであるか、mTLS証明書を使用できます。
- ホストを入力します。ホストのドロップダウン・リストから
mqtts://プロトコルを選択し、IoTドメインからデバイス・ホスト<domain-short-id>.device.iot.<region>.oci.oraclecloud.comを入力します。「IoTドメインの詳細の取得」を参照してください。 - ポート(
8883など)を入力します。ノート
現在、MQTT Secure (MQTTS)はポート8883を使用してのみサポートされています。 - SSL/TLSの切り替えを有効にします。
- 「SSLセキュア」の切替えをオンにします。
- 「証明書」で、「CA署名サーバー証明書」オプションを選択します。
- MQTTX接続を構成する場合は、次を使用して接続してください。
clean session: クリーン・セッション・オプションをtrueに設定します。cleanセッションがtrueに設定されている場合、ブローカはクライアントの情報を保持せず、永続セッションから以前の状態をすべて破棄します。ネットワーク接続がクローズされると、すべてのセッション・データが削除されます。Last-Will-Retainオプションをfalseに設定すると、デバイスが短時間切断した場合にクライアント・サブスクリプションが保持されるようになります。
- Last Will QoSを 1に設定します。切断通知の「At Least Once」配信の信頼性を定義します。
- 「接続」を選択します。
この画像は、MQTTXでのこれらの設定を示しています。右クリックして新しいタブで開き、より大きなスクリーンショットを表示します。
ステップ3: MQTTXでレスポンスを受信するためのトピックのサブスクライブ
外部システムまたはIoTデバイスがサブスクライブされたトピックにメッセージをパブリッシュすると、MQTTXでそのトピックの受信メッセージを表示します。前のコマンドからのレスポンスを待っている場合は、正しいレスポンス・トピックをサブスクライブしていることを確認してください。
JSONファイルでコマンドを定義するときに、次のステップでresponseEndpointを定義します。"responseEndpoint": "/endpoints/4321"文字列は、デバイスがレスポンスを公開するトピックまたはエンドポイント・パスを表します。デジタル・ツイン・ルートの任意の論理エンドポイント・パスを選択します。クラウド側(コマンドの送信時)とデバイス側(レスポンスの公開時)の両方で同じパスを使用する必要があります。
- MQTTXで、「+新規サブスクリプション」を選択します。
- 「トピック」としてエンドポイントを入力します。
- QoSドロップダウン・メニューから、「1回以上」を選択します。
- 「確認」を選択します。
- クライアントID: your-client-ID
- ユーザー名: 外部ID。
- パスワード: デバイスのパスワードを入力します。
- IoTドメインのデバイス・ホストで、ポート番号8883を使用して
mqtts://を入力します。mqtts://<iot-domain-short-id>.device.iot.<region>.oci.oraclecloud.com:8883
.
ステップ4: JSONファイルでのコマンドの定義
JSONファイルでコマンド詳細を定義し、次のステップでこのファイルを使用して「デバイスでのRAW JSONコマンドの起動」を実行できます。
この例では、このスニペットをcommand.jsonファイルに保存して、これを使用してコマンドを起動し、ファイル内の指示に従ってレスポンスを処理できるようにします。
{
"requestEndpoint": "/endpoints/1234",
"requestDuration": "PT3M",
"requestDataFormat": "JSON",
"requestData": {
"temp": 33
},
"requestDataContentType": "application/json",
"responseEndpoint": "/endpoints/4321",
"responseDuration": "PT3M"
}requestEndpoint: リクエストが送信されるURLパス/endpoints/1234。これは通常、APIエンドポイントまたはIoTプラットフォームがコマンドをリスニングするアドレスです。レスポンス専用のエンドポイントがすでにある場合(例:
/endpoints/<external-id>/response)、そのパスをresponseEndpointで使用します。または、デバイスがパブリッシュできるデジタル・ツイン・アダプタのインバウンド・ルーティング・ルールで、デジタル・ツイン・インスタンス用の新しい
endpoint/routeを作成します。command.jsonファイルでそのパスを参照します。コマンドのレスポンスを確認できるように、responseEndpointで定義したパスがMQTTトピックになり、クライアントがステップ3でサブスクライブする必要があるため、エンドポイント・パスの一貫性を維持します。requestDuration: リクエストが完了するまでの許容期間(ISO 8601期間形式)。たとえば、PT3Mは3分です。requestDataFormat: JSONリクエストで送信されるデータの日付書式を指定します。requestData: デバイスの温度値を設定するためにキー値ペアで送信されるJSONペイロード:"temp": 33
ステップ5: デバイスでのRAW JSONコマンドの起動
CLIまたはAPIを使用して、デバイスでコマンドを起動できます。次の例では、CLIを使用します。
CLIの使用
oci iot digital-twin-instance invoke-raw-json-commandコマンドおよびパラメータを使用して、デバイスでRAW JSONコマンドを起動します。
- 「ステップ1: デジタル・ツイン・インスタンスの作成」の<digital-twin-instance-OCID>をデジタル・ツイン・インスタンスのOCIDに置き換えます。
- 前の「ステップ2: JSONファイルでのコマンドの定義」の
command.jsonファイルを使用します。 /endpoints/1234を、--request-endpointパラメータのcommand.jsonファイルに定義した値に置き換えます。
oci iot digital-twin-instance invoke-raw-json-command --digital-twin-instance-id <digital-twin-instance-OCID> --request-endpoint "/endpoints/1234" --from-json file://command.jsonステップ6: MQTTXでの検証
{
"temp": 33
}大きなスクリーンショットを表示するには、右クリックして新しいタブで開きます。
| シナリオ | デバイスの状態 | 予想されるコマンド状態 | コメント |
|---|---|---|---|
| 未接続 | 未接続、未登録 | 拒否済 | コマンドの配信がすぐに失敗する |
| 接続済ですがサブスクライブされていません | 接続済 | 拒否済 | デバイスはオンラインですが、コマンドを受信しません |
| サブスクライブしましたが、接続されていません | サブスクライブのみ | 保留中 → 失効 | コマンドは待機します。タイムアウト後に期限切れになります。 |
| サブスクライブされていますが、最初に接続されておらず、タイムアウト前に接続されています | 初期オフライン | 保留中 → 送信済 | コマンドを受信しました |
| 接続済およびサブスクライブ済 | 接続済およびサブスクライブ済 | 送信 | コマンドを受信しました |
| 一方向コマンド(応答なし) | 接続済およびサブスクライブ済 | COMPLETED | 応答は予期されず、追跡されます |
| 双方向コマンド(応答を受信しませんでした) | 接続済およびサブスクライブ済 | NOT_RESPONDED | デバイスがレスポンス期間のタイムアウト内に応答しません |
| 双方向コマンド(レスポンスを受信) | 接続済およびサブスクライブ済 | COMPLETED | デバイスはレスポンス・タイムアウト内にデータを送信し、フローを完了します |
ステップ7: APEXでのコマンドの配信ステータスの監視
APEXでIoTデータを表示するには、データへのアクセスの構成が必要です。その構成が完了したら、APEXを使用してIoTデータを操作できます。
- APEXで、ワークスペース名およびデータベース・ユーザー名として次を使用して、特定のIoTドメインのワークスペースにログインします。データベース・スキーマ名の2つのアンダースコアに注意してください。「SQLワークショップ」に移動し、「SQLコマンド」を選択してIoTデータを問い合せます。
<domain-short-id-from-device-host>__IOT - 次のコマンドを入力し、
<digital-twin-instance-OCID>をデジタル・ツインOCIDに置き換え、「実行」を選択してRAWコマンド・データを問い合せます。select * from raw_command_data where digital_twin_instance_id='<digital-twin-instance-OCID>' - 「結果」で、RESPONSE_DATAを表示します。
{"test":1}
