開始使用裝置對應項目 （Python）

• CLI
• .NET
• Python
• Node.js
• Java

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

注意

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

使用裝置對應項以：

• 從解決方案後端儲存裝置元數據。

• 從您的裝置應用程式報告目前的狀態資訊，例如可用的功能和條件，例如所使用的連線方法。

• 同步處理裝置應用程式與後端應用程式之間長時間執行的工作流程狀態，例如韌體和組態更新。

• 查詢您的裝置中繼資料、設定或狀態。

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

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

• 標籤。 裝置元數據只能由解決方案後端存取。

• 預期屬性。 解決方案後端可修改的 JSON 物件，並可由裝置應用程式觀察。

• 回報的屬性。 裝置應用程式可修改的 JSON 物件，並可由解決方案後端讀取。

標記和屬性不能包含數位，但可以包含巢狀物件。

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

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

本文章說明如何：

• 使用模擬裝置應用程式，將其連線通道報告為裝置對應項上的報告屬性。

• 使用先前建立之標籤和屬性的篩選，從後端應用程式查詢裝置。

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

• AddTagsAndQuery.py：可新增標籤和查詢裝置對應項的後端應用程式。

• 報告 連線 ivity.py：連線到IoT中樞的模擬裝置應用程式，並報告其連線狀況。

注意

如需可用來建置裝置和後端應用程式之 SDK 工具的詳細資訊，請參閱 Azure IoT SDK。

必要條件

• 使用中的 Azure 帳戶。 (如果您沒有帳戶，只需要幾分鐘的時間就可以建立免費帳戶。)

• 一個 IoT 中樞。 使用 CLI 或 Azure 入口網站建立一個。

• 已註冊的裝置。 在 Azure 入口網站中註冊一個。

• 建議使用 Python 3.7 版或更新版本。 請務必使用安裝程式所需的 32 位元或 64 位元安裝。 在安裝期間出現系統提示時，務必將 Python 新增至平台特有的環境變數。

• 請確定您的防火牆中已開啟埠 8883。 本文中的裝置範例會使用 MQTT 通訊協定，其會透過連接埠 8883 進行通訊。 某些公司和教育網路環境可能會封鎖此連接埠。 如需此問題的詳細資訊和解決方法，請參閱連線至 IoT 中樞 (MQTT)。

取得 IoT 中樞連接字串

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

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

1. 在 Azure 入口網站中，選取 [資源群組]。 選取中樞所在的資源群組，然後從資源清單選取中樞。

2. 在中樞的左側窗格中，選取 [共用存取原則]。

3. 從原則清單上方的頂端功能表中，選取 [ 新增共用原則存取原則]。

4. 在右側的 [ 新增共用存取原則 ] 窗格中，輸入原則的描述性名稱，例如 serviceAndRegistryRead。 在 [許可權] 底下，選取 [登錄讀取和服務 連線]，然後選取 [新增]。

   

5. 從原則清單中選取您的新原則。

6. 選取主要 連接字串 的複製圖示，然後儲存值。

   

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

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

在本節中，您會建立 Python 控制台應用程式，將位置元數據新增至與 {Device ID} 相關聯的裝置對應項。 應用程式會針對位於美國的裝置查詢IoT中樞，然後查詢報告行動數據網路連線的裝置。

1. 在您的工作目錄中，開啟命令提示字元，並安裝適用於 Python 的 Azure IoT 中樞 Service SDK。

   pip install azure-iot-hub
   

2. 使用文字編輯器，建立新的 AddTagsAndQuery.py 檔案。

3. 新增下列程式代碼以從服務 SDK 匯入所需的模組：

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

4. 加入下列程式碼。 將 取代[IoTHub Connection String]為您在取得IoT中樞 連接字串 中複製的IoT中樞 連接字串。 將取代 [Device Id] 為IoT中樞中已註冊裝置的裝置識別碼（名稱）。

   IOTHUB_CONNECTION_STRING = "[IoTHub Connection String]"
   DEVICE_ID = "[Device Id]"
   

5. 將下列程式代碼新增至 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 工廠的裝置對應項，第二個會精簡查詢，只選取也透過行動數據網路連線的裝置。

6. 在 AddTagsAndQuery.py 結尾新增下列程式代碼，以實作iothub_service_sample_run函式：

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

7. 使用下列項目執行應用程式：

   python AddTagsAndQuery.py
   

   您應該會在查詢結果中看到一個裝置，要求所有位於 Redmond43 的裝置，且查詢中沒有一個裝置，該查詢會將結果限製為使用行動數據網路的裝置。 在下一節中，您將建立將使用行動數據網路的裝置應用程式，然後重新執行此查詢以查看其變更方式。

   

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

在本節中，您會建立 Python 控制台應用程式，以連線到您的中樞作為 {裝置標識符} ，然後更新其裝置對應項的報告屬性，以確認其已使用行動數據網路連線。

1. 從工作目錄中的命令提示字元，安裝適用於 Python 的 Azure IoT 中樞 Device SDK：

   pip install azure-iot-device
   

2. 使用文本編輯器，建立新的報表 連線 ivity.py 檔案。

3. 新增下列程式代碼以從裝置 SDK 匯入所需的模組：

   import time
   from azure.iot.device import IoTHubModuleClient
   

4. 加入下列程式碼。 將[IoTHub Device Connection String]佔位元值取代為您在 IoT 中樞 中註冊裝置時看到的裝置 連接字串：

   CONNECTION_STRING = "[IoTHub Device Connection String]"
   

5. 將下列程式代碼新增至 Report 連線 ivity.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
   

6. 在 Report 結尾新增下列程式代碼 連線 ivity.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()
   

7. 執行裝置應用程式：

   python ReportConnectivity.py
   

   您應該會看到確認裝置對應項報告屬性已更新。

   

8. 既然裝置回報其連線資訊，它應該會出現在這兩個查詢中。 返回並再次執行查詢：

   python AddTagsAndQuery.py
   

   這次您的 {裝置標識符} 應該會出現在這兩個查詢結果中。

   

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

   

在本文章中，您將：

• 已從後端應用程式新增裝置元數據作為標籤
• 裝置對應項中回報的裝置連線資訊
• 使用 IoT 中樞 查詢語言查詢裝置對應項資訊

下一步

若要了解如何：

• 從裝置傳送遙測，請參閱快速入門：將遙測從 IoT 隨插即用 裝置傳送至 Azure IoT 中樞 一文。

• 使用裝置對應項所需的屬性設定裝置，請參閱 教學課程：從後端服務設定您的裝置。

• 以互動方式控制裝置，例如從使用者控制的應用程式開啟風扇，請參閱 快速入門：控制連線到IoT中樞的裝置。