IoT Hub からのダイレクト メソッドの呼び出しについてUnderstand and invoke direct methods from IoT Hub

IoT Hub には、クラウドからデバイス上のダイレクト メソッドを呼び出す機能が備わっています。IoT Hub gives you the ability to invoke direct methods on devices from the cloud. ダイレクト メソッドは、デバイスとの要求/応答型通信を表し、すぐに要求の成功または失敗が確定する (ユーザーが指定したタイムアウト後) という点で HTTP 呼び出しに似ています。Direct methods represent a request-reply interaction with a device similar to an HTTP call in that they succeed or fail immediately (after a user-specified timeout). この方法は、デバイスが応答できるかどうかに応じて即座に実行するアクションが異なるシナリオで便利です。This approach is useful for scenarios where the course of immediate action is different depending on whether the device was able to respond.


この記事で説明されている機能は、Standard レベルの IoT Hub でのみ使用できます。The features described in this article are available only in the standard tier of IoT Hub. Basic および Standard または Free レベルの IoT Hub の詳細については、適切な IoT Hub レベルの選択に関するページを参照してください。For more information about the basic and standard/free IoT Hub tiers, see Choose the right IoT Hub tier.

各デバイス メソッドは、1 つのデバイスをターゲットとします。Each device method targets a single device. 複数デバイスでのジョブをスケジュール設定する」では、複数のデバイス上のダイレクト メソッドを呼び出し、接続されていないデバイスに対するメソッドの呼び出しをスケジュール設定する方法を紹介しています。Schedule jobs on multiple devices shows how to provide a way to invoke direct methods on multiple devices, and schedule method invocation for disconnected devices.

IoT Hub でサービス接続のアクセス許可を持っていれば、誰でもデバイスでメソッドを呼び出すことができます。Anyone with service connect permissions on IoT Hub may invoke a method on a device.

ダイレクト メソッドは要求/応答型パターンに従うメソッドであり、結果をすぐに確認する必要がある通信向けです。Direct methods follow a request-response pattern and are meant for communications that require immediate confirmation of their result. たとえばデバイスを対話式で制御する (例: ファンをオンにする) ときに使用されます。For example, interactive control of the device, such as turning on a fan.

必要とされるプロパティ、ダイレクト メソッド、または C2D メッセージの使用方法の詳細については、「cloud-to-device 通信に関するガイダンス」を参照してください。Refer to Cloud-to-device communication guidance if in doubt between using desired properties, direct methods, or cloud-to-device messages.

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

ダイレクト メソッドはデバイス上に実装され、正しくインスタンス化するには、メソッドのペイロードに 0 個以上の入力が必要になります。Direct methods are implemented on the device and may require zero or more inputs in the method payload to correctly instantiate. ダイレクト メソッドは、サービス向け URI ({iot hub}/twins/{device id}/methods/) を通じて呼び出します。You invoke a direct method through a service-facing URI ({iot hub}/twins/{device id}/methods/). デバイスは、デバイス固有の MQTT トピック ($iothub/methods/POST/{method name}/) または AMQP リンク (IoThub-methodname および IoThub-status アプリケーション プロパティ) を通じてダイレクト メソッドを受け取ります。A device receives direct methods through a device-specific MQTT topic ($iothub/methods/POST/{method name}/) or through AMQP links (the IoThub-methodname and IoThub-status application properties).


