你当前正在访问 Microsoft Azure Global Edition 技术文档网站。 如果需要访问由世纪互联运营的 Microsoft Azure 中国技术文档网站,请访问 https://docs.azure.cn

IoTHubModuleClient 类

连接到 Azure IoT 中心 或 Azure IoT Edge 实例的同步模块客户端。

继承
azure.iot.device.iothub.sync_clients.GenericIoTHubClient
IoTHubModuleClient
azure.iot.device.iothub.abstract_clients.AbstractIoTHubModuleClient
IoTHubModuleClient

构造函数

IoTHubModuleClient(mqtt_pipeline, http_pipeline)

参数

mqtt_pipeline
http_pipeline

方法

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 中心接收所需的属性修补程序。

这是一个同步调用,这意味着以下内容:

  1. 如果 block=True,则此函数将阻止,直到发生以下情况之一:

    • 从 Azure IoT 中心 或 Azure IoT Edge 中心接收所需的属性修补程序。

    • 超时期限(如果已提供)已过。 如果发生超时,此函数将引发 InboxEmpty 异常

  2. 如果 block=False,则此函数将返回管道可能已接收但尚未返回到应用程序的任何所需属性修补程序。 如果管道未收到所需的属性修补程序,此函数将引发 InboxEmpty 异常

自版本 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)

参数

connection_string
str
必需

要连接到的 IoTHub 的连接字符串。

server_verification_cert
str
必需

配置选项。 受信任的证书链。 使用连接到具有非标准信任根的终结点(例如协议网关)时是必需的。

websockets
bool
必需

配置选项。 默认值为 False。 如果基于 Websocket 使用 MQTT,则设置为 true。

cipher
strlist(str)
必需

配置选项。 密码套件 (TLS/SSL 的) ,作为“OpenSSL 密码列表格式”的字符串或密码套件字符串列表。

product_info
str
必需

配置选项。 默认值为空字符串。 字符串包含追加到用户代理字符串的任意产品信息。

proxy_options
ProxyOptions
必需

用于通过代理服务器发送流量的选项。

sastoken_ttl
int
必需

创建用于身份验证的 SasToken 的生存时间 (秒) 。 默认值为 3600 秒(1 小时)。

keep_alive
int
必需

与中转站通信之间的最长时间段(以秒为单位)。 如果没有交换其他消息,这将控制客户端将 ping 消息发送到中转站的速率。 如果未提供,将使用默认值 60 秒。

auto_connect
bool
必需

调用需要建立连接的方法时,自动将客户端连接到 IoTHub。 (默认值:True)

connection_retry
bool
必需

尝试重新建立断开的连接 (默认值:True)

connection_retry_interval
int
必需

尝试重新建立已删除的连接之间的间隔(以秒为单位) (默认值:10)

ensure_desired_properties
bool
必需

确保在重新连接时收到最新的所需属性修补程序, (Default:True)

返回

使用连接字符串进行身份验证的 IoTHub 客户端的实例。

例外

ValueError if given an invalid connection_string.
TypeError if given an unsupported parameter.

create_from_edge_environment

从IoT Edge环境实例化客户端。

此方法只能从 IoT Edge 容器内部运行,或者在为 Edge 开发 (配置的调试环境中运行,例如 Visual Studio,Visual Studio Code)

create_from_edge_environment(**kwargs)

参数

websockets
bool
必需

配置选项。 默认值为 False。 如果基于 Websocket 使用 MQTT,则设置为 true。

cipher
strlist(str)
必需

配置选项。 密码套件 (TLS/SSL 的) ,作为“OpenSSL 密码列表格式”的字符串或密码套件字符串列表。

product_info
str
必需

配置选项。 默认值为空字符串。 字符串包含追加到用户代理字符串的任意产品信息。

proxy_options
ProxyOptions
必需

用于通过代理服务器发送流量的选项。

sastoken_ttl
int
必需

