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

[アーティクル]
03/23/2023

IoT Hub には、クラウドからデバイス上のダイレクトメソッドを呼び出す機能が備わっています。ダイレクトメソッドは、デバイスとの要求/応答型通信を表し、すぐに要求の成功または失敗が確定する (ユーザーが指定したタイムアウト後) という点で HTTP 呼び出しに似ています。この方法は、デバイスが応答できるかどうかに応じて即座に実行するアクションが異なるシナリオで便利です。

Note

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

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

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

ダイレクトメソッドは要求/応答型パターンに従うメソッドであり、結果をすぐに確認する必要がある通信向けです。たとえばデバイスを対話式で制御する (例: ファンをオンにする) ときに使用されます。

必要とされるプロパティ、ダイレクトメソッド、または C2D メッセージの使用方法の詳細については、「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 要求を変更する必要があります。

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

Response

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

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 開発者ガイド内の他の参照トピックは次のとおりです。

IoT Hub エンドポイント: 各 IoT Hub でランタイムと管理の操作のために公開される、さまざまなエンドポイントについて説明します。
調整とクォータ: IoT Hub の使用時に適用されるクォータと想定される調整の動作について説明します。
Azure IoT device SDK とサービス SDK: IoT Hub とやりとりするデバイスとサービスアプリの両方を開発する際に使用できるさまざまな言語の SDK を紹介します。
デバイスツイン、ジョブ、メッセージルーティングの IoT Hub クエリ言語: デバイスツインとジョブに関する情報を IoT Hub から取得するために使用できる IoT Hub クエリ言語について説明します。
IoT Hub の MQTT サポート: IoT Hub での MQTT プロトコルのサポートについて詳しく説明します。

次のステップ

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

複数デバイスでのジョブをスケジュール設定する

この記事で説明した概念を試す場合は、次の IoT Hub のチュートリアルをご利用ください。

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

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

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

メソッドの呼び出し

例

Response

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

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

MQTT

メソッドの呼び出し

Response

AMQP

メソッドの呼び出し

Response

参考資料

次のステップ

その他のリソース

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

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

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