次の方法で共有

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

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

注

この記事で説明されている機能は、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 アプリケーション プロパティ) を通じてダイレクト メソッドを受け取ります。

注

デバイス上で直接メソッドを呼び出す場合、プロパティ名と値には、次のセットに属するものを除き、US-ASCII で印刷可能な英数字のみを含めることができます: $ ( ) < > @ , ; : \ " / [ ] ? = { } SP HT

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

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

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

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

バックエンド アプリからダイレクト メソッドを呼び出すには、Devices - Invoke 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 状態コードが返されます。

注

前の例は、デバイスでダイレクト メソッドを呼び出す方法を示しています。 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 モジュールのメソッド呼び出し

モジュールでダイレクト メソッドを呼び出すには、 Modules - Invoke メソッド 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 プロトコルを使用して IoT ハブと通信する」を参照してください。

メソッドの呼び出し

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

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

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

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

[応答]

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

  • status プロパティは、デバイスから提供される、メソッド実行の状態です。

  • $rid プロパティは、IoT Hub から受け取るメソッド呼び出しの要求 ID です。 要求 ID は、16 進形式の値です。

デバイスは本文を設定し、任意の状態にすることができます。

AMQP

次のセクションでは、AMQP プロトコルを扱います。 IoT Hub で直接 AMQP プロトコルを使用する方法の詳細については、「AMQP プロトコルを使用して IoT ハブと通信する」を参照してください。

メソッドの呼び出し

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

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

  • 関連付け ID プロパティ。対応するメソッド応答で戻される要求 ID が含まれています。

  • IoThub-methodname という名前のアプリケーション プロパティ。呼び出されるメソッドの名前が含まれています。

  • AMQP メッセージ本文。JSON としてメソッド ペイロードが含まれています。

[応答]

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

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

  • 関連付け ID プロパティ。メソッドの要求メッセージで渡される要求 ID が含まれています。

  • IoThub-status という名前のアプリケーション プロパティ。ユーザーが指定したメソッド状態が含まれています。

  • AMQP メッセージ本文。JSON としてメソッド応答が含まれています。

次のステップ

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