创建用于身份验证的 SasToken 的生存时间 (秒) 。 默认值为 3600 秒 (1 小时)

keep_alive
int
必需

与中转站通信之间的最长时间段(以秒为单位)。 如果没有交换其他消息,这将控制客户端将 ping 消息发送到中转站的速率。 如果未提供,将使用默认值 60 秒。

auto_connect
bool
必需

调用需要建立连接的方法时,自动将客户端连接到 IoTHub。 (默认值:True)

connection_retry
bool
必需

尝试重新建立断开的连接 (默认值:True)

connection_retry_interval
int
必需

尝试重新建立已删除的连接之间的间隔(以秒为单位) (默认值:10)

返回

使用 IoT Edge 环境进行身份验证的 IoTHub 客户端的实例。

例外

OSError if the IoT Edge container is not configured correctly.
ValueError if debug variables are invalid.
TypeError if given an unsupported parameter.

create_from_sastoken

从预先创建的 SAS 令牌字符串实例化客户端

create_from_sastoken(sastoken, **kwargs)

参数

sastoken
str
必需

SAS 令牌字符串

server_verification_cert
str
必需

配置选项。 受信任的证书链。 使用连接到具有非标准信任根的终结点(例如协议网关)时是必需的。

gateway_hostname
str
必需

配置选项。 网关设备的网关主机名。

websockets
bool
必需

配置选项。 默认值为 False。 如果基于 Websocket 使用 MQTT,则设置为 true。

cipher
strlist(str)
必需

配置选项。 密码套件 (TLS/SSL 的) ,作为“OpenSSL 密码列表格式”的字符串或密码套件字符串列表。

product_info
str
必需

配置选项。 默认值为空字符串。 字符串包含追加到用户代理字符串的任意产品信息。

proxy_options
ProxyOptions
必需

用于通过代理服务器发送流量的选项。

keep_alive
int
必需

与中转站通信之间的最长时间段(以秒为单位)。 如果没有交换其他消息,这将控制客户端将 ping 消息发送到中转站的速率。 如果未提供,将使用默认值 60 秒。

auto_connect
bool
必需

调用需要建立连接的方法时,自动将客户端连接到 IoTHub。 (默认值:True)

connection_retry
bool
必需

尝试重新建立断开的连接 (默认值:True)

connection_retry_interval
int
必需

尝试重新建立已删除的连接之间的间隔(以秒为单位) (默认值:10)

ensure_desired_properties
bool
必需

确保在重新连接时收到最新的所需属性修补程序, (Default:True)

例外

TypeError if given an unsupported parameter.
ValueError if the sastoken parameter is invalid.

create_from_x509_certificate

使用 X509 证书身份验证实例化客户端。

create_from_x509_certificate(x509, hostname, device_id, module_id, **kwargs)

参数

hostname
str
必需

运行 IotHub 的主机。 可以在“概述”选项卡的Azure 门户中找到字符串主机名。

x509
X509
必需

完整的 x509 证书对象。 若要使用证书,注册对象需要包含证书 (根证书或) 的一个中间 CA 证书。 如果证书来自 CER 文件,则需要进行 base64 编码。

device_id
str
必需

用于在 IoTHub 中唯一标识设备的 ID

module_id
str
必需

用于唯一标识 IoTHub 设备上模块的 ID。

server_verification_cert
str
必需

配置选项。 受信任的证书链。 使用连接到具有非标准信任根的终结点(例如协议网关)时是必需的。

gateway_hostname
str
必需

配置选项。 网关设备的网关主机名。

websockets
bool
必需

配置选项。 默认值为 False。 如果基于 Websocket 使用 MQTT,则设置为 true。

cipher
strlist(str)
必需

配置选项。 密码套件 (TLS/SSL 的) ,作为“OpenSSL 密码列表格式”的字符串或密码套件字符串列表。

product_info
str
必需

配置选项。 默认值为空字符串。 字符串包含追加到用户代理字符串的任意产品信息。

