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

[アーティクル]
04/01/2024

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

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

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

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

ソリューションに接続されている IoT プラグアンドプレイデバイス、モジュール、または IoT Edge モジュールによって実装されるモデルのモデル ID を識別します。
そのモデル 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 を識別したら、次の手順を行います。

モデルリポジトリからのモデル ID を使用して、モデル定義を取得します。詳しくは、「モデルを解決する」を参照してください。
接続されたデバイスのモデル定義を使用すれば、デバイスの機能を列挙できます。
デバイスの列挙機能を使用すれば、ユーザーがデバイスと対話するのを許可することができます。

モデルを解決する

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 は、http(s) を通じて利用可能なカスタム 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 を識別したら、次の手順を行います。

ご利用のカスタムストアからのモデル ID を使用して、モデル定義を取得します。
接続されたデバイスのモデル定義を使用すれば、デバイスの機能を列挙できます。
デバイスの列挙機能を使用すれば、ユーザーがデバイスと対話するのを許可することができます。

次のステップ

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

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