デバイスツインの使用 (.NET)

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

デバイスツインは、デバイスに関する情報 (メタデータ、構成、状態など) を格納する JSON ドキュメントです。 IoT Hub は、IoT Hub に接続する各デバイスにデバイスツインを保持します。

Note

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

次の場合にデバイスツインを使用します。

ソリューションバックエンドからデバイスメタデータを格納する。
デバイスアプリで利用できる機能や状態 (たとえば、使用される接続方法) などの現在の状態に関する情報をレポートする。
デバイスアプリとバックエンドアプリの間で実行時間の長いワークフロー (ファームウェアや構成の更新など) の状態を同期する。
デバイスメタデータ、構成、または状態を照会する。

デバイスツインは、同期のほか、デバイスの構成と状態の照会に対応しています。デバイスツインの使用方法など、デバイスツインの詳細については、デバイスツインの理解に関するページを参照してください。

IoT ハブには、次の要素を含むデバイスツインが格納されます。

タグ。ソリューションバックエンドからのみアクセスできるデバイスメタデータです。
必要なプロパティ。ソリューションバックエンドから変更でき、デバイスアプリから監視できる JSON オブジェクトです。
報告されるプロパティ。デバイスアプリから変更でき、ソリューションバックエンドから読み取り可能な JSON オブジェクトです。

タグとプロパティには配列を含めることはできませんが、入れ子になったオブジェクトを含めることができます。

次の図は、デバイスツイン組織を示しています。

デバイスツインの概念図のスクリーンショット。

さらに、ソリューションバックエンドは、上記のすべてのデータに基づいてデバイスツインに対してクエリを実行できます。デバイスツインの詳細については、デバイスツインの理解に関するページを参照してください。クエリ実行の詳細については、IoT Hub クエリ言語に関するページを参照してください。

この記事で取り上げるテクニック:

シミュレートされたデバイスアプリを使用して、その接続チャネルをデバイスツインで報告されたプロパティとして報告します。
以前に作成したタグとプロパティのフィルターを使用して、バックエンドアプリからデバイスに対してクエリを実行します。

この記事では、次の 2 つの .NET コンソールアプリを作成します。

AddTagsAndQuery: タグの追加とデバイスツインのクエリを実行するバックエンドアプリ。
ReportConnectivity: IoT ハブに接続してその接続状態を報告するシミュレートされたデバイスアプリ。

Note

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

前提条件

見ることができます。
IoT Hub。 CLI または Azure portal を使って作成します。
登録済みのデバイス。 Azure portal に登録してください。
ポート 8883 がファイアウォールで開放されていることを確認してください。この記事のデバイスサンプルでは、ポート 8883 を介して通信する MQTT プロトコルを使用しています。このポートは、企業や教育用のネットワーク環境によってはブロックされている場合があります。この問題の詳細と対処方法については、「IoT Hub への接続 (MQTT)」を参照してください。

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

この記事では、デバイスツインに必要なプロパティを追加した後、ID レジストリに対してクエリを実行し、適切に更新された報告されるプロパティを持つデバイスをすべて検索するバックエンドサービスを作成します。そのサービスには、必要なデバイスツインのプロパティを変更するためのサービス接続アクセス許可と、ID レジストリに対してクエリを実行するためのレジストリ読み取りアクセス許可が必要となります。その 2 つのアクセス許可だけを含んだ既定の共有アクセスポリシーは存在しないため、共有アクセスポリシーを独自に作成する必要があります。

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

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

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

報告されたプロパティを更新するデバイスアプリを作成する

このセクションでは、myDeviceId としてハブに接続される .NET コンソールアプリを作成し、その報告されたプロパティを更新して、接続に携帯ネットワークが使用されていることを確認します。

Visual Studio を開き、[新しいプロジェクトの作成] を選びます。
[コンソールアプリ (.NET Framework)] を選び、[次へ] を選びます。
[新しいプロジェクトの構成] で、プロジェクトに ReportConnectivity という名前を付け、[次へ] を選びます。
ソリューションエクスプローラーで ReportConnectivity プロジェクトを右クリックし、 [NuGet パッケージの管理] を選択します。
既定の .NET Framework をそのまま使い、[作成] を選んでプロジェクトを作成します。
[参照] を選択し、Microsoft.Azure.Devices.Client を探して選択します。 [インストール] を選択します。

この手順により、パッケージのダウンロードとインストールが実行され、Azure IoT device SDK NuGet パッケージへの参照とその依存関係が追加されます。

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

using Microsoft.Azure.Devices.Client;
using Microsoft.Azure.Devices.Shared;
using Newtonsoft.Json;

Program クラスに次のフィールドを追加します。 {device connection string} を、IoT Hub にデバイスを登録した時に表示されたデバイス接続文字列に置き換えます。
```
static string DeviceConnectionString = "HostName=<yourIotHubName>.azure-devices.net;DeviceId=<yourIotDeviceName>;SharedAccessKey=<yourIotDeviceAccessKey>";
static DeviceClient Client = null;
```

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

public static async void InitClient()
{
    try
    {
        Console.WriteLine("Connecting to hub");
        Client = DeviceClient.CreateFromConnectionString(DeviceConnectionString, 
          TransportType.Mqtt);
        Console.WriteLine("Retrieving twin");
        await Client.GetTwinAsync();
    }
    catch (Exception ex)
    {
        Console.WriteLine();
        Console.WriteLine("Error in sample: {0}", ex.Message);
    }
}

Client オブジェクトに、デバイスからデバイスツインとやりとりするのに必要なすべてのメソッドが表示されます。上記のコードでは、クライアント オブジェクトが初期化された後、myDeviceId のデバイスツインが取得されます。

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

public static async void ReportConnectivity()
{
    try
    {
        Console.WriteLine("Sending connectivity data as reported property");

        TwinCollection reportedProperties, connectivity;
        reportedProperties = new TwinCollection();
        connectivity = new TwinCollection();
        connectivity["type"] = "cellular";
        reportedProperties["connectivity"] = connectivity;
        await Client.UpdateReportedPropertiesAsync(reportedProperties);
    }
    catch (Exception ex)
    {
        Console.WriteLine();
        Console.WriteLine("Error in sample: {0}", ex.Message);
    }
}

上記のコードでは、myDeviceId の報告されるプロパティが接続情報で更新されます。

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

try
{
    InitClient();
    ReportConnectivity();
}
catch (Exception ex)
{
    Console.WriteLine();
    Console.WriteLine("Error in sample: {0}", ex.Message);
}
Console.WriteLine("Press Enter to exit.");
Console.ReadLine();

ソリューションエクスプローラーでソリューションを右クリックし、 [スタートアッププロジェクトの設定] を選択します。
[共通プロパティ]>[スタートアッププロジェクト] で、 [マルチスタートアッププロジェクト] を選択します。 ReportConnectivity では、 [アクション] として [開始] を選択します。 [OK] を選択して変更を保存します。
ReportConnectivity プロジェクトを右クリックし、 [デバッグ] を選択してから、 [新しいインスタンスを開始] を選択して、このアプリを実行します。アプリでツインの情報が取得された後、接続性が "報告されるプロパティ" として送信される様子が見られます。

デバイスの接続情報が報告された後、両方のクエリで表示されるようになります。
AddTagsAndQuery プロジェクトを右クリックし、 [デバッグ]>[新しいインスタンスを開始] を選択して、クエリを再実行します。今回は、myDeviceId が両方のクエリ結果に表示されるはずです。

目的のプロパティおよびクエリツインを更新するサービスアプリを作成する

このセクションでは、myDeviceId に関連付けられたデバイスツインに場所のメタデータを追加する .NET コンソールアプリを C# を使用して作成します。このアプリは、IoT ハブで米国内にあるデバイスのクエリを実行した後、携帯ネットワーク接続を報告しているデバイスのクエリを実行します。

Visual Studio で、[ファイル] > [新規作成] > [プロジェクト] の順に選びます。 [新しいプロジェクトの作成] で、 [コンソールアプリ (.NET Framework)] を選択してから、 [次へ] を選択します。
[新しいプロジェクトの構成] で、プロジェクトに AddTagsAndQuery という名前を付け、[次へ] を選びます。
.NET Framework の既定のバージョンをそのまま使用し、[作成] を選択してプロジェクトを作成します。
ソリューションエクスプローラーで AddTagsAndQuery プロジェクトを右クリックし、 [NuGet パッケージの管理] を選択します。
[参照] を選択し、Microsoft.Azure.Devices を探して選択します。 [インストール] を選択します。

この手順により、パッケージのダウンロードとインストールが実行され、Azure IoT service SDK NuGet パッケージへの参照とその依存関係が追加されます。
Program.cs ファイルの先頭に次の using ステートメントを追加します。
```
using Microsoft.Azure.Devices;
```
Program クラスに次のフィールドを追加します。 {iot hub connection string} を、「IoT ハブ接続文字列を取得する」でコピーしておいた IoT ハブ接続文字列に置き換えてください。
```
static RegistryManager registryManager;
static string connectionString = "{iot hub connection string}";
```
Program クラスに次のメソッドを追加します。
```
public static async Task AddTagsAndQuery()
{
    var twin = await registryManager.GetTwinAsync("myDeviceId");
    var patch =
        @"{
            tags: {
                location: {
                    region: 'US',
                    plant: 'Redmond43'
                }
            }
        }";
    await registryManager.UpdateTwinAsync(twin.DeviceId, patch, twin.ETag);

    var query = registryManager.CreateQuery(
      "SELECT * FROM devices WHERE tags.location.plant = 'Redmond43'", 100);
    var twinsInRedmond43 = await query.GetNextAsTwinAsync();
    Console.WriteLine("Devices in Redmond43: {0}", 
      string.Join(", ", twinsInRedmond43.Select(t => t.DeviceId)));

    query = registryManager.CreateQuery("SELECT * FROM devices WHERE tags.location.plant = 'Redmond43' AND properties.reported.connectivity.type = 'cellular'", 100);
    var twinsInRedmond43UsingCellular = await query.GetNextAsTwinAsync();
    Console.WriteLine("Devices in Redmond43 using cellular network: {0}", 
      string.Join(", ", twinsInRedmond43UsingCellular.Select(t => t.DeviceId)));
}
```
RegistryManager クラスに、サービスからデバイスツインとやりとりするのに必要なすべてのメソッドが表示されます。前のコードでは、まず registryManager オブジェクトを初期化し、myDeviceId のデバイスツインを取得して、最後にタグを目的の位置情報で更新します。

更新後、2 つのクエリを実行します。1 番目のクエリでは、Redmond43 工場にあるデバイスのデバイスツインのみを選択し、2 番目のクエリでは携帯ネットワーク経由で接続しているデバイスのみを選択します。

前のコードでは、query オブジェクトの作成時に、返されるドキュメントの最大数を指定します。 query オブジェクトには、GetNextAsTwinAsync メソッドを複数回呼び出してすべての結果を取得する際に使用できる HasMoreResults のブール型プロパティが含まれます。 GetNextAsJson というメソッドは、集計クエリの結果など、デバイスツインではない結果に使用できます。

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

registryManager = RegistryManager.CreateFromConnectionString(connectionString);
AddTagsAndQuery().Wait();
Console.WriteLine("Press Enter to exit.");
Console.ReadLine();

AddTagsAndQuery プロジェクトを右クリックし、 [デバッグ] を選択してから、 [新しいインスタンスを開始] を選択して、このアプリケーションを実行します。 Redmond43 にあるすべてのデバイスを照会するクエリの結果には、1 件のデバイスが表示され、携帯ネットワークを使用するデバイスに絞り込んだ結果には 0 件のデバイスが表示されます。

この記事では、次の内容について説明します。

バックエンドアプリからタグとしてデバイスメタデータを追加しました
デバイスツインでデバイス接続情報を報告しました
SQL に似た IoT Hub クエリ言語を使用して、デバイスツイン情報のクエリを実行しました

次のステップ

参照:

デバイスからテレメトリを送信するには、「クイックスタート: IoT プラグアンドプレイデバイスから Azure IoT Hub にテレメトリを送信する」を参照してください。
デバイスツインの目的のプロパティを使用してデバイスを構成するには、「チュートリアル: バックエンドサービスからデバイスを構成する」を参照してください。
ユーザー制御アプリからファンをオンにするなど、対話形式でデバイスを制御するには、「クイックスタート: IoT ハブに接続されたデバイスを制御する」を参照してください。

デバイス ツインの使用 (.NET)

前提条件

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

報告されたプロパティを更新するデバイス アプリを作成する

目的のプロパティおよびクエリ ツインを更新するサービス アプリを作成する

次のステップ

その他のリソース

デバイスツインの使用 (.NET)

報告されたプロパティを更新するデバイスアプリを作成する

目的のプロパティおよびクエリツインを更新するサービスアプリを作成する