Iot ソリューションで IoT プラグ アンド プレイを使用する

この記事では、IoT ソリューションにおいて、IoT プラグ アンド プレイ デバイスのモデル ID を識別し、次にそのモデル定義を取得する方法について説明します。

IoT ソリューションには、大きく分けて 2 つのカテゴリがあります。

• "専用のソリューション" は、ソリューションに接続する IoT プラグ アンド プレイ デバイスの既知のモデル セットで機能します。 ソリューションを開発するときに、これらのモデルを使用します。

• "モデル駆動型ソリューション" は、任意の IoT プラグ アンド プレイ デバイスのモデルで機能します。 モデル駆動型ソリューションの構築はより複雑ですが、今後追加される可能性がある任意のデバイスでソリューションが機能するという利点があります。 モデル駆動型 IoT ソリューションでは、モデルを取得し、それを使用することで、デバイスが実装するテレメトリ、プロパティ、およびコマンドが決定されます。

IoT プラグ アンド プレイ モデルを使用するには、IoT ソリューションで次のことを行います。

1. ソリューションに接続されている IoT プラグ アンド プレイ デバイス、モジュール、または IoT Edge モジュールによって実装されるモデルのモデル ID を識別します。

2. そのモデル ID を使用して、接続されているデバイスのモデル定義をモデル リポジトリまたはカスタム ストアから取得します。

モデル ID を識別する

IoT プラグ アンド プレイ デバイスが IoT Hub に接続されると、それによって実装されているモデルのモデル ID が IoT Hub に登録されます。

IoT Hub は、デバイス接続フローの一環としてデバイス モデル ID を使用してソリューションに通知します。

ソリューションでは、次の 3 つの方法のいずれかを使用して、IoT プラグ アンド プレイ デバイスのモデル ID を取得できます。

Get Device Twin API

このソリューションでは、Get Device Twin API を使用して、IoT プラグ アンド プレイ デバイスのモデル ID を取得することができます。

ヒント

モジュールと IoT Edge モジュールの場合は、ModuleClient.getTwin を使用します。

次のデバイス ツイン応答スニペットでは、IoT プラグ アンド プレイ デバイスのモデル ID が modelId に含まれています。

{
    "deviceId": "sample-device",
    "etag": "AAAAAAAAAAc=",
    "deviceEtag": "NTk0ODUyODgx",
    "status": "enabled",
    "statusUpdateTime": "0001-01-01T00:00:00Z",
    "connectionState": "Disconnected",
    "lastActivityTime": "2020-07-17T06:12:26.8402249Z",
    "cloudToDeviceMessageCount": 0,
    "authenticationType": "sas",
    "x509Thumbprint": {
        "primaryThumbprint": null,
        "secondaryThumbprint": null
    },
    "modelId": "dtmi:com:example:TemperatureController;1",
    "version": 15,
    "properties": {...}
    }
}

Get Digital Twin API

ソリューションでは、Get Digital Twin API を使用して、IoT プラグ アンド プレイ デバイスによって実装されたモデルのモデル ID を取得できます。

次のデジタル ツイン応答スニペットでは、IoT プラグ アンド プレイ デバイスのモデル ID が $metadata.$model に含まれています。

{
    "$dtId": "sample-device",
    "$metadata": {
        "$model": "dtmi:com:example:TemperatureController;1",
        "serialNumber": {
            "lastUpdateTime": "2020-07-17T06:10:31.9609233Z"
        }
    }
}

デジタル ツインの変更イベント通知

デバイスの接続により、Digital Twin 変更イベント通知が生成されます。 ソリューションは、このイベント通知をサブスクライブする必要があります。 デジタル ツイン イベントのルーティングを有効にする方法については、「IoT Hub メッセージ ルーティングを使用して device-to-cloud メッセージを別のエンドポイントに送信する」を参照してください。

このソリューションでは、次のスニペットに示すイベントを使用して、接続している IoT プラグ アンド プレイ デバイスについて把握し、そのモデル ID を取得することができます。

iothub-connection-device-id:sample-device
iothub-enqueuedtime:7/22/2020 8:02:27 PM
iothub-message-source:digitalTwinChangeEvents
correlation-id:100f322dc2c5
content-type:application/json-patch+json
content-encoding:utf-8
[
  {
    "op": "replace",
    "path": "/$metadata/$model",
    "value": "dtmi:com:example:TemperatureController;1"
  }
]

モデル定義を取得する

ソリューションでは、以前に識別されたモデル ID を使用して、対応するモデル定義が取得されます。

ソリューションでモデル定義を取得するには、次のいずれかのオプションを使用します。

モデル リポジトリ

ソリューションでは、デバイス モデル リポジトリ (DMR) から DTDL モデルを取得することができます。 DMR は、Microsoft がホストするパブリック リポジトリであり、キュレーションされた DTDL モデルのコレクションが含まれています。 DMR 内に保存されているパブリック デバイス モデルは、すべてのユーザーがパブリック エンドポイント https://devicemodels.azure.com からアプリケーション内で使用および統合することができます。

新しいデバイス接続用のモデル ID を識別したら、次の手順を行います。

1. モデル リポジトリからのモデル ID を使用して、モデル定義を取得します。 詳しくは、「モデルを解決する」を参照してください。

2. 接続されたデバイスのモデル定義を使用すれば、デバイスの機能を列挙できます。

3. デバイスの列挙機能を使用すれば、ユーザーがデバイスと対話するのを許可することができます。

モデルを解決する

DMR の規約には、ホストされるモデルの使用を簡略化するためのその他のアーティファクトが含まれています。 これらの機能は、カスタムリポジトリまたはプライベートリポジトリでは オプション となります。

• Index。 使用可能なすべての DTMI は、一連の json ファイルによって構成される次のようなインデックスを介して公開されます: https://devicemodels.azure.com/index.page.2.json
• 拡張済み。 すべての依存関係を持つファイルは、各インターフェイスで使用できます。たとえば: https://devicemodels.azure.com/dtmi/com/example/temperaturecontroller-1.expanded.json
• メタデータ。 このファイルは、リポジトリのキー属性を公開し、最新の公開済みモデル スナップショットで定期的に更新されます。 これには、モデル インデックスまたは拡張モデル ファイルが使用可能かどうかなど、リポジトリが実装する機能が含まれます。 https://devicemodels.azure.com/metadata.json で DMR メタデータにアクセスできます。

DMR 内のパブリック DTDL モデルにプログラムでアクセスするには、NuGet パッケージ Azure.IoT.ModelsRepository において入手可能な ModelsRepositoryClient を使用することができます。 既定では、このクライアントは devicemodels.azure.com で入手可能なパブリック DMR に対してクエリを実行するように構成されており、任意のカスタム リポジトリに対して構成できます。

クライアントは DTMI を入力として受け取り、必要なすべてのインターフェイスを含むディクショナリを返します。

using Azure.IoT.ModelsRepository;

var client = new ModelsRepositoryClient();
ModelResult models = client.GetModel("dtmi:com:example:TemperatureController;1");
models.Content.Keys.ToList().ForEach(k => Console.WriteLine(k));

予想される出力には、依存関係チェーンで見つかった 3 つのインターフェイスの DTMI が表示されます。

dtmi:com:example:TemperatureController;1
dtmi:com:example:Thermostat;1
dtmi:azure:DeviceManagement:DeviceInformation;1

ModelsRepositoryClient は、https を通じて利用可能なカスタム DMR をクエリし、ModelDependencyResolution フラグを使用して依存関係の解決を指定するように構成できます。

• Disabled。 指定されたインターフェイスだけを返します。依存関係はありません。
• 有効にします。 依存関係チェーン内のすべてのインターフェイスを返します。

ヒント

カスタム リポジトリでは、.expanded.json ファイルが公開されない場合があります。 このファイルを使用できない場合、クライアントは各依存関係をローカルで処理するためにフォールバックします。

次のサンプル コードは、カスタム リポジトリのベース URL を使用して ModelsRepositoryClient を初期化する方法を示しています。この例では、expanded フォームを使用せずに (raw エンドポイントで利用できないため)、GitHub API からの raw URL を使用しています。 AzureEventSourceListener は、クライアントによって実行される HTTP 要求を検査するために初期化されます。

using AzureEventSourceListener listener = AzureEventSourceListener.CreateConsoleLogger();

var client = new ModelsRepositoryClient(
    new Uri("https://raw.githubusercontent.com/Azure/iot-plugandplay-models/main"));

ModelResult model = await client.GetModelAsync(
    "dtmi:com:example:TemperatureController;1", 
    dependencyResolution: ModelDependencyResolution.Enabled);

model.Content.Keys.ToList().ForEach(k => Console.WriteLine(k));

Azure SDK GitHub リポジトリ (Azure.Iot.ModelsRepository/samples) で、さらに多くのサンプルを入手できます。

カスタム ストア

ソリューションでは、これらのモデル定義をローカル ファイル システムまたはパブリック ファイル ストアに格納することも、カスタム実装を使用することもできます。

新しいデバイス接続用のモデル ID を識別したら、次の手順を行います。

1. ご利用のカスタム ストアからのモデル ID を使用して、モデル定義を取得します。

2. 接続されたデバイスのモデル定義を使用すれば、デバイスの機能を列挙できます。

3. デバイスの列挙機能を使用すれば、ユーザーがデバイスと対話するのを許可することができます。

次のステップ

IoT プラグ アンド プレイ モデルを IoT ソリューションに統合する方法を学習したので、次に推奨されるいくつかのステップを以下に示します。

• ソリューションからデバイスを操作する
• IoT Digital Twin REST API
• Azure IoT エクスプローラー