你当前正在访问 Microsoft Azure Global Edition 技术文档网站。 如果需要访问由世纪互联运营的 Microsoft Azure 中国技术文档网站，请访问 https://docs.azure.cn。
IoTHubDeviceClient 类
连接到Azure IoT 中心实例的同步设备客户端。
IoTHubDeviceClient 的初始值设定项。
不应直接调用此初始值设定项。 请改用“create_from_<<”>>类方法之一进行实例化
- 继承
-
azure.iot.device.iothub.sync_clients.GenericIoTHubClientIoTHubDeviceClientazure.iot.device.iothub.abstract_clients.AbstractIoTHubDeviceClientIoTHubDeviceClient
构造函数
IoTHubDeviceClient(mqtt_pipeline, http_pipeline)参数
- mqtt_pipeline
- <xref:azure.iot.device.iothub.pipeline.MQTTPipeline>
用于连接到 IoTHub 终结点的管道。
- http_pipeline
方法
| connect |
将客户端连接到 Azure IoT 中心 或 Azure IoT Edge 中心实例。 根据通过初始化此对象时提供的 auth_provider 参数传递的凭据选择目标。 这是一个同步调用，这意味着此函数在与服务的连接完全建立之前不会返回。 |
| create_from_connection_string |
从 IoTHub 设备或模块连接字符串实例化客户端。 |
| create_from_sastoken |
从预先创建的 SAS 令牌字符串实例化客户端 |
| create_from_symmetric_key |
使用对称密钥身份验证实例化客户端。 |
| create_from_x509_certificate |
使用 X509 证书身份验证实例化客户端。 |
| disconnect |
断开客户端与 Azure IoT 中心 或 Azure IoT Edge 中心实例的连接。 建议确保在完全完成客户端实例后调用此函数。 这是一个同步调用，这意味着此函数在与服务的连接完全关闭之前不会返回。 |
| get_storage_info_for_blob |
通过 HTTP 将 POST 请求发送到 IoTHub 终结点，该终结点将通过链接到设备连接到的 IoTHub 的 Azure 存储帐户返回上传信息。 |
| get_twin |
从 Azure IoT 中心 或 Azure IoT Edge 中心服务获取设备或模块孪生。 这是一个同步调用，这意味着此函数在从服务中检索孪生体之前不会返回。 |
| notify_blob_upload_status |
上传完成后，设备会向IoT 中心终结点发送 POST 请求，其中包含有关上传到 blob 尝试的状态的信息。 IoT 中心使用此来通知侦听客户端。 |
| patch_twin_reported_properties |
使用 Azure IoT 中心 或 Azure IoT Edge 中心服务更新报告的属性。 这是一个同步调用，这意味着此函数在修补程序已发送到服务并得到确认之前不会返回。 如果服务在修补操作上返回错误，则此函数将引发相应的错误。 |
| receive_message |
接收已从Azure IoT 中心发送的消息。 自版本 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_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_sastoken
从预先创建的 SAS 令牌字符串实例化客户端
create_from_sastoken(sastoken, **kwargs)参数
例外
create_from_symmetric_key
使用对称密钥身份验证实例化客户端。
create_from_symmetric_key(symmetric_key, hostname, device_id, **kwargs)参数
- symmetric_key
对称密钥。
- device_id
设备 ID
返回
使用对称密钥进行身份验证的 IoTHub 客户端的实例。
例外
create_from_x509_certificate
使用 X509 证书身份验证实例化客户端。
create_from_x509_certificate(x509, hostname, device_id, **kwargs)参数
返回
使用 X509 证书进行身份验证的 IoTHub 客户端的实例。
例外
disconnect
断开客户端与 Azure IoT 中心 或 Azure IoT Edge 中心实例的连接。
建议确保在完全完成客户端实例后调用此函数。
这是一个同步调用，这意味着此函数在与服务的连接完全关闭之前不会返回。
disconnect()例外
如果在执行期间出现意外故障，则为 。
get_storage_info_for_blob
通过 HTTP 将 POST 请求发送到 IoTHub 终结点，该终结点将通过链接到设备连接到的 IoTHub 的 Azure 存储帐户返回上传信息。
get_storage_info_for_blob(blob_name)参数
- blob_name
- str
将使用存储 API 上传的 Blob 的字符串格式的名称。 此名称将用于为存储生成正确的凭据，并且需要与用于 Azure 存储 SDK 以执行 Blob 上传的内容匹配。
返回
类似于 JSON 的 (字典) 来自IoT 中心的对象，该对象将包含相关信息，包括：correlationId、hostName、containerName、blobName、sasToken。
例外
如果凭据无效且无法建立连接，则为 。
如果建立连接导致失败，则为 。
如果在执行期间丢失连接，则为 。
如果连接超时，则为 。
如果在执行期间发生意外失败，则为 。
get_twin
从 Azure IoT 中心 或 Azure IoT Edge 中心服务获取设备或模块孪生。
这是一个同步调用，这意味着此函数在从服务中检索孪生体之前不会返回。
get_twin()返回
以 JSON 听写的形式完成孪生
返回类型
例外
如果凭据无效且无法建立连接，则为 。
如果建立连接导致失败，则为 。
如果连接在执行期间丢失，则为 。
如果连接尝试超时
如果客户端未 (连接，并且没有启用自动连接)
如果在执行期间出现意外故障，则为 。
notify_blob_upload_status
上传完成后，设备会向IoT 中心终结点发送 POST 请求，其中包含有关上传到 blob 尝试的状态的信息。 IoT 中心使用此来通知侦听客户端。
notify_blob_upload_status(correlation_id, is_success, status_code, status_description)参数
例外
如果凭据无效且无法建立连接，则为 。
如果建立连接导致失败，则为 。
如果在执行期间丢失连接，则为 。
如果连接超时，则为 。
如果在执行期间发生意外失败，则为 。
patch_twin_reported_properties
使用 Azure IoT 中心 或 Azure IoT Edge 中心服务更新报告的属性。
这是一个同步调用，这意味着此函数在修补程序已发送到服务并得到确认之前不会返回。
如果服务在修补操作上返回错误，则此函数将引发相应的错误。
patch_twin_reported_properties(reported_properties_patch)参数
例外
如果凭据无效且无法建立连接，则为 。
如果建立连接导致失败，则为 。
如果连接在执行期间丢失，则为 。
如果连接尝试超时
如果客户端未 (连接，并且没有启用自动连接)
如果在执行期间出现意外故障，则为 。
receive_message
接收已从Azure IoT 中心发送的消息。
自版本 2.3.0 以来已弃用：建议改用 .on_message_received 属性来设置处理程序
receive_message(block=True, timeout=None)参数
返回
从Azure IoT 中心发送的消息;如果阻止期结束时未收到任何方法请求，则为 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 听录;如果阻塞期结束时未收到任何修补程序，则为 None
返回类型
例外
如果凭据无效且无法建立连接，则为 。
如果建立连接导致失败，则为 。
如果在执行期间丢失连接，则为 。
如果连接超时，则为 。
如果在执行期间发生意外失败，则为 。
send_message
将消息发送到 Azure IoT 中心 或 Azure IoT Edge 中心实例上的默认事件终结点。
这是一个同步事件，这意味着此函数在事件已发送到服务且服务确认收到事件之前不会返回。
如果之前尚未通过调用连接来打开与服务的连接，则此函数将在发送事件之前打开连接。
send_message(message)参数
例外
如果凭据无效且无法建立连接，则为 。
如果建立连接导致失败，则为 。
如果连接在执行期间丢失，则为 。
如果连接尝试超时
如果客户端未 (连接，并且没有启用自动连接)
如果在执行期间出现意外故障，则为 。
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 字典对象形式的孪生体补丁 (一个位置参数)
反馈
即将发布：在整个 2024 年，我们将逐步淘汰作为内容反馈机制的“GitHub 问题”，并将其取代为新的反馈系统。 有关详细信息，请参阅：https://aka.ms/ContentUserFeedback。
提交和查看相关反馈