proxy_options
ProxyOptions
必需

用于通过代理服务器发送流量的选项。

keep_alive
int
必需

与中转站通信之间的最长时间段(以秒为单位)。 如果没有交换其他消息,这将控制客户端将 ping 消息发送到中转站的速率。 如果未提供,将使用默认值 60 秒。

auto_connect
bool
必需

调用需要建立连接的方法时,自动将客户端连接到 IoTHub。 (默认值:True)

connection_retry
bool
必需

尝试重新建立断开的连接 (默认值:True)

connection_retry_interval
int
必需

尝试重新建立已删除的连接之间的间隔(以秒为单位) (默认值:10)

ensure_desired_properties
bool
必需

确保在重新连接时收到最新的所需属性修补程序, (Default:True)

返回

使用 X509 证书进行身份验证的 IoTHub 客户端的实例。

例外

TypeError if given an unsupported parameter.

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) 。

device_id
str
必需

将在其中调用方法的目标设备的设备 ID。

module_id
str
默认值: None

将在其中调用方法的目标模块的模块 ID。 (可选)

返回

method_result应包含状态和有效负载

返回类型

例外

如果凭据无效且无法建立连接,则为 。

如果建立连接导致失败,则为 。

如果在执行期间丢失连接,则为 。

如果连接超时,则为 。

如果在执行期间发生意外失败,则为 。

patch_twin_reported_properties

使用 Azure IoT 中心 或 Azure IoT Edge 中心服务更新报告的属性。

这是一个同步调用,这意味着此函数在修补程序已发送到服务并得到确认之前不会返回。

如果服务在修补操作上返回错误,此函数将引发相应的错误。

patch_twin_reported_properties(reported_properties_patch)

参数

reported_properties_patch
dict
必需

作为 JSON dict 的孪生报告属性修补程序

例外

如果凭据无效且无法建立连接,则为 。

如果建立连接导致失败,则为 。

如果在执行期间丢失连接,则为 。

如果连接尝试超时

如果客户端未 (连接,并且没有启用自动连接)

如果在执行期间发生意外失败,则为 。

receive_message_on_input

接收已从另一个模块发送到特定输入的输入消息。

自版本 2.3.0 以来已弃用:建议改用 .on_message_received 属性来设置处理程序

receive_message_on_input(input_name, block=True, timeout=None)

参数

input_name
str
必需

要接收消息的输入名称。

block
bool
必需

指示在收到消息之前是否应阻止操作。

timeout
int
必需

(可选)提供阻止超时前的秒数。

返回

发送到指定输入的消息;如果在阻塞期结束时未收到任何方法请求,则为 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)

参数

method_name
str
默认值: None

(可选)提供要接收其请求的方法的名称。 如果未提供此参数,则将接收其他receive_method请求尚未专门面向的所有方法。

block
bool
默认值: True

指示在收到请求之前是否应阻止操作。

timeout
int
默认值: None

(可选)提供阻止超时前的秒数。

返回

表示接收的方法请求的 MethodRequest 对象;如果在阻塞期结束时尚未收到任何方法请求,则为 None。

例外

如果凭据无效且无法建立连接,则为 。

如果建立连接导致失败,则为 。

如果在执行期间丢失连接,则为 。

如果连接超时,则为 。

如果在执行期间发生意外失败,则为 。

receive_twin_desired_properties_patch

通过 Azure IoT 中心 或 Azure IoT Edge 中心接收所需的属性修补程序。

这是一个同步调用,这意味着以下内容:

  1. 如果 block=True,则此函数将阻止,直到发生以下情况之一:

    • 从 Azure IoT 中心 或 Azure IoT Edge 中心接收所需的属性修补程序。

    • 超时期限(如果已提供)已过。 如果发生超时,此函数将引发 InboxEmpty 异常

  2. 如果 block=False,则此函数将返回管道可能已接收但尚未返回到应用程序的任何所需属性修补程序。 如果管道未收到所需的属性修补程序,此函数将引发 InboxEmpty 异常

自版本 2.3.0 以来已弃用:建议改用 .on_twin_desired_properties_patch_received 属性来设置处理程序

receive_twin_desired_properties_patch(block=True, timeout=None)

参数

block
bool
默认值: True

指示在收到请求之前是否应阻止操作。

timeout
int
默认值: None

(可选)提供阻止超时前的秒数。

返回

孪生所需属性修补程序作为 JSON dict;如果在阻塞期结束时未收到任何修补程序,则为 None

返回类型

dict,

例外

如果凭据无效且无法建立连接,则为 。

如果建立连接导致失败,则为 。

如果在执行期间丢失连接,则为 。

如果连接超时,则为 。

如果在执行期间发生意外失败,则为 。

send_message

将消息发送到Azure IoT 中心或 Azure IoT Edge中心实例上的默认事件终结点。

这是一个同步事件,这意味着此函数在事件已发送到服务且服务确认收到事件之前不会返回。

如果之前未通过调用连接打开与服务的连接,此函数将在发送事件之前打开连接。

send_message(message)

参数

message
Messagestr
必需

要发送的实际消息。 传递的不是 Message 类实例的任何内容都将转换为 Message 对象。

例外

如果凭据无效且无法建立连接,则为 。

如果建立连接导致失败,则为 。

如果在执行期间丢失连接,则为 。

如果连接尝试超时

如果客户端未 (连接,并且没有启用自动连接)

如果在执行期间发生意外失败,则为 。

ValueError if the message fails size validation.

send_message_to_output

将事件/消息发送到给定的模块输出。

这些是传出事件,是“输出事件”。

这是一个同步事件,这意味着此函数在事件已发送到服务且服务确认收到事件之前不会返回。

如果之前未通过调用连接打开与服务的连接,此函数将在发送事件之前打开连接。

send_message_to_output(message, output_name)

参数

message
Messagestr
必需

要发送到给定输出的消息。 传递的不是 Message 类实例的任何内容都将转换为 Message 对象。

output_name
str
必需

要向其发送事件的输出的名称。

例外

如果凭据无效且无法建立连接,则为 。

如果建立连接导致失败,则为 。

如果在执行期间丢失连接,则为 。

如果连接尝试超时

如果客户端未 (连接,并且没有启用自动连接)

如果在执行期间发生意外失败,则为 。

ValueError if the message fails size validation.

send_method_response

通过 Azure IoT 中心 或 Azure IoT Edge 中心向方法请求发送响应。

这是一个同步事件,这意味着此函数在事件已发送到服务且服务确认收到事件之前不会返回。

如果之前未通过调用连接打开与服务的连接,此函数将在发送事件之前打开连接。

send_method_response(method_response)

参数

method_response
MethodResponse
必需

要发送的 MethodResponse。

例外

如果凭据无效且无法建立连接,则为 。

如果建立连接导致失败,则为 。

如果在执行期间丢失连接,则为 。

如果连接尝试超时

如果客户端未 (连接,并且没有启用自动连接)

如果在执行期间发生意外失败,则为 。

shutdown

关闭客户端以正常退出。

调用此方法后,任何尝试进一步的客户端调用都将导致引发 ClientError

shutdown()

例外

如果在执行期间发生意外失败,则为 。

update_sastoken

更新用于身份验证的客户端 SAS 令牌,然后重新授权连接。

仅当客户端最初是使用 SAS 令牌创建的时,才能使用此 API。

update_sastoken(sastoken)

参数

sastoken
str
必需

供客户端使用的新 SAS 令牌字符串

例外

ValueError if the sastoken parameter is invalid

如果凭据无效且无法重新建立连接,则为 。

如果重新建立连接导致失败,则为 。

如果在执行期间丢失连接,则为 。

如果重新授权尝试超时,则为 。

如果客户端最初不是使用 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 字典对象形式的孪生体补丁 (一个位置参数)