通过

了解和调用 IoT 中心的直接方法

IoT 中心直接方法使你能够从云中远程调用设备上的调用。 直接方法遵循请求-响应模式，适用于需要立即确认其结果的通信。 例如对设备的交互式控制，如打开风扇。 此功能用于即时操作过程不同的情况，即时操作的不同取决于设备能否响应。

注意

本文所述的功能只能用于 IoT 中心的标准层。 有关基本层和标准/免费 IoT 中心层的详细信息，请参阅 为解决方案选择正确的 IoT 中心层和大小。

每个设备方法针对一个设备。 如果你希望对多个设备调用直接方法，或者为已断开连接的设备计划方法调用，请参阅在多个设备上计划作业。

在 IoT 中心具有 服务连接 权限的任何人都可以在设备上调用方法。

如果在使用所需属性、直接方法或云到设备消息之间有疑问，请参阅 云到设备通信指南 。

方法生命周期

直接方法在设备上实现，可能需要在方法负载中包含零个或多个输入才能正确实例化。 可以通过面向服务的 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、基于 WebSocket 的 MQTT 或 基于 WebSockets 的 AMQP 调用。

方法请求和响应的有效负载为最大 128 KB 的 JSON 文档。

从后端应用调用直接方法

若要从后端应用调用直接方法，请使用 设备 - 调用方法 REST API 或其等效方法之一的 IoT 中心服务 SDK。

方法调用

设备上的直接方法调用是 HTTPS 调用，它由以下项构成：

  • 特定于设备的请求 URI 以及 API 版本：

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

  • POST 方法

  • 标头，包含身份验证、内容类型和内容编码。

  • 透明的 JSON 正文 ，采用以下格式：

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

在请求中作为 responseTimeoutInSeconds 提供的值是 IoT 中心服务在设备上执行直接方法所需等待的时间。 将此超时设置为至少与设备直接方法的预期执行时间一样长。 如果未提供超时值，则使用默认值 30 秒。 responseTimeoutInSeconds 的最小值和最大值分别为 5 秒和 300 秒。

在请求中作为 connectTimeoutInSeconds 提供的值是在调用直接方法后，IoT 中心服务等待断开连接的服务进入联机状态所需的时间。 默认值为 0，表示在调用直接方法时，设备必须已处于联机状态。 connectTimeoutInSeconds 的最大值为 300 秒。

示例

此示例发起一个请求，以调用已注册到 Azure IoT 中心的 IoT 设备上的直接方法。

若要开始，请使用适用于 Azure CLI 的 Azure IoT 扩展创建 SharedAccessSignature。

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

接下来，将 Authorization 标头替换为新生成的 SharedAccessSignature，然后修改 iothubName、deviceId、methodName 和 payload 参数，使之与下面的示例 curl 命令中的实现匹配。

curl -X POST \
  https://<iothubName>.azure-devices.cn/twins/<deviceId>/methods?api-version=2021-04-12 \
  -H 'Authorization: SharedAccessSignature sr=iothubname.azure-devices.cn&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.cn/twins/<deviceId>/modules/<moduleName>/methods?api-version=2021-04-12

响应

后端应用接收响应，响应由以下项构成：

  • HTTP 状态代码：

    • 200 表示成功执行直接方法；
    • 404 表示设备 ID 无效，或者设备在调用直接方法及其后的一段时间内未联机（请使用附带的错误消息以了解根本原因）；
    • 504 表示由于设备未在 responseTimeoutInSeconds 内响应直接方法调用而导致的网关超时。

  • 标头，包含 请求 ID、内容类型和内容编码。

  • 采用以下格式的 JSON 正文：

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

    status 和 payload 均由设备提供，用于应对设备自身的状态代码和方法响应。

IoT Edge 模块的方法调用

若要在模块上调用直接方法，请使用 Modules - Invoke 方法 REST API 或其等效方法之一的 IoT 中心服务 SDK。

使用 REST API 时，moduleId 将与请求 URI 中的 deviceId 一起传递；使用服务 SDK 时，作为参数传递。 例如 https://<iothubName>.azure-devices.net/twins/<deviceId>/modules/<moduleName>/methods?api-version=2021-04-12。 请求正文和响应类似于设备上调用的直接方法。

处理针对设备的直接方法

在 IoT 设备上，可以通过 MQTT、AMQP 或 WebSocket 上的任一协议接收直接方法。 IoT 中心设备 SDK 可帮助接收和响应设备上的直接方法，而无需担心基础协议详细信息。

MQTT

以下部分适用于 MQTT 协议。 若要详细了解如何将 MQTT 协议直接与 IoT 中心配合使用，请参阅 使用 MQTT 协议与 IoT 中心通信。

方法调用

设备通过 MQTT 主题接收直接方法请求：$iothub/methods/POST/{method name}/?$rid={request id}。 但是，无法提前知道request id，因为它由 IoT 中心生成，因此请订阅$iothub/methods/POST/#，然后根据您的设备支持的方法名称筛选接收到的消息。 使用生成的 request id 响应。

设备接收的正文采用以下格式：

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

方法请求为 QoS 0。

响应

设备将响应发送到 $iothub/methods/res/{status}/?$rid={request id}，其中：

  • status 属性是设备提供的方法执行状态。

  • $rid 属性是从 IoT 中心接收的方法调用中的请求 ID。 请求 ID 是一个十六进制格式的值。

设备可以设置主体，并且可以是任何状态。

AMQP

以下部分适用于 AMQP 协议。 若要详细了解如何将 AMQP 协议直接与 IoT 中心配合使用，请参阅 使用 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 中心开发人员指南文章感兴趣：

  • Last updated on