IoT Hub モジュール ID とモジュール ツイン (Python) の概要Get started with IoT Hub module identity and module twin (Python)

注意

モジュール ID とモジュール ツインは、Azure IoT Hub のデバイス ID とデバイス ツインに似ていますが、より細かい粒度を指定できます。Module identities and module twins are similar to Azure IoT Hub device identities and device twins, but provide finer granularity. Azure IoT Hub のデバイス ID とデバイス ツインでは、バックエンド アプリケーションがデバイスを構成し、そのデバイスの状態に関する可視性を提供できるのに対して、モジュール ID とモジュール ツインでは、これらの機能がデバイスの個々のコンポーネントに対して提供されます。While Azure IoT Hub device identities and device twins enable a back-end application to configure a device and provide visibility on the device's conditions, module identities and module twins provide these capabilities for individual components of a device. 複数のコンポーネントで構成される対応デバイス (オペレーティング システム ベースのデバイスやファームウェア デバイスなど) では、構成や状態をコンポーネントごとに分離できます。On capable devices with multiple components, such as operating system based devices or firmware devices, they allow for isolated configuration and conditions for each component.

このチュートリアルの最後には、次の 3 つの Python アプリが完成します。At the end of this tutorial, you have three Python apps:

  • CreateModule。デバイスとモジュール クライアントを接続するためのデバイス ID、モジュール ID、関連付けられたセキュリティ キーを作成します。CreateModule, which creates a device identity, a module identity, and associated security keys to connect your device and module clients.

  • UpdateModuleTwinDesiredProperties。更新されたモジュール ツインの必要なプロパティを IoT Hub に送信します。UpdateModuleTwinDesiredProperties, which sends updated module twin desired properties to your IoT Hub.

  • ReceiveModuleTwinDesiredPropertiesPatch。デバイスでモジュール ツインの必要なプロパティの修正プログラムを受信します。ReceiveModuleTwinDesiredPropertiesPatch, which receives the module twin desired properties patch on your device.

注意

IoT Hub には、Azure IoT device SDK を介した多数のデバイス プラットフォームや言語 (C、Java、Javascript、Python など) に対する SDK サポートがあります。IoT Hub has SDK support for many device platforms and languages (including C, Java, Javascript, and Python) through Azure IoT device SDKs. このチュートリアルのコード (一般的には Azure IoT Hub) にデバイスを接続するために Python を使用する方法の手順については、Azure IoT Python SDK に関するページを参照してください。For instructions on how to use Python to connect your device to this tutorial's code, and generally to Azure IoT Hub, see the Azure IoT Python SDK.

前提条件Prerequisites

IoT Hub の作成Create an IoT hub

ここでは、Azure portal を使用して IoT ハブを作成する方法について説明します。This section describes how to create an IoT hub using the Azure portal.

  1. Azure portal にサインインします。Sign in to the Azure portal.

  2. Azure ホームページから [+ リソースの作成] ボタンを選択し、 [Marketplace を検索] フィールドに「IoT Hub」と入力します。From the Azure homepage, select the + Create a resource button, and then enter IoT Hub in the Search the Marketplace field.

  3. 検索結果の [IoT Hub] を選択し、 [作成] を選択します。Select IoT Hub from the search results, and then select Create.

  4. [基本] タブで、次のように各フィールドに入力します。On the Basics tab, complete the fields as follows:

    • サブスクリプション:ハブで使用するサブスクリプションを選択します。Subscription: Select the subscription to use for your hub.

    • リソース グループ:リソース グループを選択するか、新しく作成します。Resource Group: Select a resource group or create a new one. 新たに作成するには、 [新規作成] を選択して、使用する名前を入力します。To create a new one, select Create new and fill in the name you want to use. 既存のリソース グループを使用するには、そのリソース グループを選択します。To use an existing resource group, select that resource group. 詳しくは、「Manage Azure Resource Manager resource groups (Azure Resource Manager のリソース グループの管理)」をご覧ください。For more information, see Manage Azure Resource Manager resource groups.

    • [リージョン] :ハブを配置するリージョンを選択します。Region: Select the region in which you want your hub to be located. ユーザーに最も近い場所を選択します。Select the location closest to you. 一部の機能 (IoT Hub デバイス ストリームなど) は、特定のリージョンでのみご利用いただけます。Some features, such as IoT Hub device streams, are only available in specific regions. これらの制限のある機能については、サポート対象のいずれかのリージョンを選択する必要があります。For these limited features, you must select one of the supported regions.

    • [IoT Hub 名] : ハブの名前を入力します。IoT Hub Name: Enter a name for your hub. この名前はグローバルに一意である必要があります。This name must be globally unique. 入力した名前が使用可能な場合は、緑色のチェック マークが表示されます。If the name you enter is available, a green check mark appears.

    重要

    IoT ハブは DNS エンドポイントとして公開されるため、名前を付ける際に機密情報や個人を特定できる情報を入力しないように注意してください。Because the IoT hub will be publicly discoverable as a DNS endpoint, be sure to avoid entering any sensitive or personally identifiable information when you name it.

    Azure portal でハブを作成する

  5. 次へ:Size and scale(次へ: サイズとスケール) を選択して、ハブの作成を続けます。Select Next: Size and scale to continue creating your hub.

    Azure portal を使用して新しいハブのサイズとスケールを設定する

    ここでは、既定の設定をそのまま使用できます。You can accept the default settings here. 必要に応じて、次のフィールドに変更を加えることができます。If desired, you can modify any of the following fields:

    • [価格とスケールティア] : 選択したレベル。Pricing and scale tier: Your selected tier. 必要な機能およびソリューションで 1 日に送信するメッセージの数に応じて、複数のレベルから適切なものを選びます。You can choose from several tiers, depending on how many features you want and how many messages you send through your solution per day. 無料レベルは、テストおよび評価用です。The free tier is intended for testing and evaluation. ハブに接続できるデバイスは 500 個で、1 日に許可されるメッセージ数は最大 8,000 件です。It allows 500 devices to be connected to the hub and up to 8,000 messages per day. Azure サブスクリプションごとに、Free レベルの IoT ハブを 1 つ作成できます。Each Azure subscription can create one IoT hub in the free tier.

      IoT Hub デバイス ストリームのクイックスタートに取り組んでいる場合は、Free レベルを選択してください。If you are working through a Quickstart for IoT Hub device streams, select the free tier.

    • [IoT Hub ユニット] : ユニットごとに許可される 1 日あたりのメッセージの数は、ハブの価格レベルによって決まります。IoT Hub units: The number of messages allowed per unit per day depends on your hub's pricing tier. たとえば、ハブで 700,000 件のイングレス メッセージをサポートする場合は、S1 レベルのユニットを 2 つ選択します。For example, if you want the hub to support ingress of 700,000 messages, you choose two S1 tier units. 他のレベルのオプションについて詳しくは、適切な IoT Hub レベルの選択に関するページをご覧ください。For details about the other tier options, see Choosing the right IoT Hub tier.

    • Azure Security Center:IoT およびお使いのデバイスに、脅威に対する保護のレイヤーを別途追加するには、これをオンにします。Azure Security Center: Turn this on to add an extra layer of threat protection to IoT and your devices. このオプションは、Free レベルのハブでは使用できません。This option is not available for hubs in the free tier. この機能の詳細については、Azure Security Center for IoT に関するページを参照してください。For more information about this feature, see Azure Security Center for IoT.

    • [詳細設定] > [Device-to-cloud パーティション] : このプロパティでは、device-to-cloud メッセージがそのメッセージの同時閲覧者数に関連付けられます。Advanced Settings > Device-to-cloud partitions: This property relates the device-to-cloud messages to the number of simultaneous readers of the messages. ほとんどのハブでは、4 つのパーティションのみが必要となります。Most hubs need only four partitions.

  6. 次へ:[Next](次へ) を選択して、次の画面に進みます。Select Next: Tags to continue to the next screen.

    タグは、名前と値の組です。Tags are name/value pairs. 複数のリソースおよびリソース グループに同じタグを割り当てることで、リソースを分類したり、課金情報を統合したりすることができます。You can assign the same tag to multiple resources and resource groups to categorize resources and consolidate billing. 詳細については、タグを使用した Azure リソースの整理に関するページを参照してください。For more information, see Use tags to organize your Azure resources.

    Azure portal を使用してハブにタグを割り当てる

  7. 次へ:次へ: レビューと作成 をクリックして、選択内容を確認します。Select Next: Review + create to review your choices. 次の画面のようになります。ただし、表示されるのはハブの作成時に選択した値です。You see something similar to this screen, but with the values you selected when creating the hub.

    新しいハブを作成するための情報を確認する

  8. [作成] を選択して、新しいハブを作成します。Select Create to create your new hub. ハブの作成には数分かかります。Creating the hub takes a few minutes.

IoT ハブ接続文字列を取得するGet the IoT hub connection string

この記事では、ID レジストリにデバイスを追加してそのデバイスにモジュールを追加するバックエンド サービスを作成します。In this article, you create a back-end service that adds a device in the identity registry and then adds a module to that device. このサービスには、レジストリ書き込みのアクセス許可 (これには、レジストリ読み取りも含まれます) が必要です。This service requires the registry write permission (which also includes registry read). また、必要なプロパティを新しく作成されたモジュールのモジュール ツインに追加するサービスも作成します。You also create a service that adds desired properties to the module twin for the newly created module. このサービスには、サービス接続のアクセス許可が必要です。This service needs the service connect permission. これらのアクセス許可を個別に付与する既定の共有アクセス ポリシーが存在しますが、このセクションでは、これらのアクセス許可の両方を含むカスタム共有アクセス ポリシーを作成します。Although there are default shared access policies that grant these permissions individually, in this section, you create a custom shared access policy that contains both of these permissions.

サービス接続およびレジストリ書き込みのアクセス許可を付与する共有アクセス ポリシーを作成し、そのポリシーの接続文字列を取得するには、次の手順を実行します。To create a shared access policy that grants service connect and registry write permissions and to get a connection string for this policy, follow these steps:

  1. Azure portal で、 [リソース グループ] を選択します。In the Azure portal, select Resource groups. ハブが配置されているリソース グループを選択し、リソースの一覧からハブを選択します。Select the resource group where your hub is located, and then select your hub from the list of resources.

  2. ハブの左側のウィンドウで、 [共有アクセス ポリシー] を選択します。On the left-side pane of your hub, select Shared access policies.

  3. ポリシーの一覧の上にあるトップ メニューから [追加] を選択します。From the top menu above the list of policies, select Add.

  4. [共有アクセス ポリシーを追加] の下で、ポリシーのわかりやすい名前を入力します (serviceAndRegistryReadWrite など)。Under Add a shared access policy, enter a descriptive name for your policy, such as serviceAndRegistryReadWrite. [アクセス許可][レジストリ書き込み][サービス接続] を選択し、 [作成] を選択しますUnder Permissions, select Registry write and Service connect, and then select Create. ( [レジストリ読み取り] アクセス許可は、 [レジストリ書き込み] を選択すると自動的に含まれます)。(The Registry read permission is included automatically when you select Registry write.)

    新しい共有アクセス ポリシーを追加する方法を示す画面

  5. ポリシーの一覧から、新しいポリシーを選択します。Select your new policy from the list of policies.

  6. [共有アクセス キー] で、 [接続文字列 - プライマリ キー] のコピー アイコンを選択し、その値を保存します。Under Shared access keys, select the copy icon for the Connection string -- primary key and save the value.

    接続文字列を取得する方法を示す画面

IoT Hub の共有アクセス ポリシーとアクセス許可の詳細については、「アクセス制御とアクセス許可」を参照してください。For more information about IoT Hub shared access policies and permissions, see Access control and permissions.

IoT Hub でデバイス ID とモジュール ID を作成するCreate a device identity and a module identity in IoT Hub

このセクションでは、IoT ハブの ID レジストリにデバイス ID とモジュール ID を作成する Python サービス アプリを作成します。In this section, you create a Python service app that creates a device identity and a module identity in the identity registry in your IoT hub. ID レジストリにエントリがない限り、デバイスまたはモジュールは IoT ハブに接続できません。A device or module can't connect to IoT hub unless it has an entry in the identity registry. 詳細については、「IoT Hub の ID レジストリを理解する」を参照してください。For more information, see Understand the identity registry in your IoT hub. このコンソール アプリを実行すると、デバイスとモジュール両方に対して一意のデバイス ID とキーが生成されます。When you run this console app, it generates a unique ID and key for both device and module. デバイスとモジュールは、IoT ハブに device-to-cloud メッセージを送信するときにこれらの値を使用して自分自身を識別します。Your device and module use these values to identify itself when it sends device-to-cloud messages to IoT Hub. ID には大文字と小文字の区別があります。The IDs are case-sensitive.

  1. コマンド プロンプトで次のコマンドを実行して azure-iot-hub パッケージをインストールします。At your command prompt, run the following command to install the azure-iot-hub package:

    pip install azure-iot-hub
    
  2. コマンド プロンプトで、次のコマンドを実行して msrest パッケージをインストールします。At your command prompt, run the following command to install the msrest package. このパッケージは、HTTPOperationError 例外をキャッチするために必要です。You need this package to catch HTTPOperationError exceptions.

    pip install msrest
    
  3. テキスト エディターを使用して、CreateModule.py という名前のファイルを作業ディレクトリに作成します。Using a text editor, create a file named CreateModule.py in your working directory.

  4. Python ファイルに次のコードを追加します。Add the following code to your Python file. YourIoTHubConnectionString を、「IoT ハブ接続文字列を取得する」でコピーした接続文字列に置き換えます。Replace YourIoTHubConnectionString with the connection string you copied in Get the IoT hub connection string.

    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")
    
  5. コマンド プロンプトで、次のコマンドを実行します。At your command prompt, run the following command:

    python CreateModule.py
    

このアプリは、ID myFirstDevice のデバイス ID と ID myFirstModule のモジュール ID をデバイス myFirstDevice の下に作成します。This app creates a device identity with ID myFirstDevice and a module identity with ID myFirstModule under device myFirstDevice. (デバイスまたはモジュール ID が ID レジストリに既に存在する場合、コードは単純に、既存のデバイスまたはモジュール情報を取得します。)アプリには、ID と各 ID のプライマリ キーが表示されます。(If the device or module ID already exists in the identity registry, the code simply retrieves the existing device or module information.) The app displays the ID and primary key for each identity.

注意

IoT ハブの ID レジストリには、IoT ハブに対するセキュリティで保護されたアクセスを有効にするためのデバイス ID とモジュール ID のみが格納されます。The IoT Hub identity registry only stores device and module identities to enable secure access to the IoT hub. ID レジストリには、セキュリティ資格情報として使用されるデバイス ID とキーが格納されます。The identity registry stores device IDs and keys to use as security credentials. ID レジストリには、そのデバイスのアクセスを無効にするために使用できる各デバイスの有効/無効フラグも格納されます。The identity registry also stores an enabled/disabled flag for each device that you can use to disable access for that device. その他デバイス固有のメタデータをアプリケーションで保存する必要がある場合は、アプリケーション固有のストアを使用する必要があります。If your application needs to store other device-specific metadata, it should use an application-specific store. モジュール ID 用の有効/無効フラグはありません。There is no enabled/disabled flag for module identities. 詳細については、「IoT Hub の ID レジストリを理解する」を参照してください。For more information, see Understand the identity registry in your IoT hub.

Python サービス SDK を使用してモジュール ツインを更新するUpdate the module twin using Python service SDK

このセクションでは、モジュール ツインの必要なプロパティを更新する Python サービス アプリを作成します。In this section, you create a Python service app that updates the module twin desired properties.

  1. コマンド プロンプトで、次のコマンドを実行して azure-iot-hub パッケージをインストールします。At your command prompt, run the following command to install the azure-iot-hub package. 前のセクションで azure-iot-hub パッケージをインストールした場合は、この手順をスキップできます。You can skip this step if you installed the azure-iot-hub package in the previous section.

    pip install azure-iot-hub
    
  2. テキスト エディターを使用して、UpdateModuleTwinDesiredProperties.py という名前のファイルを作業ディレクトリに作成します。Using a text editor, create a file named UpdateModuleTwinDesiredProperties.py in your working directory.

  3. Python ファイルに次のコードを追加します。Add the following code to your Python file. YourIoTHubConnectionString を、「IoT ハブ接続文字列を取得する」でコピーした接続文字列に置き換えます。Replace YourIoTHubConnectionString with the connection string you copied in Get the IoT hub connection string.

    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" )
    

デバイス側を更新するGet updates on the device side

このセクションでは、デバイスでモジュール ツインの必要なプロパティの更新プログラムを取得する Python アプリを作成します。In this section, you create a Python app to get the module twin desired properties update on your device.

  1. モジュールの接続文字列を取得します。Get your module connection string. Azure portal で、IoT Hub に移動し、左側のウィンドウで [IoT デバイス] を選択します。In Azure portal, navigate to your IoT Hub and select IoT devices in the left pane. デバイスの一覧から [myFirstDevice] を選択し、それを開きます。Select myFirstDevice from the list of devices and open it. [モジュール ID] で、 [myFirstModule] を選択します。Under Module identities, select myFirstModule. モジュールの接続文字列をコピーします。Copy the module connection string. これは後の手順で必要になります。You need it in a following step.

    Azure Portal モジュールの詳細

  2. コマンド プロンプトで次のコマンドを実行して azure-iot-device パッケージをインストールします。At your command prompt, run the following command to install the azure-iot-device package:

    pip install azure-iot-device
    
  3. テキスト エディターを使用して、ReceiveModuleTwinDesiredPropertiesPatch.py という名前のファイルを作業ディレクトリに作成します。Using a text editor, create a file named ReceiveModuleTwinDesiredPropertiesPatch.py in your working directory.

  4. Python ファイルに次のコードを追加します。Add the following code to your Python file. YourModuleConnectionString を、手順 1 でコピーしたモジュールの接続文字列に置き換えます。Replace YourModuleConnectionString with the module connection string you copied in step 1.

    import time
    import threading
    from azure.iot.device import IoTHubModuleClient
    
    CONNECTION_STRING = "YourModuleConnectionString"
    
    
    def twin_update_listener(client):
        while True:
            patch = client.receive_twin_desired_properties_patch()  # blocking call
            print("")
            print("Twin desired properties patch received:")
            print(patch)
    
    def iothub_client_sample_run():
        try:
            module_client = IoTHubModuleClient.create_from_connection_string(CONNECTION_STRING)
    
            twin_update_listener_thread = threading.Thread(target=twin_update_listener, args=(module_client,))
            twin_update_listener_thread.daemon = True
            twin_update_listener_thread.start()
    
            while True:
                time.sleep(1000000)
    
        except KeyboardInterrupt:
            print("IoTHubModuleClient sample stopped")
    
    
    if __name__ == '__main__':
        print ( "Starting the IoT Hub Python sample..." )
        print ( "IoTHubModuleClient waiting for commands, press Ctrl-C to exit" )
    
        iothub_client_sample_run()
    

アプリの実行Run the apps

このセクションでは、ReceiveModuleTwinDesiredPropertiesPatch デバイス アプリを実行した後、UpdateModuleTwinDesiredProperties サービス アプリを実行して、モジュールの必要なプロパティを更新します。In this section, you run the ReceiveModuleTwinDesiredPropertiesPatch device app and then run the UpdateModuleTwinDesiredProperties service app to update the desired properties of your module.

  1. コマンド プロンプトを開き、デバイス アプリを実行します。Open a command prompt and run the device app:

    python ReceiveModuleTwinDesiredPropertiesPatch.py
    

    デバイス アプリの最初の出力

  2. 別のコマンド プロンプトを開き、サービス アプリを実行します。Open a separate command prompt and run the service app:

    python UpdateModuleTwinDesiredProperties.py
    

    サービス アプリの出力の更新されたモジュール ツインに、必要なプロパティ TelemetryInterval が表示されることに注意してください。Notice that the TelemetryInterval desired property appears in the updated module twin in your service app output:

    サービス アプリの出力

    同じプロパティが、デバイス アプリの出力の受信された必要なプロパティの修正プログラムに表示されます。The same property appears in the desired properties patch received in your device app output:

    デバイス アプリの出力に、必要なプロパティの修正プログラムが表示される

次のステップNext steps

引き続き IoT Hub の使用方法を確認すると共に、他の IoT のシナリオについて調べるには、次のページを参照してください。To continue getting started with IoT Hub and to explore other IoT scenarios, see: