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

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

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

注意

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

このチュートリアルの最後には、次の 2 つの .NET コンソールアプリが完成します。

CreateIdentities: ユーザーのデバイスおよびモジュールクライアントに接続するための、デバイス ID、モジュール ID、および関連づけられたセキュリティキーを作成します。
UpdateModuleTwinReportedProperties: 更新されたモジュールツインと報告されたプロパティを IoT ハブに送信します。

Note

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

前提条件

見ることができます。
IoT Hub。 CLI または Azure portal を使って作成します。

モジュールの認証

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

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

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

この記事では、ID レジストリにデバイスを追加してそのデバイスにモジュールを追加するバックエンドサービスを作成します。サービスには、レジストリ書き込みのアクセス許可が必要です。既定では、どの IoT ハブも、このアクセス許可を付与する registryReadWrite という名前の共有アクセスポリシーがある状態で作成されます。

registryReadWrite ポリシーの IoT Hub 接続文字列を取得するには、次の手順を実行します。

Azure portal で、 [リソースグループ] を選択します。ハブが配置されているリソースグループを選択し、リソースの一覧からハブを選択します。
ハブの左側のウィンドウで、 [共有アクセスポリシー] を選択します。
ポリシーの一覧から、 [registryReadWrite] ポリシーを選択します。
[プライマリ接続文字列] をコピーし、値を保存します。

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

モジュール ID を作成する

このセクションでは、ご自身のハブの ID レジストリにデバイス ID とモジュール ID を作成する .NET コンソールアプリを作成します。ハブに接続するデバイスまたはモジュールは、あらかじめ ID レジストリに登録されている必要があります。詳細については、IoT Hub 開発者ガイドの ID レジストリに関するセクションを参照してください。

このコンソールアプリを実行すると、デバイスとモジュール両方に対して一意のデバイス ID とキーが生成されます。デバイスとモジュールでは、IoT ハブに device-to-cloud メッセージを送信するときにこれらの値を使用して自分自身を識別します。 ID には大文字と小文字の区別があります。

Visual Studio を開き、 [新しいプロジェクトの作成] を選択します。
[新しいプロジェクトの作成] で、[コンソールアプリ (.NET Framework)] を選択します。
[次へ] を選択して、[新しいプロジェクトの構成] を開きます。プロジェクトに CreateIdentity という名前を付け、[次へ] を選択します。
既定の .NET Framework オプションをそのまま使用し、[作成] を選択してプロジェクトを作成します。
Visual Studio で、 [ツール]>[NuGet パッケージマネージャー]>[ソリューションの NuGet パッケージの管理] を開きます。 [参照] タブを選択します。
Microsoft.Azure.Devices を検索します。これを選択してから、[インストール] を選択します。
Program.cs ファイルの先頭に次の using ステートメントを追加します。
```
using Microsoft.Azure.Devices;
using Microsoft.Azure.Devices.Common.Exceptions;
```
Program クラスに次のフィールドを追加します。プレースホルダーの値は、前のセクションで作成したハブの IoT Hub 接続文字列に置き換えてください。
```
const string connectionString = "<replace_with_iothub_connection_string>";
const string deviceID = "myFirstDevice";
const string moduleID = "myFirstModule";
```

次の操作を行うコードを Main クラスに追加します。

static void Main(string[] args)
{
    AddDeviceAsync().Wait();
    AddModuleAsync().Wait();
}

Program クラスに次のメソッドを追加します。
```
private static async Task AddDeviceAsync()
{
   RegistryManager registryManager = 
     RegistryManager.CreateFromConnectionString(connectionString);
   Device device;

   try
   {
       device = await registryManager.AddDeviceAsync(new Device(deviceID));
   }
   catch (DeviceAlreadyExistsException)
    {
        device = await registryManager.GetDeviceAsync(deviceID);
    }

    Console.WriteLine("Generated device key: {0}", 
      device.Authentication.SymmetricKey.PrimaryKey);
}

private static async Task AddModuleAsync()
{
    RegistryManager registryManager = 
      RegistryManager.CreateFromConnectionString(connectionString);
    Module module;

    try
    {
        module = 
          await registryManager.AddModuleAsync(new Module(deviceID, moduleID));
    }
    catch (ModuleAlreadyExistsException)
    {
        module = await registryManager.GetModuleAsync(deviceID, moduleID);
    }

    Console.WriteLine("Generated module key: {0}", module.Authentication.SymmetricKey.PrimaryKey);
}
```
AddDeviceAsync メソッドでは、myFirstDevice という ID でデバイス ID が作成されます。そのデバイス ID が既に ID レジストリに存在する場合は、コードにより単にその既存のデバイス情報が取得されます。続けてその ID のプライマリキーが表示されます。シミュレーション対象デバイスアプリ内でこのキーを使用して、ハブに接続します。

AddModuleAsync メソッドでは、デバイス myFirstDevice の下で、myFirstModule という ID でモジュール ID が作成されます。そのモジュール ID が既に ID レジストリに存在する場合は、単にその既存のモジュール情報を取得します。続けてその ID のプライマリキーが表示されます。シミュレートされたモジュールアプリ内でこのキーを使用し、ハブに接続します。

重要

デバイス ID は、カスタマーサポートとトラブルシューティング目的で収集されたログに表示される場合があります。そのため、名前を付ける際は機密情報を含めないようにしてください。
このアプリを実行し、デバイスキーとモジュールキーを書き留めておきます。

Note

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

.NET デバイス SDK を使用してモジュールツインを更新する

次に、シミュレートされたデバイスからクラウドに通信してみましょう。モジュール ID が作成されると、IoT Hub 内でモジュールツインが暗黙的に作成されます。このセクションでは、モジュールツインによって報告されるプロパティを更新する、シミュレートされたデバイス上に.NET を作成するコンソールアプリを作成します。

モジュールの接続文字列を取得するには、お使いの IoT ハブに移動して、[デバイス] を選びます。 myFirstDevice を見つけて選んで開いてから、myFirstModule を選んで開きます。 [モジュール ID の詳細] で、[接続文字列 (主キー)] をコピーしてコンソールアプリ用に保存します。

Visual Studio で、 [ファイル]>[新規作成]>[プロジェクト] の順に選択し、ソリューションに新しいプロジェクトを追加します。 新しいプロジェクトの作成 で、コンソールアプリ (.NET Framework) を選択し、次へを選択します。
[新しいプロジェクトの構成] で、プロジェクトに「UpdateModuleTwinReported Properties」という名前を付け、[次へ] を選択します。
既定の .NET Framework オプションをそのまま使用し、[作成] を選択してプロジェクトを作成します。
Visual Studio で、 [ツール]>[NuGet パッケージマネージャー]>[ソリューションの NuGet パッケージの管理] を開きます。 [参照] タブを選択します。
Microsoft.Azure.Devices.Client を検索して選択し、 [インストール] を選択します。

Program.cs ファイルの先頭に次の using ステートメントを追加します。

using Microsoft.Azure.Devices.Client;
using Microsoft.Azure.Devices.Shared;
using System.Threading.Tasks;
using Newtonsoft.Json;

Program クラスに次のフィールドを追加します。プレースホルダーの値をモジュールの接続文字列に置き換えます。

private const string ModuleConnectionString = "<Your module connection string>";
private static ModuleClient Client = null;
static void ConnectionStatusChangeHandler(ConnectionStatus status, 
  ConnectionStatusChangeReason reason)
{
    Console.WriteLine("Connection Status Changed to {0}; the reason is {1}", 
      status, reason);
}

次の OnDesiredPropertyChanged メソッドを Program クラスに追加します。

private static async Task OnDesiredPropertyChanged(TwinCollection desiredProperties, 
  object userContext)
    {
        Console.WriteLine("desired property change:");
        Console.WriteLine(JsonConvert.SerializeObject(desiredProperties));
        Console.WriteLine("Sending current time as reported property");
        TwinCollection reportedProperties = new TwinCollection
        {
            ["DateTimeLastDesiredPropertyChangeReceived"] = DateTime.Now
        };

        await Client.UpdateReportedPropertiesAsync(reportedProperties).ConfigureAwait(false);
    }

Main メソッドに次の行を追加します。

static void Main(string[] args)
{
    Microsoft.Azure.Devices.Client.TransportType transport = 
      Microsoft.Azure.Devices.Client.TransportType.Amqp;

    try
    {
        Client = 
          ModuleClient.CreateFromConnectionString(ModuleConnectionString, transport);
        Client.SetConnectionStatusChangesHandler(ConnectionStatusChangeHandler);
        Client.SetDesiredPropertyUpdateCallbackAsync(OnDesiredPropertyChanged, null).Wait();

        Console.WriteLine("Retrieving twin");
        var twinTask = Client.GetTwinAsync();
        twinTask.Wait();
        var twin = twinTask.Result;
        Console.WriteLine(JsonConvert.SerializeObject(twin.Properties)); 

        Console.WriteLine("Sending app start time as reported property");
        TwinCollection reportedProperties = new TwinCollection();
        reportedProperties["DateTimeLastAppLaunch"] = DateTime.Now;

        Client.UpdateReportedPropertiesAsync(reportedProperties);
    }
    catch (AggregateException ex)
    {
        Console.WriteLine("Error in sample: {0}", ex);
    }

    Console.WriteLine("Waiting for Events.  Press enter to exit...");
    Console.ReadLine();
    Client.CloseAsync().Wait();
}

これで、モジュールツインを取得し、報告されたプロパティを AMQP プロトコルを使って更新する方法がわかりました。

必要に応じて、これらのステートメントを Main メソッドに追加して、モジュールから IoT Hub にイベントを送信できます。これらの行を try catch ブロックの下に配置します。
```
Byte[] bytes = new Byte[2];
bytes[0] = 0;
bytes[1] = 1;
var sendEventsTask = Client.SendEventAsync(new Message(bytes));
sendEventsTask.Wait();
Console.WriteLine("Event sent to IoT Hub.");
```

アプリの実行

これで、アプリケーションを実行できます。

Visual Studio のソリューションエクスプローラーでソリューションを右クリックし、 [スタートアッププロジェクトの設定] を選択します。
[共通プロパティ] の下の [スタートアッププロジェクト] を選択します。
アプリに対するアクションとして、 [マルチスタートアッププロジェクト] を選択し、 [起動する] を選択し、 [OK] をクリックして変更を受け入れます。
F5 キーを押してアプリを起動します。

次のステップ

引き続き IoT Hub の使用方法を確認すると共に、他の IoT のシナリオについて調べるには、次のページを参照してください。

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