你当前正在访问 Microsoft Azure Global Edition 技术文档网站。 如果需要访问由世纪互联运营的 Microsoft Azure 中国技术文档网站,请访问 https://docs.azure.cn。
IoTHubModuleClient 类
连接到 Azure IoT 中心 或 Azure IoT Edge 实例的同步模块客户端。
IoTHubModuleClient 的初始值设定项。
不应直接调用此初始值设定项。 请改用“create_from_<<”>>类方法之一进行实例化
- 继承
-
azure.iot.device.iothub.sync_clients.GenericIoTHubClientIoTHubModuleClientazure.iot.device.iothub.abstract_clients.AbstractIoTHubModuleClientIoTHubModuleClient
构造函数
IoTHubModuleClient(mqtt_pipeline, http_pipeline)
参数
- mqtt_pipeline
- <xref:azure.iot.device.iothub.pipeline.MQTTPipeline>
用于连接到 IoTHub 终结点的管道。
- http_pipeline
- <xref:azure.iot.device.iothub.pipeline.HTTPPipeline>
用于通过 HTTP 连接到 IoTHub 终结点的管道。
方法
connect |
将客户端连接到 Azure IoT 中心 或 Azure IoT Edge 中心实例。 根据通过初始化此对象时提供的 auth_provider 参数传递的凭据选择目标。 这是一个同步调用,这意味着此函数在与服务的连接完全建立之前不会返回。 |
create_from_connection_string |
从 IoTHub 设备或模块连接字符串实例化客户端。 |
create_from_edge_environment |
从IoT Edge环境实例化客户端。 此方法只能从 IoT Edge 容器内部运行,或者在为 Edge 开发配置 (调试环境中运行,例如 Visual Studio,Visual Studio Code) |
create_from_sastoken |
从预先创建的 SAS 令牌字符串实例化客户端 |
create_from_x509_certificate |
使用 X509 证书身份验证实例化客户端。 |
disconnect |
断开客户端与 Azure IoT 中心 或 Azure IoT Edge 中心实例的连接。 建议在完全完成客户端实例后,确保调用此函数。 这是一个同步调用,这意味着在与服务的连接完全关闭之前,此函数不会返回。 |
get_twin |
从 Azure IoT 中心 或 Azure IoT Edge 中心服务获取设备或模块孪生。 这是一个同步调用,这意味着此函数在从服务中检索孪生体之前不会返回。 |
invoke_method |
将方法从客户端调用到设备或模块客户端,并接收对方法调用的响应。 |
patch_twin_reported_properties |
使用 Azure IoT 中心 或 Azure IoT Edge 中心服务更新报告的属性。 这是一个同步调用,这意味着此函数在修补程序已发送到服务并得到确认之前不会返回。 如果服务在修补操作上返回错误,此函数将引发相应的错误。 |
receive_message_on_input |
接收已从另一个模块发送到特定输入的输入消息。 自版本 2.3.0 以来已弃用:建议改用 .on_message_received 属性来设置处理程序 |
receive_method_request |
通过 Azure IoT 中心 或 Azure IoT Edge 中心接收方法请求。 自版本 2.3.0 以来已弃用:建议改用 .on_method_request_received 属性来设置处理程序 |
receive_twin_desired_properties_patch |
通过 Azure IoT 中心 或 Azure IoT Edge 中心接收所需的属性修补程序。 这是一个同步调用,这意味着以下内容:
自版本 2.3.0 以来已弃用:建议改用 .on_twin_desired_properties_patch_received 属性来设置处理程序 |
send_message |
将消息发送到 Azure IoT 中心 或 Azure IoT Edge 中心实例上的默认事件终结点。 这是一个同步事件,这意味着此函数在事件已发送到服务且服务确认收到事件之前不会返回。 如果之前尚未通过调用连接来打开与服务的连接,则此函数将在发送事件之前打开连接。 |
send_message_to_output |
将事件/消息发送到给定的模块输出。 这些是传出事件,是“输出事件”。 这是一个同步事件,这意味着此函数在事件已发送到服务且服务确认收到事件之前不会返回。 如果之前尚未通过调用连接来打开与服务的连接,则此函数将在发送事件之前打开连接。 |
send_method_response |
通过 Azure IoT 中心 或 Azure IoT Edge 中心向方法请求发送响应。 这是一个同步事件,这意味着此函数在事件已发送到服务且服务确认收到事件之前不会返回。 如果之前尚未通过调用连接来打开与服务的连接,则此函数将在发送事件之前打开连接。 |
shutdown |
关闭客户端以正常退出。 调用此方法后,进一步客户端调用的任何尝试都将导致引发 ClientError |
update_sastoken |
更新客户端用于身份验证的 SAS 令牌,然后重新授权连接。 仅当客户端最初是使用 SAS 令牌创建的时,才能使用此 API。 |
connect
将客户端连接到 Azure IoT 中心 或 Azure IoT Edge 中心实例。
根据通过初始化此对象时提供的 auth_provider 参数传递的凭据选择目标。
这是一个同步调用,这意味着此函数在与服务的连接完全建立之前不会返回。
connect()
例外
如果凭据无效且无法建立连接,则为 。
如果建立连接导致失败,则为 。
如果连接在执行期间丢失,则为 。
如果连接超时,则为 。
如果在执行期间出现意外故障,则为 。
create_from_connection_string
从 IoTHub 设备或模块连接字符串实例化客户端。
create_from_connection_string(connection_string, **kwargs)
参数
返回
使用连接字符串进行身份验证的 IoTHub 客户端的实例。
例外
create_from_edge_environment
从IoT Edge环境实例化客户端。
此方法只能从 IoT Edge 容器内部运行,或者在为 Edge 开发配置 (调试环境中运行,例如 Visual Studio,Visual Studio Code)
create_from_edge_environment(**kwargs)
参数
返回
使用 IoT Edge 环境进行身份验证的 IoTHub 客户端的实例。
例外
create_from_sastoken
从预先创建的 SAS 令牌字符串实例化客户端
create_from_sastoken(sastoken, **kwargs)
参数
例外
create_from_x509_certificate
使用 X509 证书身份验证实例化客户端。
create_from_x509_certificate(x509, hostname, device_id, module_id, **kwargs)
参数
返回
使用 X509 证书进行身份验证的 IoTHub 客户端的实例。
例外
disconnect
断开客户端与 Azure IoT 中心 或 Azure IoT Edge 中心实例的连接。
建议在完全完成客户端实例后,确保调用此函数。
这是一个同步调用,这意味着在与服务的连接完全关闭之前,此函数不会返回。
disconnect()
例外
如果在执行期间发生意外失败,则为 。
get_twin
从 Azure IoT 中心 或 Azure IoT Edge 中心服务获取设备或模块孪生。
这是一个同步调用,这意味着此函数在从服务中检索孪生体之前不会返回。
get_twin()
返回
作为 JSON dict 的完整孪生体
返回类型
例外
如果凭据无效且无法建立连接,则为 。
如果建立连接导致失败,则为 。
如果在执行期间丢失连接,则为 。
如果连接尝试超时
如果客户端未 (连接,并且没有启用自动连接)
如果在执行期间发生意外失败,则为 。
invoke_method
将方法从客户端调用到设备或模块客户端,并接收对方法调用的响应。
invoke_method(method_params, device_id, module_id=None)
参数
- method_params
- dict
应包含 methodName (str) 、payload (str) 、connectTimeoutInSeconds (int) 、responseTimeoutInSeconds (int) 。
返回
method_result应包含状态和有效负载
返回类型
例外
如果凭据无效且无法建立连接,则为 。
如果建立连接导致失败,则为 。
如果连接在执行期间丢失,则为 。
如果连接超时,则为 。
如果在执行期间出现意外故障,则为 。
patch_twin_reported_properties
使用 Azure IoT 中心 或 Azure IoT Edge 中心服务更新报告的属性。
这是一个同步调用,这意味着此函数在修补程序已发送到服务并得到确认之前不会返回。
如果服务在修补操作上返回错误,此函数将引发相应的错误。
patch_twin_reported_properties(reported_properties_patch)
参数
例外
如果凭据无效且无法建立连接,则为 。
如果建立连接导致失败,则为 。
如果在执行期间丢失连接,则为 。
如果连接尝试超时
如果客户端未 (连接,并且没有启用自动连接)
如果在执行期间发生意外失败,则为 。
receive_message_on_input
接收已从另一个模块发送到特定输入的输入消息。
自版本 2.3.0 以来已弃用:建议改用 .on_message_received 属性来设置处理程序
receive_message_on_input(input_name, block=True, timeout=None)
参数
返回
发送到指定输入的消息;如果在阻塞期结束时未收到任何方法请求,则为 None。
例外
如果凭据无效且无法建立连接,则为 。
如果建立连接导致失败,则为 。
如果连接在执行期间丢失,则为 。
如果连接超时,则为 。
如果在执行期间出现意外故障,则为 。
receive_method_request
通过 Azure IoT 中心 或 Azure IoT Edge 中心接收方法请求。
自版本 2.3.0 以来已弃用:建议改用 .on_method_request_received 属性来设置处理程序
receive_method_request(method_name=None, block=True, timeout=None)
参数
返回
表示接收的方法请求的 MethodRequest 对象;如果在阻塞期结束时尚未收到任何方法请求,则为 None。
例外
如果凭据无效且无法建立连接,则为 。
如果建立连接导致失败,则为 。
如果连接在执行期间丢失,则为 。
如果连接超时,则为 。
如果在执行期间出现意外故障,则为 。
receive_twin_desired_properties_patch
通过 Azure IoT 中心 或 Azure IoT Edge 中心接收所需的属性修补程序。
这是一个同步调用,这意味着以下内容:
如果 block=True,则此函数将阻止,直到发生以下情况之一:
从 Azure IoT 中心 或 Azure IoT Edge 中心接收所需的属性修补程序。
超时期限(如果已提供)已过。 如果发生超时,此函数将引发 InboxEmpty 异常
如果 block=False,则此函数将返回管道可能已接收但尚未返回到应用程序的任何所需属性修补程序。 如果管道未收到所需的属性修补程序,此函数将引发 InboxEmpty 异常
自版本 2.3.0 以来已弃用:建议改用 .on_twin_desired_properties_patch_received 属性来设置处理程序
receive_twin_desired_properties_patch(block=True, timeout=None)
参数
返回
孪生所需属性修补程序作为 JSON dict;如果在阻塞期结束时未收到任何修补程序,则为 None
返回类型
例外
如果凭据无效且无法建立连接,则为 。
如果建立连接导致失败,则为 。
如果连接在执行期间丢失,则为 。
如果连接超时,则为 。
如果在执行期间出现意外故障,则为 。
send_message
将消息发送到 Azure IoT 中心 或 Azure IoT Edge 中心实例上的默认事件终结点。
这是一个同步事件,这意味着此函数在事件已发送到服务且服务确认收到事件之前不会返回。
如果之前尚未通过调用连接来打开与服务的连接,则此函数将在发送事件之前打开连接。
send_message(message)
参数
例外
如果凭据无效且无法建立连接,则为 。
如果建立连接导致失败,则为 。
如果连接在执行期间丢失,则为 。
如果连接尝试超时
如果客户端未 (连接,并且没有启用自动连接)
如果在执行期间出现意外故障,则为 。
send_message_to_output
将事件/消息发送到给定的模块输出。
这些是传出事件,是“输出事件”。
这是一个同步事件,这意味着此函数在事件已发送到服务且服务确认收到事件之前不会返回。
如果之前尚未通过调用连接来打开与服务的连接,则此函数将在发送事件之前打开连接。
send_message_to_output(message, output_name)
参数
例外
如果凭据无效且无法建立连接,则为 。
如果建立连接导致失败,则为 。
如果连接在执行期间丢失,则为 。
如果连接尝试超时
如果客户端未 (连接,并且没有启用自动连接)
如果在执行期间出现意外故障,则为 。
send_method_response
通过 Azure IoT 中心 或 Azure IoT Edge 中心向方法请求发送响应。
这是一个同步事件,这意味着此函数在事件已发送到服务且服务确认收到事件之前不会返回。
如果之前尚未通过调用连接来打开与服务的连接,则此函数将在发送事件之前打开连接。
send_method_response(method_response)
参数
例外
如果凭据无效且无法建立连接,则为 。
如果建立连接导致失败,则为 。
如果连接在执行期间丢失,则为 。
如果连接尝试超时
如果客户端未 (连接,并且没有启用自动连接)
如果在执行期间出现意外故障,则为 。
shutdown
update_sastoken
更新客户端用于身份验证的 SAS 令牌,然后重新授权连接。
仅当客户端最初是使用 SAS 令牌创建的时,才能使用此 API。
update_sastoken(sastoken)
参数
例外
如果凭据无效且无法重新建立连接,则为 。
如果重新建立连接导致失败,则为 。
如果连接在执行期间丢失,则为 。
如果重新授权尝试超时,则为 。
如果最初未使用 SAS 令牌创建客户端,则为 。
如果在执行期间出现意外故障,则为 。
属性
connected
只读属性,用于指示传输是否已连接。
on_background_exception
发生后台异常时,将调用处理程序函数或协同例程。
函数或协同例程定义应采用一个位置参数 (异常对象)
on_connection_state_change
将在连接状态更改时调用的处理程序函数或协同例程。
函数或协同例程定义不应采用位置参数。
on_message_received
接收输入消息时将调用的处理程序函数或协同例程。
函数定义或协同例程应 (对象) Message
on_method_request_received
接收方法请求时将调用的处理程序函数或协同例程。
请记得使用客户端的 .send_method_response () 方法确认函数中的方法请求或协同例程。
函数或协同例程定义应采用一个位置参数 (MethodRequest 对象)
on_new_sastoken_required
当客户端需要新的 SAS 令牌时将调用的处理程序函数或协同程序。 这会在 SAS 令牌过期前大约 2 分钟发生。 在 Windows 平台上,如果生存期超过大约 49 天,则不管 SAS 生存期有多长,在 49 天后都需要一个新令牌。
请注意,仅当使用通过 .create_from_sastoken () 方法创建的客户端时,才需要此处理程序。
可以在函数中提供新令牌,也可以使用客户端的 .update_sastoken () 方法进行协同例程。
函数或协同例程定义不应采用位置参数。
on_twin_desired_properties_patch_received
接收孪生所需属性修补程序时将调用的处理程序函数或协同例程。
函数或协同例程定义应采用一个位置参数 (JSON 字典对象形式的孪生体补丁)