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

借助 IoT 中心,用户可以从云中对设备调用直接方法。 直接方法表示与设备进行的请求-答复式交互,类似于会立即成功或失败(在用户指定的超时时间后)的 HTTP 调用。 此方法用于即时操作过程不同的情况,即时操作的不同取决于设备能否响应。

Note

本文中所述的功能仅可在 IoT 中心的标准层中使用。 有关基本和标准 IoT 中心层的详细信息,请参阅如何选择合适的 IoT 中心层

每个设备方法针对一个设备。 在多个设备上计划作业展示了一种方法,用于对多个设备调用直接方法,并为已断开连接的设备计划方法调用。

只要拥有 IoT 中心的“服务连接”权限,任何人都可以调用设备上的方法。

直接方法遵循请求-响应模式,适用于需要立即确认其结果的通信。 例如对设备的交互式控制,如打开风扇。

如果在使用所需属性、直接方法或云到设备消息方面有任何疑问,请参阅 云到设备通信指南

方法生命周期

直接方法在设备上实现,可能需要在方法有效负载中进行 0 次或 0 次以上的输入才能正确地实例化。 可以通过面向服务的 URI ({iot hub}/twins/{device id}/methods/) 调用直接方法。 设备通过特定于设备的 MQTT 主题 ($iothub/methods/POST/{method name}/) 或通过 AMQP 链接(IoThub-methodnameIoThub-status 应用程序属性)接收直接方法。

Note

调用设备上的直接方法时,属性名称和值只能包含 US ASCII 可打印字母数字,但下列组中的任一项除外:{'$', '(', ')', '<', '>', '@', ',', ';', ':', '\', '"', '/', '[', ']', '?', '=', '{', '}', SP, HT}

直接方法是同步的,在超时期限(默认:30 秒,最长可设置为 3600 秒)过后,其结果不是成功就是失败。 直接方法适用于交互式场景,即当且仅当设备处于联机状态且可接收命令时,用户希望设备做出响应。 例如,打开手机的灯。 在此类方案中,用户需要立即看到结果是成功还是失败,以便云服务可以尽快根据结果进行操作。 设备可能返回某些消息正文作为方法的结果,但系统不会要求方法一定这样做。 无法保证基于方法调用的排序或者任何并发语义。

直接方法从云端只能通过 HTTPS 调用,从设备端可以通过 MQTT 或 AMQP 调用。

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

从后端应用调用直接方法

现在,从后端应用调用某个直接方法。

方法调用

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

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

    https://fully-qualified-iothubname.azure-devices.cn/twins/{deviceId}/methods?api-version=2018-06-30
    
  • POST 方法

  • 标头,包含身份验证、请求 ID、内容类型和内容编码
  • 透明的 JSON 正文 ,采用以下格式:

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

超时以秒为单位。 如果未设置超时,则默认为 30 秒。

示例

有关使用 curl 的精简示例,请参阅下方。

curl -X POST \
  https://iothubname.azure-devices.cn/twins/myfirstdevice/methods?api-version=2018-06-30 \
  -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 状态代码,用于 IoT 中心发出的错误,包括 404 错误(针对当前未连接的设备)
  • 标头,包含 ETag、请求 ID、内容类型和内容编码
  • 采用以下格式的 JSON 正文:

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

    statusbody 均由设备提供,用于响应,其中包含设备自身的状态代码和/或描述。

IoT Edge 模块的方法调用

IoT 服务客户端 C# SDK 中支持使用模块 ID 调用直接方法。

为此,请使用 ServiceClient.InvokeDeviceMethodAsync() 方法并传入 deviceIdmoduleId 作为参数。

处理针对设备的直接方法

让我们看看如何在 IoT 设备上处理直接方法。

MQTT

以下部分适用于 MQTT 协议。

方法调用

设备通过 MQTT 主题接收直接方法请求:$iothub/methods/POST/{method name}/?$rid={request id}。 每个设备的订阅数限制为 5。 因此,建议不要单独订阅每种直接方法。 而是考虑订阅 $iothub/methods/POST/#,然后根据所需的方法名称筛选传递的消息。

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

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

方法请求为 QoS 0。

响应

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

  • status 属性是设备提供的方法执行状态。
  • $rid 属性是从 IoT 中心接收的方法调用中的请求 ID。

正文由设备设置,可以是任何状态。

AMQP

以下部分适用于 AMQP 协议。

方法调用

设备通过在地址 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 中心开发人员指南中的其他参考主题包括:

后续步骤

了解如何使用直接方法后,可根据兴趣参阅以下 IoT 中心开发人员指南文章:

若要尝试本文中介绍的一些概念,可以根据兴趣学习以下 IoT 中心教程: