IoT Hub モジュール ID とモジュールツイン (Python) の概要

[アーティクル]
03/24/2023

モジュール ID とモジュールツインは、Azure IoT Hub のデバイス ID とデバイスツインに似ていますが、より細かい粒度を指定できます。 Azure IoT Hub のデバイス ID とデバイスツインでは、バックエンドアプリケーションがデバイスを構成し、そのデバイスの状態に関する可視性を提供できるのに対して、モジュール ID とモジュールツインでは、これらの機能がデバイスの個々のコンポーネントに対して提供されます。複数のコンポーネントで構成される対応デバイス (オペレーティングシステムデバイスやファームウェアデバイスなど) では、構成や状態をコンポーネントごとに分離できます。

注意

この記事で説明されている機能は、Standard レベルの IoT Hub でのみ使用できます。 Basic および Standard または Free レベルの IoT Hub の詳細については、「ソリューションに適した IoT Hub のレベルを選択する」を参照してください。

この記事の最後には、次の 3 つの Python アプリが完成します。

CreateModule: デバイスとモジュールクライアントを接続するためのデバイス ID、モジュール ID、関連付けられたセキュリティキーを作成します。
UpdateModuleTwinDesiredProperties: 更新されたモジュールツインの必要なプロパティを IoT Hub に送信します。
ReceiveModuleTwinDesiredPropertiesPatch: デバイスでモジュールツインの必要なプロパティの修正プログラムを受信します。

注意

デバイスとバックエンドアプリの両方の構築に使用できる SDK ツールに関する詳細については、「Azure IoT SDK」を参照してください。

前提条件

アクティブな Azure アカウントアカウントがない場合、Azure 試用版にサインアップして、最大 10 件の無料 Mobile Apps を入手できます。 (アカウントがない場合は、無料アカウントを数分で作成できます)。
IoT Hub。 CLI または Azure portal を使って作成します。
Python バージョン 3.7 以降をお勧めします。必ず、セットアップに必要な 32 ビットまたは 64 ビットのインストールを使用してください。インストール中に求められた場合は、プラットフォーム固有の環境変数に Python を追加します。

モジュールの認証

モジュールの認証には、対称キーまたは X.509 証明書を使用することができます。 X.509 証明書認証の場合、モジュールの証明書には、CN=<deviceid>/<moduleid> のような書式のモジュールの共通名が含まれている "必要があります"。次に例を示します。

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

IoT ハブ接続文字列を取得する

この記事では、ID レジストリにデバイスを追加してそのデバイスにモジュールを追加するバックエンドサービスを作成します。このサービスには、レジストリ書き込みのアクセス許可 (これには、レジストリ読み取りも含まれます) が必要です。また、必要なプロパティを新しく作成されたモジュールのモジュールツインに追加するサービスも作成します。このサービスには、サービス接続のアクセス許可が必要です。これらのアクセス許可を個別に付与する既定の共有アクセスポリシーが存在しますが、このセクションでは、これらのアクセス許可の両方を含むカスタム共有アクセスポリシーを作成します。

サービス接続およびレジストリ書き込みのアクセス許可を付与する共有アクセスポリシーを作成し、そのポリシーの接続文字列を取得するには、次の手順を実行します。

Azure portal で、 [リソースグループ] を選択します。ハブが配置されているリソースグループを選択し、リソースの一覧からハブを選択します。
ハブの左側のウィンドウで、 [共有アクセスポリシー] を選択します。
ポリシー一覧の上にあるメニューから、 [共有アクセスポリシーの追加] を選びます。
[共有アクセスポリシーを追加] にポリシーのわかりやすい名前を入力します (serviceAndRegistryReadWrite など)。 [アクセス許可] で [レジストリ書き込み] と [サービス接続] を選択し、[追加] を選択します。 ([レジストリ読み取り] アクセス許可は、[レジストリ書き込み] を選択すると自動的に含まれます。)
ポリシーの一覧から、新しいポリシーを選択します。
[共有アクセスキー] の [プライマリ接続文字列] のコピーアイコンを選び、その値を保存します。

IoT Hub の共有アクセスポリシーとアクセス許可の詳細については、「アクセス制御とアクセス許可」を参照してください。

IoT Hub でデバイス ID とモジュール ID を作成する

このセクションでは、IoT ハブの ID レジストリにデバイス ID とモジュール ID を作成する Python サービスアプリを作成します。 ID レジストリにエントリがない限り、デバイスまたはモジュールは IoT ハブに接続できません。詳細については、「IoT Hub の ID レジストリを理解する」を参照してください。このコンソールアプリを実行すると、デバイスとモジュール両方に対して一意のデバイス ID とキーが生成されます。 ID とキーは大文字と小文字が区別されます。デバイスとモジュールは、IoT ハブに device-to-cloud メッセージを送信するときにこれらの値を使用して自分自身を識別します。

コマンドプロンプトで次のコマンドを実行して 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
```

このアプリは、ID myFirstDevice のデバイス ID と ID myFirstModule のモジュール ID をデバイス myFirstDevice の下に作成します。 (デバイスまたはモジュール ID が ID レジストリに既に存在する場合、コードは単純に、既存のデバイスまたはモジュール情報を取得します。)アプリには、ID と各 ID のプライマリキーが表示されます。

Note

IoT ハブの ID レジストリには、IoT ハブに対するセキュリティで保護されたアクセスを有効にするためのデバイス ID とモジュール ID のみが格納されます。 ID レジストリには、セキュリティ資格情報として使用されるデバイス ID とキーが格納されます。 ID レジストリには、そのデバイスのアクセスを無効にするために使用できる各デバイスの有効/無効フラグも格納されます。その他デバイス固有のメタデータをアプリケーションで保存する必要がある場合は、アプリケーション固有のストアを使用する必要があります。モジュール ID 用の有効/無効フラグはありません。詳細については、「IoT Hub の ID レジストリを理解する」を参照してください。

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 portal で、IoT Hub に移動し、左側のウィンドウで [デバイス] を選択します。デバイスの一覧から [myFirstDevice] を選択し、それを開きます。 [モジュール ID] で、 [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 Hub の使用方法を確認すると共に、他の IoT のシナリオについて調べるには、次のページを参照してください。

Share via

IoT Hub モジュール ID とモジュールツイン (Python) の概要

前提条件

モジュールの認証

IoT ハブ接続文字列を取得する

IoT Hub でデバイス ID とモジュール ID を作成する

Python サービス SDK を使用してモジュールツインを更新する

デバイス側を更新する

アプリの実行

次のステップ

その他のリソース

Share via

IoT Hub モジュール ID とモジュール ツイン (Python) の概要

前提条件

モジュールの認証

IoT ハブ接続文字列を取得する

IoT Hub でデバイス ID とモジュール ID を作成する

Python サービス SDK を使用してモジュール ツインを更新する

デバイス側を更新する

アプリの実行

次のステップ

その他のリソース

IoT Hub モジュール ID とモジュールツイン (Python) の概要

Python サービス SDK を使用してモジュールツインを更新する