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 レベルの IoT Hub の詳細については、適切な IoT Hub レベルの選択に関するページを参照してください。For more information about the basic and standard 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 秒、最長 300 秒に設定可能)。Direct methods are synchronous and either succeed or fail after the timeout period (default: 30 seconds, settable up to 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:

    https://fully-qualified-iothubname.azure-devices.net/twins/{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"
        }
    }
    

タイムアウトは秒単位です。Timeout is in seconds. タイムアウトが設定されていない場合の既定値は 30 秒です。If timeout is not set, it defaults to 30 seconds.

Example

curl を使用したベアボーンの例については、以下を参照してください。See below for a barebone example using curl.

curl -X POST \
  https://iothubname.azure-devices.net/twins/myfirstdevice/methods?api-version=2018-06-30 \
  -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"
    }
}'

ResponseResponse

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

  • HTTP 状態コード。接続されていないデバイスの 404 エラーを含む、IoT Hub からのエラーに使用される。HTTP status code, which is used for errors coming from the IoT Hub, including a 404 error for devices not currently connected.

  • ヘッダー。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.

MQTTMQTT

次のセクションでは、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.

ResponseResponse

デバイスは応答を $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.

AMQPAMQP

次のセクションでは、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.

ResponseResponse

デバイスは、メソッド応答を返す送信リンクをアドレス 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: