IoT Hub からのダイレクトメソッドの呼び出しについて

[アーティクル]
05/10/2024

IoT Hub の "ダイレクトメソッド" を使用すると、リモートでクラウドからデバイスに呼び出しを行うことができます。ダイレクトメソッドは要求/応答型パターンに従うメソッドであり、結果をすぐに確認する必要がある通信向けです。たとえばデバイスを対話式で制御できます (ファンをオンにするなど)。デバイスが応答できるかどうかに応じて即座に実行するアクションが異なるシナリオの場合、この機能が役立ちます。

Note

この記事で説明されている機能は、Standard レベルの IoT Hub でのみ使用できます。 Basic および Standard または Free レベルの IoT Hub の詳細については、ソリューションに適した IoT Hub のレベルの選択に関するページを参照してください。

各デバイスメソッドは、1 つのデバイスをターゲットとします。複数のデバイスでダイレクトメソッドを呼び出し、接続されていないデバイスに対しメソッドをスケジュール設定するには、「複数デバイスでのジョブをスケジュール設定する」を参照してください。

IoT Hub でサービス接続のアクセス許可を持っていれば、誰でもデバイスでメソッドを呼び出すことができます。

必要とされるプロパティ、ダイレクトメソッド、または cloud-to-device メッセージのどれを使用すべきかで疑問がある場合は、「cloud-to-device 通信に関するガイダンス」を参照してください。

メソッドのライフサイクル

ダイレクトメソッドはデバイス上に実装され、正しくインスタンス化するには、メソッドのペイロードに 0 個以上の入力が必要になります。ダイレクトメソッドは、サービス向け URI ({iot hub}/twins/{device id}/methods/) を通じて呼び出します。デバイスは、デバイス固有の MQTT トピック ($iothub/methods/POST/{method name}/) または AMQP リンク (IoThub-methodname および IoThub-status アプリケーションプロパティ) を通じてダイレクトメソッドを受け取ります。

Note

デバイス上のダイレクトメソッドを呼び出す場合、プロパティ名と値には $ ( ) < > @ , ; : \ " / [ ] ? = { } SP HT を除く US-ASCII 印刷可能英数字のみを使用できます。

ダイレクトメソッドは同期型であり、タイムアウト期間 (既定では 30 秒、5 秒から 300 秒に設定可能) 後に成功または失敗します。ダイレクトメソッドは、デバイスがオンラインでコマンドを受け取っている場合のみデバイスを操作する対話型のシナリオで便利です。たとえば、携帯電話からの照明を点灯させる場合です。このようなシナリオでは、成功か失敗かを即座に確認し、クラウドサービスがその結果に対してできるだけ早く対応することが必要になります。デバイスはメソッドの結果として何らかのメッセージ本文を返すことがありますが、それは必須ではありません。順番の保証や、メソッドの呼び出しのコンカレンシーセマンティクスはありません。

ダイレクトメソッドは、クラウド側からは HTTPS のみになります。また、デバイス側からは MQTT、AMQP、MQTT over WebSocket、または AMQP over WebSocket になります。

メソッドの要求および応答のペイロードは、最大 128 KB の JSON ドキュメントになります。

バックエンドアプリからダイレクトメソッドを呼び出す

バックエンドアプリからダイレクトメソッドを呼び出すには、Invoke device method REST API またはIoT Hub サービス SDK のいずれかで同等のものを使用します。

メソッドの呼び出し

デバイスでのダイレクトメソッドの呼び出しは HTTPS 呼び出しであり、次で構成されます。

デバイスに固有の "要求の URI" と API バージョン:

https://fully-qualified-iothubname.azure-devices.net/twins/{deviceId}/methods?api-version=2021-04-12

POST メソッド
ヘッダー。承認、コンテンツの種類、コンテンツのエンコードを含む。

透過的な JSON 本文。次の形式になります。

{
    "connectTimeoutInSeconds": 200,
    "methodName": "reboot",
    "responseTimeoutInSeconds": 200,
    "payload": {
        "input1": "someInput",
        "input2": "anotherInput"
    }
}

