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 Hub 實例。 系統會根據透過初始化此物件時提供的 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 Hub 服務更新報告的屬性。 這是同步呼叫，這表示在修補程式傳送至服務並認可之前，此函式不會傳回。 如果服務在修補作業上傳回錯誤，此函式會引發適當的錯誤。 |
| receive_message_on_input |
接收已從另一個模組傳送至特定輸入的輸入訊息。 自 2.3.0 版以來已被取代：建議您改用 .on_message_received 屬性來設定處理常式 |
| receive_method_request |
透過 Azure IoT 中樞 或 Azure IoT Edge Hub 接收方法要求。 自 2.3.0 版以來已被取代：建議您改用 .on_method_request_received 屬性來設定處理常式 |
| receive_twin_desired_properties_patch |
透過 Azure IoT 中樞 或 Azure IoT Edge Hub 接收所需的屬性修補程式。 這是同步呼叫，這表示下列各項：
自 2.3.0 版起已被取代：建議您改用 .on_twin_desired_properties_patch_received 屬性來設定處理常式 |
| send_message |
將訊息傳送至Azure IoT 中樞或 Azure IoT Edge Hub 實例上的預設事件端點。 這是同步事件，這表示此函式不會傳回，直到事件傳送至服務，且服務已認可收到事件為止。 如果先前尚未由呼叫連線開啟服務的連線，此函式會在傳送事件之前開啟連線。 |
| send_message_to_output |
將事件/訊息傳送至指定的模組輸出。 這些是傳出事件，其目的為「輸出事件」。 這是同步事件，這表示此函式不會傳回，直到事件傳送至服務，且服務已認可收到事件為止。 如果先前尚未由呼叫連線開啟服務的連線，此函式會在傳送事件之前開啟連線。 |
| send_method_response |
透過 Azure IoT 中樞 或 Azure IoT Edge Hub 將回應傳送至方法要求。 這是同步事件，這表示此函式不會傳回，直到事件傳送至服務，且服務已認可收到事件為止。 如果先前尚未由呼叫連線開啟服務的連線，此函式會在傳送事件之前開啟連線。 |
| shutdown |
關閉用戶端以正常結束。 呼叫此方法之後，任何進一步用戶端呼叫的嘗試都會引發 ClientError |
| update_sastoken |
更新用於驗證的用戶端 SAS 權杖，然後重新授權連線。 只有在用戶端最初使用 SAS 權杖建立時，才能使用此 API。 |
connect
將用戶端連線至 Azure IoT 中樞 或 Azure IoT Edge Hub 實例。
系統會根據透過初始化此物件時提供的 auth_provider 參數傳遞的認證來選擇目的地。
這是同步呼叫，這表示在完全建立服務連線之前，此函式不會傳回。
connect()例外狀況
如果認證無效且無法建立連線，則為 。
如果建立連接導致失敗，則為 。
如果在執行期間遺失連線，則為 。
如果連線逾時，則為 。
如果在執行期間發生非預期的失敗，則為 。
create_from_connection_string
從 IoTHub 裝置或模組連接字串具現化用戶端。
create_from_connection_string(connection_string, **kwargs)參數
- keep_alive
- int
與訊息代理程式通訊之間以秒為單位的最大期間。 如果沒有交換其他訊息，這會控制用戶端將傳送 Ping 訊息給訊息代理程式的速度。 如果未提供預設值 60 秒，則會使用 。
傳回
使用連接字串進行驗證的 IoTHub 用戶端實例。
例外狀況
create_from_edge_environment
從IoT Edge環境具現化用戶端。
這個方法只能從IoT Edge容器內部執行，或在針對 Edge (開發設定的偵錯環境中執行，例如 Visual Studio、Visual Studio Code)
create_from_edge_environment(**kwargs)參數
- keep_alive
- int
與訊息代理程式通訊之間以秒為單位的最大期間。 如果沒有交換其他訊息，這會控制用戶端將傳送 Ping 訊息給訊息代理程式的速度。 如果未提供預設值 60 秒，則會使用 。
傳回
IoTHub 用戶端的實例，使用IoT Edge環境進行驗證。
例外狀況
create_from_sastoken
從預先建立的 SAS 權杖字串具現化用戶端
create_from_sastoken(sastoken, **kwargs)參數
- keep_alive
- int
與訊息代理程式通訊之間的最大期間，以秒為單位。 如果沒有交換其他訊息，這會控制用戶端將傳送 Ping 訊息給訊息代理程式的速度。 如果未提供預設值 60 秒，則會使用 。
例外狀況
create_from_x509_certificate
使用 X509 憑證驗證具現化用戶端。
create_from_x509_certificate(x509, hostname, device_id, module_id, **kwargs)參數
- keep_alive
- int
與訊息代理程式通訊之間的最大期間，以秒為單位。 如果沒有交換其他訊息，這會控制用戶端將傳送 Ping 訊息給訊息代理程式的速度。 如果未提供預設值 60 秒，則會使用 。
傳回
使用 X509 憑證進行驗證的 IoTHub 用戶端實例。
例外狀況
disconnect
中斷用戶端與 Azure IoT 中樞 或 Azure IoT Edge 中樞實例的連線。
當您完全使用用戶端實例完成時，建議您務必呼叫此函式。
這是同步呼叫，這表示在完全關閉服務連線之前，此函式不會傳回。
disconnect()例外狀況
如果在執行期間發生非預期的失敗，則為 。
get_twin
從 Azure IoT 中樞 或 Azure IoT Edge 中樞服務取得裝置或模組對應項。
這是同步呼叫，這表示在從服務擷取對應項之前，此函式不會傳回。
get_twin()傳回
以 JSON 聽寫形式完成對應項
傳回類型
例外狀況
如果認證無效且無法建立連線，則為 。
如果建立連接導致失敗，則為 。
如果在執行期間遺失連接，則為 。
如果連線嘗試逾時
如果用戶端未連線 (且未啟用自動連線)
如果在執行期間發生非預期的失敗，則為 。
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 Hub 服務更新報告的屬性。
這是同步呼叫，這表示在修補程式傳送至服務並認可之前，此函式不會傳回。
如果服務在修補作業上傳回錯誤，此函式會引發適當的錯誤。
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 Hub 接收方法要求。
自 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 Hub 接收所需的屬性修補程式。
這是同步呼叫，這表示下列各項：
如果 block=True，則此函式會封鎖，直到發生下列其中一項為止：
從 Azure IoT 中樞 或 Azure IoT Edge Hub 收到所需的屬性修補程式。
如果已提供，則逾時期間會經過。 如果發生逾時，此函式將會引發收件匣Empty 例外狀況
如果 block=False，此函式會傳回管線可能已收到但尚未傳回給應用程式的任何所需屬性修補程式。 如果管線未收到任何所需的屬性修補程式，此函式將會引發 InboxEmpty 例外狀況
自 2.3.0 版起已被取代：建議您改用 .on_twin_desired_properties_patch_received 屬性來設定處理常式
receive_twin_desired_properties_patch(block=True, timeout=None)參數
傳回
對應項 Desired Properties 修補為 JSON 聽寫，如果封鎖期間結束時未收到任何修補程式，則為 None
傳回類型
例外狀況
如果認證無效且無法建立連線，則為 。
如果建立連接導致失敗，則為 。
如果在執行期間遺失連線，則為 。
如果連線逾時，則為 。
如果在執行期間發生非預期的失敗，則為 。
send_message
將訊息傳送至Azure IoT 中樞或 Azure IoT Edge Hub 實例上的預設事件端點。
這是同步事件，這表示此函式不會傳回，直到事件傳送至服務，且服務已認可收到事件為止。
如果先前尚未由呼叫連線開啟服務的連線，此函式會在傳送事件之前開啟連線。
send_message(message)參數
例外狀況
如果認證無效且無法建立連線，則為 。
如果建立連接導致失敗，則為 。
如果在執行期間遺失連線，則為 。
如果連線嘗試逾時
如果用戶端未連線 (，且未啟用自動連線)
如果在執行期間發生非預期的失敗，則為 。
send_message_to_output
將事件/訊息傳送至指定的模組輸出。
這些是傳出事件，其目的為「輸出事件」。
這是同步事件，這表示此函式不會傳回，直到事件傳送至服務，且服務已認可收到事件為止。
如果先前尚未由呼叫連線開啟服務的連線，此函式會在傳送事件之前開啟連線。
send_message_to_output(message, output_name)參數
例外狀況
如果認證無效且無法建立連線，則為 。
如果建立連接導致失敗，則為 。
如果在執行期間遺失連線，則為 。
如果連線嘗試逾時
如果用戶端未連線 (，且未啟用自動連線)
如果在執行期間發生非預期的失敗，則為 。
send_method_response
透過 Azure IoT 中樞 或 Azure IoT Edge Hub 將回應傳送至方法要求。
這是同步事件，這表示此函式不會傳回，直到事件傳送至服務，且服務已認可收到事件為止。
如果先前尚未由呼叫連線開啟服務的連線，此函式會在傳送事件之前開啟連線。
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。
提交並檢視相關的意見反應