開始使用 IoT 中樞模組身分識別和模組對應項 (Python)

發行項
08/25/2023

模組身分識別與模組對應項類似於 Azure IoT 中樞裝置身分識別與裝置對應項，但提供更精細的細微性。雖然 Azure IoT 中樞裝置身分識別與裝置對應項可讓後端應用程式設定裝置並提供裝置狀況的可見性，但模組身分識別和模組對應項可提供裝置個別元件的上述功能。多個元件的支援裝置 (例如作業系統裝置或韌體裝置) 允許每個元件使用獨立的設定和條件。

注意

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

在本文結尾，您會有三個 Python 應用程式：

CreateModule：建立裝置身分識別、模組身分識別和關聯的安全性金鑰，並連線您的裝置與模組用戶端。
UpdateModuleTwinDesiredProperties：傳送更新的模組對應項、所需屬性至 IoT 中樞。
ReceiveModuleTwinDesiredPropertiesPatch：在裝置上接收模組對應項、所需屬性的修補檔。

注意

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

必要條件

使用中的 Azure 帳戶。 (如果您沒有帳戶，只需要幾分鐘的時間就可以建立免費帳戶。)
IoT 中樞。使用 CLI 或 Azure 入口網站建立一個。
建議使用 Python 3.7 版或更新版本。請務必使用安裝程式所需的 32 位元或 64 位元安裝。在安裝期間出現系統提示時，務必將 Python 新增至平台特有的環境變數。

模組驗證

您可以使用對稱金鑰或 X.509 憑證來驗證模組身分識別。針對 X.509 憑證驗證，模組的憑證必須具有其一般名稱， (CN) 格式如下 CN=<deviceid>/<moduleid> 。例如：

openssl req -new -key d1m1.key.pem -out d1m1.csr -subj "/CN=device01\/module01"

取得 IoT 中樞連接字串

在本文中，您會建立後端服務，以在身分識別登錄中新增裝置，然後將模組新增至該裝置。此服務需要登錄寫入權限 (其中也包含登錄讀取)。您也會建立服務，將所需的屬性新增至新建模組的模組對應項。此服務需要服務連線權限。雖然預設的共用存取原則會個別授與這些權限，但在本節中，您會建立包含這兩個權限的自訂共用存取原則。

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

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

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

在 IoT 中樞中建立裝置身分識別與模組身分識別

在本節中，您會建立 Python 服務應用程式，其會在 IoT 中樞的身分識別登錄中建立裝置身分識別和模組身分識別。裝置或模組無法連線到 IoT 中樞，除非其在身分識別登錄中具有項目。如需詳細資訊，請參閱了解 IoT 中樞中的身分識別登錄。當您執行此主控台應用程式時，它會針對裝置和模組產生唯一的識別碼和金鑰。識別碼和金鑰區分大小寫。當裝置和模組將裝置到雲端的訊息傳送給 IoT 中樞時，裝置和模組會使用這些值來識別自己。

在命令提示字元中，執行下列命令以安裝 azure-iot-hub 套件：
```
pip install azure-iot-hub
```
在命令提示字元中，執行下列命令以安裝 msrest 套件。您需要此套件來擷取 HTTPOperationError 例外狀況。
```
pip install msrest
```
使用文字編輯器，在工作目錄中建立名為 CreateModule.py 的檔案。

將下列程式碼新增至 Python 檔案。將 YourIoTHubConnectionString 取代為在取得 IoT 中樞連接字串中複製連接字串。

import sys
from msrest.exceptions import HttpOperationError
from azure.iot.hub import IoTHubRegistryManager

CONNECTION_STRING = "YourIotHubConnectionString"
DEVICE_ID = "myFirstDevice"
MODULE_ID = "myFirstModule"

try:
    # RegistryManager
    iothub_registry_manager = IoTHubRegistryManager(CONNECTION_STRING)

    try:
        # CreateDevice - let IoT Hub assign keys
        primary_key = ""
        secondary_key = ""
        device_state = "enabled"
        new_device = iothub_registry_manager.create_device_with_sas(
            DEVICE_ID, primary_key, secondary_key, device_state
        )
    except HttpOperationError as ex:
        if ex.response.status_code == 409:
            # 409 indicates a conflict. This happens because the device already exists.
            new_device = iothub_registry_manager.get_device(DEVICE_ID)
        else:
            raise

    print("device <" + DEVICE_ID +
          "> has primary key = " + new_device.authentication.symmetric_key.primary_key)

    try:
        # CreateModule - let IoT Hub assign keys
        primary_key = ""
        secondary_key = ""
        managed_by = ""
        new_module = iothub_registry_manager.create_module_with_sas(
            DEVICE_ID, MODULE_ID, managed_by, primary_key, secondary_key
        )
    except HttpOperationError as ex:
        if ex.response.status_code == 409:
            # 409 indicates a conflict. This happens because the module already exists.
            new_module = iothub_registry_manager.get_module(DEVICE_ID, MODULE_ID)
        else:
            raise

    print("device/module <" + DEVICE_ID + "/" + MODULE_ID +
          "> has primary key = " + new_module.authentication.symmetric_key.primary_key)

except Exception as ex:
    print("Unexpected error {0}".format(ex))
except KeyboardInterrupt:
    print("IoTHubRegistryManager sample stopped")

在命令提示字元中，執行下列命令：
```
python CreateModule.py
```

此應用程式會在 myFirstDevice 裝置下方建立識別碼為 myFirstDevice 的裝置身分識別，以及識別碼為 myFirstModule 的模組身分識別。 (如果裝置或模組識別碼已經存在身分識別登錄中，程式碼就只會擷取現有的裝置或模組資訊)。應用程式會顯示每個身分識別的識別碼和主索引鍵。

注意

IoT 中樞身分識別登錄只會儲存裝置和模組身分識別，以啟用對 IoT 中樞的安全存取。身分識別登錄會儲存裝置識別碼和金鑰，以作為安全性認證使用。身分識別登錄也會儲存每個裝置的已啟用/已停用旗標，以便您用來停用該裝置的存取權。如果您的應用程式需要儲存其他裝置特定的中繼資料，它應該使用應用程式專用的存放區。模組身分識別沒有啟用/停用旗標。如需詳細資訊，請參閱了解 IoT 中樞中的身分識別登錄。

使用 Python 服務 SDK 更新模組對應項

在本節中，您會建立 Python 服務應用程式，以更新模組對應項所需的屬性。

在命令提示字元中，執行下列命令以安裝 azure-iot-hub 套件。如果您已在上一節中安裝 azure-iot-hub 套件，則可以略過此步驟。
```
pip install azure-iot-hub
```
使用文字編輯器，在工作目錄中建立名為 UpdateModuleTwinDesiredProperties.py 的檔案。

將下列程式碼新增至 Python 檔案。將 YourIoTHubConnectionString 取代為在取得 IoT 中樞連接字串中複製連接字串。

import sys
from azure.iot.hub import IoTHubRegistryManager
from azure.iot.hub.models import Twin, TwinProperties

CONNECTION_STRING = "YourIoTHubConnectionString"
DEVICE_ID = "myFirstDevice"
MODULE_ID = "myFirstModule"

try:
    # RegistryManager
    iothub_registry_manager = IoTHubRegistryManager(CONNECTION_STRING)

    module_twin = iothub_registry_manager.get_module_twin(DEVICE_ID, MODULE_ID)
    print ( "" )
    print ( "Module twin properties before update    :" )
    print ( "{0}".format(module_twin.properties) )

    # Update twin
    twin_patch = Twin()
    twin_patch.properties = TwinProperties(desired={"telemetryInterval": 122})
    updated_module_twin = iothub_registry_manager.update_module_twin(
        DEVICE_ID, MODULE_ID, twin_patch, module_twin.etag
    )
    print ( "" )
    print ( "Module twin properties after update     :" )
    print ( "{0}".format(updated_module_twin.properties) )

except Exception as ex:
    print ( "Unexpected error {0}".format(ex) )
except KeyboardInterrupt:
    print ( "IoTHubRegistryManager sample stopped" )

取得裝置端的更新

在本節中，您會建立 Python 應用程式，以取得裝置上模組對應項所需的屬性更新。

取得模組連接字串。在 Azure 入口網站中，瀏覽至 IoT 中樞，然後在左側窗格中，選取 [裝置]。從裝置清單中選取 myFirstDevice 並加以開啟。在 [模組身分識別] 底下，選取 [myFirstModule]。選取 [連接字串 (主索引鍵)] 的複製圖示。在下列步驟中，您會需要此連接字串。
在命令提示字元中，執行下列命令以安裝 azure-iot-device 套件：
```
pip install azure-iot-device
```
使用文字編輯器，在工作目錄中建立名為 ReceiveModuleTwinDesiredPropertiesPatch.py 的檔案。

將下列程式碼新增至 Python 檔案。將 YourModuleConnectionString 取代為在步驟 1 複製的模組連接字串。

import time
from azure.iot.device import IoTHubModuleClient

CONNECTION_STRING = "YourModuleConnectionString"


def twin_patch_handler(twin_patch):
    print("")
    print("Twin desired properties patch received:")
    print(twin_patch)


def main():
    print ("Starting the IoT Hub Python sample...")
    client = IoTHubModuleClient.create_from_connection_string(CONNECTION_STRING)

    print ("Waiting for commands, press Ctrl-C to exit")
    try:
        # Attach the handler to the client
        client.on_twin_desired_properties_patch_received = twin_patch_handler

        while True:
            time.sleep(1000)
    except KeyboardInterrupt:
        print("IoTHubModuleClient sample stopped")
    finally:
        # Graceful exit
        print("Shutting down IoT Hub Client")
        client.shutdown()

if __name__ == '__main__':
    main()

執行應用程式

在本節中，您會執行 ReceiveModuleTwinDesiredPropertiesPatch 裝置應用程式，然後執行 UpdateModuleTwinDesiredProperties 服務應用程式來更新模組所需的屬性。

開啟命令提示字元，並執行裝置應用程式：
```
python ReceiveModuleTwinDesiredPropertiesPatch.py
```
開啟個別的命令提示字元並執行服務應用程式：
```
python UpdateModuleTwinDesiredProperties.py
```
請注意，TelemetryInterval 所需的屬性會出現在服務應用程式輸出中的已更新模組對應項中：

相同的屬性會出現在裝置應用程式輸出中收到的所需屬性修補中：

後續步驟

若要繼續開始使用 IoT 中樞並瀏覽其他 IoT 案例，請參閱︰