デバイス上のダイレクト メソッドを呼び出す場合、プロパティ名と値には {'$', '(', ')', '<', '>', '@', ',', ';', ':', '\', '"', '/', '[', ']', '?', '=', '{', '}', SP, HT} を除く US-ASCII 印刷可能英数字のみを使用できます。When you invoke a direct method on a device, property names and values can only contain US-ASCII printable alphanumeric, except any in the following set: {'$', '(', ')', '<', '>', '@', ',', ';', ':', '\', '"', '/', '[', ']', '?', '=', '{', '}', SP, HT}

ダイレクト メソッドは同期型であり、タイムアウト期間後に成功または失敗します (既定では30 秒、5 - 300 秒の範囲で設定可能)。Direct methods are synchronous and either succeed or fail after the timeout period (default: 30 seconds, settable between 5 and 300 seconds). ダイレクト メソッドは、デバイスがオンラインでコマンドを受け取っている場合のみデバイスを操作する対話型のシナリオで便利です。Direct methods are useful in interactive scenarios where you want a device to act if and only if the device is online and receiving commands. たとえば、携帯電話からの照明を点灯させる場合です。For example, turning on a light from a phone. このようなシナリオでは、成功か失敗かを即座に確認し、クラウド サービスがその結果に対してできるだけ早く対応することが必要になります。In these scenarios, you want to see an immediate success or failure so the cloud service can act on the result as soon as possible. デバイスはメッセージの結果として何らかのメッセージ本文を返すことがありますが、メソッドにはその機能は必要ありません。The device may return some message body as a result of the method, but it isn't required for the method to do so. 順番の保証や、メソッドの呼び出しのコンカレンシー セマンティクスはありません。There is no guarantee on ordering or any concurrency semantics on method calls.

ダイレクト メソッドは、クラウド側からは HTTPS のみに、デバイス側からは MQTT または AMQP になります。Direct methods are HTTPS-only from the cloud side, and MQTT or AMQP from the device side.

メソッドの要求および応答のペイロードは、最大 128 KB の JSON ドキュメントになります。The payload for method requests and responses is a JSON document up to 128 KB.

バックエンド アプリからダイレクト メソッドを呼び出すInvoke a direct method from a back-end app

次に、バックエンド アプリからダイレクト メソッドを呼び出します。Now, invoke a direct method from a back-end app.

メソッドの呼び出しMethod invocation

デバイスでのダイレクト メソッドの呼び出しは HTTPS 呼び出しであり、次で構成されます。Direct method invocations on a device are HTTPS calls that are made up of the following items:

  • API バージョンが適合するデバイスに固有の要求の URI:The request URI specific to the device along with the API version:{deviceId}/methods?api-version=2018-06-30
  • POST メソッドThe POST method

  • ヘッダー。承認、要求 ID、コンテンツの種類、コンテンツのエンコーディングを含む。Headers that contain the authorization, request ID, content type, and content encoding.

  • 透過的な JSON 本文。次の形式になります。A transparent JSON body in the following format:

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

要求で responseTimeoutInSeconds として指定された値は、IoT Hub サービスがデバイスでのダイレクト メソッドの実行が完了するまで待機する必要がある時間です。The value provided as responseTimeoutInSeconds in the request is the amount of time that IoT Hub service must await for completion of a direct method execution on a device. このタイムアウトは、少なくとも、デバイスによるダイレクト メソッドの予想実行時間と同じ長さに設定してください。Set this timeout to be at least as long as the expected execution time of a direct method by a device. タイムアウトが指定されていない場合は、既定値の 30 秒が使用されます。If timeout is not provided, it the default value of 30 seconds is used. responseTimeoutInSeconds の最小値は 5 秒で、最大値は 300 秒です。The minimum and maximum values for responseTimeoutInSeconds are 5 and 300 seconds, respectively.

要求で connectTimeoutInSeconds として指定された値は、ダイレクト メソッドの呼び出し時に、IoT Hub サービスが接続されていないデバイスがオンラインになるまで待機する必要がある時間です。The value provided as connectTimeoutInSeconds in the request is the amount of time upon invocation of a direct method that IoT Hub service must await for a disconnected device to come online. 既定値は 0 です。これは、ダイレクト メソッドの呼び出し時にデバイスが既にオンラインである必要があることを意味します。The default value is 0, meaning that devices must already be online upon invocation of a direct method. connectTimeoutInSeconds の最大値は 300 秒です。The maximum value for connectTimeoutInSeconds is 300 seconds.


この例では、Azure IoT Hub に登録されている IoT デバイス上でダイレクト メソッドを呼び出すための要求を安全に開始することができます。This example will allow you to securely initiate a request to invoke a Direct Method on an IoT device registered to an Azure IoT Hub.

まず、Azure CLI 用の Microsoft Azure IoT 拡張機能を使用して、SharedAccessSignature を作成します。To begin, use the Microsoft Azure IoT extension for Azure CLI to create a SharedAccessSignature.

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

次に、Authorization ヘッダーを、新しく生成された SharedAccessSignature に置き換えます。次に、以下の curl コマンドの例の実装に一致するように、iothubNamedeviceIdmethodName、および payload パラメーターを変更します。Next, replace the Authorization header with your newly generated SharedAccessSignature, then modify the iothubName, deviceId, methodName and payload parameters to match your implementation in the example curl command below.

curl -X POST \
  https://<iothubName><deviceId>/methods?api-version=2018-06-30 \
  -H 'Authorization: SharedAccessSignature' \
  -H 'Content-Type: application/json' \
  -d '{
    "methodName": "reboot",
    "responseTimeoutInSeconds": 200,
    "payload": {
        "input1": "someInput",
        "input2": "anotherInput"

変更したコマンドを実行して、指定したダイレクト メソッドを呼び出します。Execute the modified command to invoke the specified Direct Method. 要求が成功すると、HTTP 200 状態コードが返されます。Successful requests will return an HTTP 200 status code.


上の例は、デバイスでダイレクト メソッドを呼び出す方法を示しています。The above example demonstrates invoking a Direct Method on a device. IoT Edge モジュールでダイレクト メソッドを呼び出す場合は、次に示すように URL 要求を変更する必要があります。If you wish to invoke a Direct Method in an IoT Edge Module, you would need to modify the url request as shown below:



バックエンド アプリは、次の項目で構成されている応答を受け取ります。The back-end app receives a response that is made up of the following items:

  • HTTP 状態コード:HTTP status code:

    • 200 は、ダイレクト メソッドが正常に実行されたことを示します。200 indicates successful execution of direct method;
    • 404 は、デバイス ID が無効であること、またはダイレクト メソッドの呼び出し時とその後 connectTimeoutInSeconds の間、デバイスがオンラインになっていなかったことを示します (根本原因を把握するには、付随するエラー メッセージを使用してください)。404 indicates that either device ID is invalid, or that the device was not online upon invocation of a direct method and for connectTimeoutInSeconds thereafter (use accompanied error message to understand the root cause);
    • 504 は、responseTimeoutInSeconds 内のダイレクト メソッドの呼び出しにデバイスが応答していないことが原因で、ゲートウェイのタイムアウトが発生したことを示します。504 indicates gateway timeout caused by device not responding to a direct method call within responseTimeoutInSeconds.
  • ヘッダー。ETag、要求 ID、コンテンツの種類、コンテンツのエンコーディングを含む。Headers that contain the ETag, request ID, content type, and content encoding.

  • JSON 本文。次の形式になります。A JSON body in the following format:

        "status" : 201,
        "payload" : {...}

    statusbody の両方ともデバイスによって提供され、デバイス自身の状態コードまたは説明とともに応答する場合に使用されます。Both status and body are provided by the device and used to respond with the device's own status code and/or description.

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

モジュール ID を使用したダイレクト メソッドの呼び出しは、IoT Service Client C# SDK でサポートされています。Invoking direct methods using a module ID is supported in the IoT Service Client C# SDK.

この目的で、ServiceClient.InvokeDeviceMethodAsync() メソッドを使用し、deviceIdmoduleId をパラメーターとして渡します。For this purpose, use the ServiceClient.InvokeDeviceMethodAsync() method and pass in the deviceId and moduleId as parameters.

デバイスでダイレクト メソッドを処理するHandle a direct method on a device

IoT デバイスでダイレクト メソッドを処理する方法を見てみましょう。Let's look at how to handle a direct method on an IoT device.


次のセクションでは、MQTT プロトコルを扱います。The following section is for the MQTT protocol.

メソッドの呼び出しMethod invocation

デバイスは MQTT トピックに関するダイレクト メソッド要求を受け取ります ($iothub/methods/POST/{method name}/?$rid={request id})。Devices receive direct method requests on the MQTT topic: $iothub/methods/POST/{method name}/?$rid={request id}. デバイスごとのサブスクリプションの数は 5 に制限されます。The number of subscriptions per device is limited to 5. そのため、各ダイレクト メソッドを個別にサブスクライブしないことをお勧めします。It is therefore recommended not to subscribe to each direct method individually. その代わり、$iothub/methods/POST/# をサブスクライブし、届けられたメッセージをメソッド名に基づいてフィルター処理することを検討してください。Instead consider subscribing to $iothub/methods/POST/# and then filter the delivered messages based on your desired method names.

デバイスが受け取る本文は次の形式になります。The body that the device receives is in the following format:

    "input1": "someInput",
    "input2": "anotherInput"

メソッドの要求は QoS 0 です。Method requests are QoS 0.


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

  • status プロパティは、デバイスから提供される、メソッド実行の状態です。The status property is the device-supplied status of method execution.

  • $rid プロパティは、IoT Hub から受け取るメソッド呼び出しの要求 ID です。The $rid property is the request ID from the method invocation received from IoT Hub.

本文はデバイスごとに設定され、任意の状態を設定できます。The body is set by the device and can be any status.


次のセクションでは、AMQP プロトコルを扱います。The following section is for the AMQP protocol.

メソッドの呼び出しMethod invocation

デバイスは、アドレス amqps://{hostname}:5671/devices/{deviceId}/methods/deviceBound に受信リンクを作成することによってダイレクト メソッド要求を受け取ります。The device receives direct method requests by creating a receive link on address amqps://{hostname}:5671/devices/{deviceId}/methods/deviceBound.

AMQP メッセージは、メソッド要求を表す受信リンクに到着します。The AMQP message arrives on the receive link that represents the method request. 次のセクションが含まれます。It contains the following sections:

  • 関連付け ID プロパティ。対応するメソッド応答で戻される要求 ID が含まれています。The correlation ID property, which contains a request ID that should be passed back with the corresponding method response.

  • IoThub-methodname という名前のアプリケーション プロパティ。呼び出されるメソッドの名前が含まれています。An application property named IoThub-methodname, which contains the name of the method being invoked.

  • AMQP メッセージ本文。JSON としてメソッド ペイロードが含まれています。The AMQP message body containing the method payload as JSON.


デバイスは、メソッド応答を返す送信リンクをアドレス amqps://{hostname}:5671/devices/{deviceId}/methods/deviceBound に作成します。The device creates a sending link to return the method response on address amqps://{hostname}:5671/devices/{deviceId}/methods/deviceBound.

メソッドの応答は送信リンクで返され、以下のもので構成されています。The method's response is returned on the sending link and is structured as follows:

  • 関連付け ID プロパティ。メソッドの要求メッセージで渡される要求 ID が含まれています。The correlation ID property, which contains the request ID passed in the method's request message.

  • IoThub-status という名前のアプリケーション プロパティ。ユーザーが指定したメソッド状態が含まれています。An application property named IoThub-status, which contains the user supplied method status.

  • AMQP メッセージ本文。JSON としてメソッド応答が含まれています。The AMQP message body containing the method response as JSON.

参考資料Additional reference material

IoT Hub 開発者ガイド内の他の参照トピックは次のとおりです。Other reference topics in the IoT Hub developer guide include:

次のステップNext steps

ダイレクト メソッドの使用方法を理解できたら、次の IoT Hub 開発者ガイドの記事も参考にしてください。Now you have learned how to use direct methods, you may be interested in the following IoT Hub developer guide article:

この記事で説明した概念を試す場合は、次の IoT Hub のチュートリアルをご利用ください。If you would like to try out some of the concepts described in this article, you may be interested in the following IoT Hub tutorial: