Oracle Cloud Infrastructureドキュメント

シナリオ: コマンドの受信とMQTTを使用したレスポンスの送信

このシナリオを使用して、クラウドでコマンドを受信し、Internet of Things (IoT)デバイスと対話するためにMQTTsプロトコルを使用してデバイスにレスポンスを送信します。

タスク

次のステップを完了するには、既存のIoTドメインとIoTドメイン・グループを使用するか、IoTドメイン・グループとIoTドメインを作成してから、次のステップを実行します。

  1. デジタル・ツイン・インスタンスの作成
  2. JSONファイルでのコマンドの定義
  3. raw JSONコマンドの起動
  4. MQTTXを使用した外部IDを使用したデジタル・ツインへの接続
  5. コマンドを受信するトピックをサブスクライブします
  6. APEXでのコマンドの配信ステータスの監視
  7. MQTTXでのコマンドのレスポンスの表示

ステップ1: デジタル・ツイン・インスタンスの作成

CLIの使用

  1. デジタル・ツイン・インスタンスを作成する場合、デジタル・ツイン・インスタンスが安全に認証できるように、シークレットまたは証明書を使用します。このシナリオを完了するには、シークレットを作成するか、証明書を作成する必要があります。Oracleでは、デジタル・ツイン・インスタンスごとに1つのシークレットを使用することをお薦めします。

  2. oci iot digital-twin-instance createコマンドおよび必須パラメータを使用して、デジタル・ツインを作成します。次の例は、表示名と認証IDパラメータを指定したコマンドを示しています。

    oci iot digital-twin-instance create --auth-id <vault-secret-or-client-certificate-id> --iot-domain-id <iot-domain-OCID>

    このレスポンス例では、外部キーの値を確認します。「ステップ3: 外部IDを使用したMQTTXの接続」で、次の外部キー値を使用します:

    "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: JSONファイルでのコマンドの定義

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プラットフォームがコマンドをリスニングするアドレスです。
  • requestDuration: リクエストの完了に許可またはリクエストされた期間(ISO 8601継続時間形式)。3分に等しいPT3M。
  • requestDataFormat: JSONリクエストで送信されるデータの日付書式を指定します。
  • requestData: デバイスの温度値を設定するためにキー値ペアで送信されるJSONペイロード:
    "temp": 33
ファイルの場所およびパス・タイプの詳細は、「複合入力のためのJSONファイルの使用」を参照してください。

ステップ3: デバイスでの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ファイルで定義されたRAW 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
その他のコマンド・タイプの詳細は、デジタル・ツイン・インスタンスからのRAWコマンドの送信を参照してください。

ステップ4: MQTTXを使用した外部IDを使用したデバイスへの接続

MQTTクライアントを使用します。この例では、次の設定でMQTTXを使用します。
  1. MQTTXをダウンロードして設定するには、MQTTXのスタート・ガイドを参照してください。MQTTXを開きます。
  2. 新しい接続を作成するには、「+新規接続」を選択します。
  3. 「ユーザー名」として外部キーの<unique-id>値を入力します。外部キーは、前のステップ1: デジタル・ツイン・インスタンスの作成からoci iot digital-twin-instance createレスポンスで確認できます。
    "external-key": "<unique-id>"
  4. デバイスのパスワードを入力します。
  5. 「ホスト」を入力します。ホストのドロップダウン・リストからmqtts://プロトコルを選択し、IoTドメインからデバイス・ホスト<domain-short-id>.device.iot.<region>.oci.oraclecloud.comを入力します。
  6. ポート(8883など)を入力します。
  7. SSL/TLSの切り替えを有効にします。
  8. 「SSLセキュア」の切替えをオンにします。
  9. 「証明書」で、「CA署名サーバー証明書」オプションを選択します。
  10. MQTTX接続を構成する場合は、必ずclean sessionを使用して接続し、Last-Will-Retainオプションをfalseに設定して、デバイスが短時間切断された場合にクライアント・サブスクリプションを保持できるようにします。
  11. 「Last Will QoS」を「1」に設定します。
  12. 「接続」を選択します。

このイメージは、MQTTXの設定を示しています。右クリックして新しいタブで開き、より大きなスクリーンショットを表示します。

コマンドを呼び出すためのMQTTX設定。

大きなスクリーンショットを表示するには、右クリックして新しいタブで開きます。

MQTTXで「接続」を選択します。

ステップ5: MQTTXでレスポンスを受信するためのトピックのサブスクライブ

外部システムまたはIoTデバイスがサブスクライブされたトピックにメッセージをパブリッシュすると、そのトピックの下のMQTTXで受信メッセージが表示されます。前のコマンドからのレスポンスを待機している場合は、デジタル・ツイン・インスタンスのレスポンスで<external-id>値として動的に設定される正しいレスポンス・トピックをサブスクライブしていることを確認してください。

  1. MQTTXで、「+新規サブスクリプション」を選択します。
  2. 「トピック」としてエンドポイントを入力します。
  3. QoSドロップダウン・メニューから、「1回以上」を選択します。
  4. 「確認」を選択します。
次の接続設定を使用して、特定の外部IDを持つデジタル・ツイン・インスタンスのデバイス・エンドポイントにパブリッシュされたメッセージを受信します。
  • クライアントID: your-client-ID
  • ユーザー名: 外部ID。
  • パスワード: デバイスのパスワードを入力します。
  • mqtts://にデバイス・ホストおよびポート番号を入力します。

    mqtts://<iot-domain-short-id>.device.iot.<region>.oci.oraclecloud.com:8883

大きなスクリーンショットを表示するには、右クリックして新しいタブで開きます。MQTTXでトピックとしてエンドポイントを入力し、サブスクリプションを確認します。

ステップ6: APEXでのコマンドの配信ステータスのモニター

APEXでIoTデータを表示するには、データへのアクセスの構成が必要です。その構成が完了したら、APEXを使用してIoTデータを操作できます。

  1. APEXで、ワークスペース名およびデータベース・ユーザー名として次を使用して、特定のIoTドメインのワークスペースにログインします。データベース・スキーマ名の2つのアンダースコアに注意してください。
    <domain-short-id-from-device-host>__IOT
    「SQLワークショップ」に移動し、「SQLコマンド」を選択してIoTデータを問い合せます。
  2. 次のコマンドを入力し、<digital-twin-instance-OCID>をデジタル・ツインOCIDに置き換え、「実行」を選択してRAWコマンド・データを問い合せます。 
    select * from raw_command_data
where digital_twin_instance_id='<digital-twin-instance-OCID>'
  3. 「結果」で、RESPONSE_DATAを表示します。
    {"test":1}
大きなスクリーンショットを表示するには、右クリックして新しいタブで開きます。APEXでデバイスのレスポンス・データを表示します。

ステップ7: MQTTXでのコマンドのレスポンスの表示

MQTTXで、「接続」を選択してレスポンスを表示します。
{
    "test": 1
  }

大きなスクリーンショットを表示するには、右クリックして新しいタブで開きます。

MQTTXでコマンド・レスポンス・データを表示します。