開始使用裝置對應項 (Python)

發行項
06/27/2024

裝置對應項是存放裝置狀態資訊的 JSON 文件，包括中繼資料、設定和條件。 IoT 中樞會為其連線的每個裝置保存裝置對應項。

注意

本文中所述的功能僅適用於 IoT 中樞的標準層。如需基本和標準/免費 IoT 中樞層的詳細資訊，請參閱選擇適合您解決方案的 IoT 中樞層。

使用裝置對應項以：

從您的解決方案後端儲存裝置中繼資料。
從裝置應用程式報告目前狀態資訊，例如可用功能和狀況 (例如，使用的連線方法)。
同步處理裝置應用程式與後端應用程式之間，長時間執行的工作流程狀態 (例如韌體和設定更新)。
查詢您的裝置中繼資料、設定或狀態。

裝置對應項是設計來進行同步處理和查詢裝置組態和條件。如需裝置對應項的詳細資訊，包括何時使用裝置對應項，請參閱了解裝置對應項。

IoT 中樞會儲存裝置對應項，其包含下列元素：

標籤。只有解決方案後端可存取裝置中繼資料。
預期屬性。 JSON 物件可由解決方案後端修改，並依裝置應用程式查看。
回報的屬性。 JSON 物件可由裝置應用程式修改，並由解決方案後端讀取。

標籤和屬性不能包含陣列，但可以包含巢狀物件。

下圖顯示裝置對應項的組織：

裝置對應項概念圖的螢幕擷取畫面。

此外，解決方案後端可以根據上述的所有資料查詢裝置對應項。如需裝置對應項的詳細資訊，請參閱了解裝置對應項。如需查詢的詳細資訊，請參閱 IoT 中樞查詢語言。

本文章說明如何：

使用模擬裝置應用程式，將其連線通道報告為裝置對應項上的回報屬性。
使用先前建立的標籤和屬性上的篩選器，從您的後端應用程式查詢裝置。

在本文中，您會建立兩個 Python 主控台應用程式：

AddTagsAndQuery.py：後端應用程式，可新增標籤和查詢裝置對應項。
ReportConnectivity.py：模擬裝置應用程式，可連線到 IoT 中樞，並報告其連線狀況。

注意

如需可用來建置裝置和後端應用程式的 SDK 工具詳細資訊，請參閱 Azure IoT SDK (部分機器翻譯)。

必要條件

使用中的 Azure 帳戶。 (如果您沒有帳戶，只需要幾分鐘的時間就可以建立免費帳戶。)
IoT 中樞。使用 CLI 或 Azure 入口網站建立一個。
在 IoT 中樞內註冊的裝置。如果 IoT 中樞中沒有裝置，請遵循註冊裝置中的步驟。
建議使用 Python 3.7 版或更新版本。請務必使用安裝程式所需的 32 位元或 64 位元安裝。在安裝期間出現系統提示時，務必將 Python 新增至平台特有的環境變數。
請確定您的防火牆已開啟連接埠 8883。本文中的裝置範例會使用 MQTT 通訊協定，其會透過連接埠 8883 進行通訊。某些公司和教育網路環境可能會封鎖此連接埠。如需此問題的詳細資訊和解決方法，請參閱連線至 IoT 中樞 (MQTT)。

取得 IoT 中樞連接字串

在本文中，您會建立後端服務，其會將所需的屬性新增至裝置對應項，然後查詢身分識別登錄，以尋找具有所報告屬性且已分別更新的所有裝置。服務需要有服務連線權限，才能修改裝置對應項的所需屬性，也需要有登錄讀取權限才能查詢身分識別登錄。沒有任何預設的共用存取原則只包含這兩項權限，所以必須自己建立一個。

若要建立共用存取原則，其會授與服務連線和登錄讀取權限，並取得此原則的連接字串，請遵循下列步驟：