要求で responseTimeoutInSeconds として指定された値は、IoT Hub サービスがデバイスでのダイレクトメソッドの実行が完了するまで待機する必要がある時間です。このタイムアウトは、少なくとも、デバイスによるダイレクトメソッドの予想実行時間と同じ長さに設定してください。タイムアウトが指定されていない場合は、既定値の 30 秒が使用されます。 responseTimeoutInSeconds の最小値は 5 秒で、最大値は 300 秒です。

要求で connectTimeoutInSeconds として指定された値は、ダイレクトメソッドの呼び出し時に、IoT Hub サービスが接続されていないデバイスがオンラインになるまで待機する必要がある時間です。既定値は 0 です。これは、ダイレクトメソッドの呼び出し時にデバイスが既にオンラインである必要があることを意味します。 connectTimeoutInSeconds の最大値は 300 秒です。

例

この例では、Azure IoT Hub に登録されている IoT デバイス上でダイレクトメソッドを呼び出すための要求を開始します。

まず、Azure CLI 用の Microsoft Azure IoT 拡張機能を使用して、SharedAccessSignature を作成します。

az iot hub generate-sas-token -n <iothubName> --du <duration>

次に、Authorization ヘッダーを、新しく生成された SharedAccessSignature に置き換えます。次に、以下の curl コマンドの例の実装に一致するように、iothubName、deviceId、methodName、および payload パラメーターを変更します。

curl -X POST \
  https://<iothubName>.azure-devices.net/twins/<deviceId>/methods?api-version=2021-04-12\
  -H 'Authorization: SharedAccessSignature sr=iothubname.azure-devices.net&sig=x&se=x&skn=iothubowner' \
  -H 'Content-Type: application/json' \
  -d '{
    "methodName": "reboot",
    "responseTimeoutInSeconds": 200,
    "payload": {
        "input1": "someInput",
        "input2": "anotherInput"
    }
}'

変更したコマンドを実行して、指定したダイレクトメソッドを呼び出します。要求が成功すると、HTTP 200 状態コードが返されます。

Note

上の例は、デバイスでダイレクトメソッドを呼び出す方法を示しています。 IoT Edge モジュールでダイレクトメソッドを呼び出す場合は、次に示すように URL 要求を変更して /modules/<moduleName> を含める必要があります。

https://<iothubName>.azure-devices.net/twins/<deviceId>/modules/<moduleName>/methods?api-version=2021-04-12

回答

バックエンドアプリは、次の項目で構成されている応答を受け取ります。

HTTP 状態コード:
- 200 は、ダイレクトメソッドが正常に実行されたことを示します。
- 404 は、デバイス ID が無効であること、またはダイレクトメソッドの呼び出し時とその後 connectTimeoutInSeconds の間、デバイスがオンラインになっていなかったことを示します (根本原因を把握するには、付随するエラーメッセージを使用してください)。
- 504 は、responseTimeoutInSeconds 内のダイレクトメソッドの呼び出しにデバイスが応答していないことが原因で、ゲートウェイのタイムアウトが発生したことを示します。
ヘッダー。要求 ID、コンテンツの種類、コンテンツのエンコードを含む。
JSON 本文。次の形式になります。
```
{
    "status" : 201,
    "payload" : {...}
}
```
status と payload はどちらもデバイスによって提供され、デバイス自身の状態コードとメソッドの応答を使用して応答するために使用されます。

IoT Edge モジュールのメソッド呼び出し

モジュールでのダイレクトメソッドの呼び出しは、Invoke module method REST API または IoT Hub サービス SDK のいずれかでそれに相当するものによってサポートされます。

moduleId は、REST API を使用する場合は要求 URI で deviceId とともに渡され、サービス SDK を使用する場合はパラメーターとして渡されます。たとえば、「 https://<iothubName>.azure-devices.net/twins/<deviceId>/modules/<moduleName>/methods?api-version=2021-04-12 」のように入力します。要求本文と応答は、デバイスで呼び出されるダイレクトメソッドと似ています。

デバイスでダイレクトメソッドを処理する

IoT デバイスでは、ダイレクトメソッドを MQTT または AMQP 経由で、またはこれらのプロトコルのいずれかを WebSocket 経由で受信できます。 IoT Hub デバイス SDK を使用すると、基になるプロトコルの詳細を気にすることなく、デバイスでダイレクトメソッドを受信して応答することができます。

MQTT

次のセクションでは、MQTT プロトコルを扱います。 IoT Hubで MQTT プロトコルを直接使用する方法の詳細については、MQTT プロトコルのサポートに関するページを参照してください。

メソッドの呼び出し

デバイスは MQTT トピックに関するダイレクトメソッド要求を受け取ります ($iothub/methods/POST/{method name}/?$rid={request id})。ただし、request id は IoT Hub によって生成され、事前に知ることはできないため、$iothub/methods/POST/# をサブスクライブしてから、お使いのデバイスでサポートされているメソッド名に基づいて、配信されたメッセージをフィルター処理します。 (request id を使用して応答します。)

デバイスが受け取る本文は次の形式になります。

{
    "input1": "someInput",
    "input2": "anotherInput"
}

メソッドの要求は QoS 0 です。

Response

デバイスは応答を $iothub/methods/res/{status}/?$rid={request id} に送信します。この場合、

status プロパティは、デバイスから提供される、メソッド実行の状態です。
$rid プロパティは、IoT Hub から受け取るメソッド呼び出しの要求 ID です。要求 ID は、16 進形式の値です。

本文はデバイスごとに設定され、任意の状態を設定できます。

AMQP

次のセクションでは、AMQP プロトコルを扱います。 IoT Hubで AMQP プロトコルを直接使用する方法の詳細については、AMQP プロトコルのサポートに関するページを参照してください。

メソッドの呼び出し

デバイスは、アドレス amqps://{hostname}:5671/devices/{deviceId}/methods/deviceBound に受信リンクを作成することによってダイレクトメソッド要求を受け取ります。

AMQP メッセージは、メソッド要求を表す受信リンクに到着します。次のセクションが含まれます。

関連付け ID プロパティ。対応するメソッド応答で戻される要求 ID が含まれています。
IoThub-methodname という名前のアプリケーションプロパティ。呼び出されるメソッドの名前が含まれています。
AMQP メッセージ本文。JSON としてメソッドペイロードが含まれています。

Response

デバイスは、メソッド応答を返す送信リンクをアドレス amqps://{hostname}:5671/devices/{deviceId}/methods/deviceBound に作成します。

メソッドの応答は送信リンクで返され、以下のもので構成されています。

関連付け ID プロパティ。メソッドの要求メッセージで渡される要求 ID が含まれています。
IoThub-status という名前のアプリケーションプロパティ。ユーザーが指定したメソッド状態が含まれています。
AMQP メッセージ本文。JSON としてメソッド応答が含まれています。

次のステップ

ダイレクトメソッドの使用方法を理解できたら、次の IoT Hub 開発者ガイドの記事も参考にしてください。

複数デバイスでのジョブをスケジュール設定する
Azure IoT device SDK とサービス SDK: IoT Hub とやりとりするデバイスとサービスアプリの両方を開発する際に使用できるさまざまな言語の SDK を紹介します。
デバイスツイン、ジョブ、メッセージルーティングの IoT Hub クエリ言語: デバイスツインとジョブに関する情報を IoT Hub から取得するために使用できる IoT Hub クエリ言語について説明します。

次の方法で共有

IoT Hub からのダイレクトメソッドの呼び出しについて

メソッドのライフサイクル

バックエンドアプリからダイレクトメソッドを呼び出す

メソッドの呼び出し

例

回答

IoT Edge モジュールのメソッド呼び出し

デバイスでダイレクトメソッドを処理する

MQTT

メソッドの呼び出し

Response

AMQP

メソッドの呼び出し

Response

次のステップ

フィードバック

その他のリソース

次の方法で共有

IoT Hub からのダイレクト メソッドの呼び出しについて

メソッドのライフサイクル

バックエンド アプリからダイレクト メソッドを呼び出す

メソッドの呼び出し

例

回答

IoT Edge モジュールのメソッド呼び出し

デバイスでダイレクト メソッドを処理する

MQTT

メソッドの呼び出し

Response

AMQP

メソッドの呼び出し

Response

次のステップ

フィードバック

その他のリソース

IoT Hub からのダイレクトメソッドの呼び出しについて

バックエンドアプリからダイレクトメソッドを呼び出す

デバイスでダイレクトメソッドを処理する