在 Azure 入口網站中，選取 [資源群組]。選取中樞所在的資源群組，然後從資源清單選取中樞。
在中樞的左側窗格上，選取 [共用存取原則]。
從原則清單上方的頂端功能表中，選取 [新增共用存取原則]。
在右側的 [新增共用存取原則] 窗格中，輸入原則的描述性名稱，例如 serviceAndRegistryRead。在 [權限] 底下選取 [登錄讀取] 和 [服務連線]，然後選取 [新增]。
從原則清單中選取新原則。
選取 [主要連接字串] 的複製圖示，然後儲存值。

如需 IoT 中樞共用存取原則和權限的詳細資訊，請參閱存取控制及權限。

建立服務應用程式來更新所需的屬性和查詢對應項

在本節中，您將建立一個 Python 主控台應用程式，而此應用程式會將位置中繼資料新增至與您「{裝置識別碼}」相關聯的裝置對應項。應用程式會先查詢 IoT 中樞是否有位於美國的裝置，再查詢是否有回報行動電話通訊網路連線的裝置。

在您的工作目錄中，開啟命令提示字元並安裝適用於 Python 的 Azure IoT 中樞裝置 SDK。
```
pip install azure-iot-hub
```
使用文字編輯器，建立新的 AddTagsAndQuery.py 檔案。

新增下列程式碼，從服務 SDK 匯入必要的模組：

import sys
from time import sleep
from azure.iot.hub import IoTHubRegistryManager
from azure.iot.hub.models import Twin, TwinProperties, QuerySpecification, QueryResult

加入下列程式碼。將 [IoTHub Connection String] 取代為在取得 IoT 中樞連接字串中複製的 IoT 中樞連接字串。將 [Device Id] 取代為您已註冊的裝置在 IoT 中樞內的裝置識別碼 (名稱)。
```
IOTHUB_CONNECTION_STRING = "[IoTHub Connection String]"
DEVICE_ID = "[Device Id]"
```

將下列程式碼新增至 AddTagsAndQuery.py 檔案：

def iothub_service_sample_run():
    try:
        iothub_registry_manager = IoTHubRegistryManager(IOTHUB_CONNECTION_STRING)

        new_tags = {
                'location' : {
                    'region' : 'US',
                    'plant' : 'Redmond43'
                }
            }

        twin = iothub_registry_manager.get_twin(DEVICE_ID)
        twin_patch = Twin(tags=new_tags, properties= TwinProperties(desired={'power_level' : 1}))
        twin = iothub_registry_manager.update_twin(DEVICE_ID, twin_patch, twin.etag)

        # Add a delay to account for any latency before executing the query
        sleep(1)

        query_spec = QuerySpecification(query="SELECT * FROM devices WHERE tags.location.plant = 'Redmond43'")
        query_result = iothub_registry_manager.query_iot_hub(query_spec, None, 100)
        print("Devices in Redmond43 plant: {}".format(', '.join([twin.device_id for twin in query_result.items])))

        print()

        query_spec = QuerySpecification(query="SELECT * FROM devices WHERE tags.location.plant = 'Redmond43' AND properties.reported.connectivity = 'cellular'")
        query_result = iothub_registry_manager.query_iot_hub(query_spec, None, 100)
        print("Devices in Redmond43 plant using cellular network: {}".format(', '.join([twin.device_id for twin in query_result.items])))

    except Exception as ex:
        print("Unexpected error {0}".format(ex))
        return
    except KeyboardInterrupt:
        print("IoT Hub Device Twin service sample stopped")

IoTHubRegistryManager 物件會公開從服務以與裝置對應項進行互動時所需的所有方法。程式碼會先初始化 IoTHubRegistryManager 物件，然後針對 DEVICE_ID 更新裝置對應項，最後執行兩個查詢。第一個只選取位於 Redmond43 工廠之裝置的裝置對應項，第二個會重新調整查詢，只選取也透過行動電話網路連線的裝置。

在 AddTagsAndQuery.py 結尾處新增下列程式碼來實作 iothub_service_sample_run 函數：

if __name__ == '__main__':
    print("Starting the Python IoT Hub Device Twin service sample...")
    print()

    iothub_service_sample_run()

使用下列命令執行應用程式：
```
python AddTagsAndQuery.py
```
如果是查詢所有位於 Redmond43 中的裝置，您在結果中會看到一個裝置，而如果查詢將結果限於使用行動電話網路的裝置，則您不會看到任何裝置。在下一節中，您會建立將使用行動數據網路的裝置應用程式，然後重新執行此查詢以查看其如何變更。

建立裝置應用程式來更新報告屬性

在本節中，您將建立一個 Python 主控台應用程式，此應用程式會以您的 {裝置識別碼} 連線至您的中樞，然後更新其裝置對應項所報告的屬性，以確認其目前使用行動電話網路來連線。

從工作目錄中的命令提示字元中，安裝適用於 Python 的 Azure IoT 中樞裝置 SDK：
```
pip install azure-iot-device
```
使用文字編輯器，建立新的 ReportConnectivity.py 檔案。
新增下列程式碼，從裝置 SDK 匯入必要的模組：
```
import time
from azure.iot.device import IoTHubModuleClient
```
加入下列程式碼。將 [IoTHub Device Connection String] 預留位置值取代為您在 IoT 中樞註冊新裝置時看到的裝置連接字串：
```
CONNECTION_STRING = "[IoTHub Device Connection String]"
```

將下列程式碼新增至 ReportConnectivity.py 檔案，來具現化用戶端以及實作裝置對應項功能：

def create_client():
    # Instantiate client
    client = IoTHubModuleClient.create_from_connection_string(CONNECTION_STRING)

    # Define behavior for receiving twin desired property patches
    def twin_patch_handler(twin_patch):
        print("Twin patch received:")
        print(twin_patch)

    try:
        # Set handlers on the client
        client.on_twin_desired_properties_patch_received = twin_patch_handler
    except:
        # Clean up in the event of failure
        client.shutdown()

    return client

在 ReportConnectivity.py 結尾處新增下列程式碼來執行應用程式：

def main():
    print ( "Starting the Python IoT Hub Device Twin device sample..." )
    client = create_client()
    print ( "IoTHubModuleClient waiting for commands, press Ctrl-C to exit" )

    try:
        # Update reported properties with cellular information
        print ( "Sending data as reported property..." )
        reported_patch = {"connectivity": "cellular"}
        client.patch_twin_reported_properties(reported_patch)
        print ( "Reported properties updated" )

        # Wait for program exit
        while True:
            time.sleep(1000000)
    except KeyboardInterrupt:
        print ("IoT Hub Device Twin device sample stopped")
    finally:
        # Graceful exit
        print("Shutting down IoT Hub Client")
        client.shutdown()

if __name__ == '__main__':
    main()

執行裝置應用程式︰
```
python ReportConnectivity.py
```
您應該會看到已更新裝置對應項所報告屬性的確認。
現在，裝置已回報其連線資訊，它應該會出現在這兩個查詢中。請返回並再次執行查詢：
```
python AddTagsAndQuery.py
```
這次，您的「{裝置識別碼}」應該會出現在這兩個查詢結果中。

在您的裝置應用程式中，您將會看到已接收到服務應用程式所傳送所需屬性對應項修補程式的確認。

在本文章中，您將：

從後端應用程式將裝置中繼資料新增為標籤
回報裝置對應項中的裝置連線資訊
使用 IoT 中樞查詢語言來查詢裝置對應項資訊

下一步

若要了解如何：

從裝置傳送遙測，請參閱快速入門：將遙測資料從 IoT 隨插即用裝置傳送至 IoT 中樞一文。
使用裝置對應項所需的屬性設定裝置，請參閱教學課程：從後端服務設定您的裝置。
以互動方式控制裝置，例如從使用者控制的應用程式開啟風扇，請參閱快速入門：控制連線到 IoT 中樞的裝置。

共用方式為