デバイステンプレートとは

[アーティクル]
07/20/2024

Azure IoT Central のデバイステンプレートは、アプリケーションに接続する種類のデバイスの特性と動作を定義するブループリントです。たとえば、デバイステンプレートによって、IoT Central が、適切なユニットとデータの種類を使用して視覚化を作成できるように、デバイスが送信するテレメトリが定義されます。デバイステンプレート定義に一致するテレメトリは、"モデル化された" データと呼ばれます。デバイステンプレート定義と一致しないテレメトリは、"モデル化されていない" データと呼ばれます。

ソリューションビルダーは、デバイステンプレートを IoT Central アプリケーションに追加します。デバイス開発者は、デバイステンプレートで定義された動作を実装するデバイスコードを作成します。デバイステンプレートを作成する方法、または自動的に生成する方法の詳細については、「Azure IoT Central アプリケーション内でデバイステンプレートを作成する」を参照してください。デバイスと IoT Central との間で交換されるデータの詳細については、「テレメトリ、プロパティ、およびコマンドのペイロード」を参照してください。

デバイステンプレートは、次のセクションで構成されます。

デバイスのモデル。デバイステンプレートのこの部分では、デバイスがアプリケーションと対話する方法を定義します。どのデバイスモデルにも一意の IDがあります。デバイス開発者は、モデルで定義された動作を実装します。
- ルートコンポーネント。どのデバイスモデルにもルートコンポーネントがあります。ルートコンポーネントのインターフェイスは、そのデバイスモデルに固有の機能を記述します。
- コンポーネント。デバイスモデルには、デバイス機能を記述するためのルートコンポーネント以外のコンポーネントが含まれる場合があります。各コンポーネントには、コンポーネントの機能を記述するインターフェイスがあります。コンポーネントのインターフェイスは、他のデバイスモデルで再利用できます。たとえば、いくつかの電話デバイスモデルでは同じカメラインターフェイスを使用できます。
- 継承インターフェイス。デバイスモデルには、ルートコンポーネントの機能を拡張する 1 つ以上のインターフェイスが含まれています。
"ビュー"。デバイステンプレートのこの部分では、ソリューション開発者が、デバイスからのデータを表示する視覚化と、デバイスの管理や制御を行うフォームを定義します。ビューは、デバイスモデルを実装するためにデバイス開発者が作成するコードには影響しません。

デバイスをデバイステンプレートに割り当てる

デバイスが IoT Central と対話するには、デバイステンプレートに割り当てられている必要があります。この割り当ては、次の 4 つの方法のいずれかで行います。

[デバイス] ページでデバイスを登録するときに、デバイスで使用するテンプレートを特定できます。
デバイスの一覧を一括インポートすると、一覧のすべてのデバイスで使用するデバイステンプレートを選択できます。
割り当てられていないデバイスを、その接続後にデバイステンプレートに手動で割り当てることができます。
デバイスをアプリケーションに最初に接続するときにモデル ID を送信すると、デバイスを自動的にデバイステンプレートに割り当てることができます。

自動割り当て

IoT Central を使用すると、デバイスの接続時にデバイスを自動的にデバイステンプレートに割り当てることができます。デバイスは、接続時にモデル ID を送信します。 IoT Central は、モデル ID を使用して、その特定のデバイスモデルのデバイステンプレートを識別します。検出プロセスは次のように実行されます。

IoT Central アプリケーションでデバイステンプレートが既に発行されている場合、デバイスはデバイステンプレートに割り当てられます。
デバイステンプレートが IoT Central アプリケーションにまだ発行されていない場合、IoT Central はパブリックデバイスモデルリポジトリでデバイスモデルを検索します。モデルが見つかると、それを使用して基本のデバイステンプレートが生成されます。
パブリックモデルリポジトリでモデルが見つからない場合、デバイスは未割り当てとしてマークされます。オペレーターは次のことができます。
- デバイス用のデバイステンプレートを作成してから、割り当てられていないデバイスを新しいデバイステンプレートに移行します。
- デバイスが送信するデータに基づいて、デバイステンプレートを自動生成します。

次のスクリーンショットは、IoT Central でデバイステンプレートのモデル ID を表示する方法を示しています。デバイステンプレート内でコンポーネントを選択し、[ID の編集] を選択します。

パブリックモデルリポジトリ内のサーモスタットモデルは表示できます。モデル ID の定義は次のようになります。

"@id": "dtmi:com:example:Thermostat;1"

次の DPS パイロードを使用して、デバイスをデバイステンプレートに割り当てます。

{
  "modelId":"dtmi:com:example:TemperatureController;2"
}

DPS ペイロードについて詳しくは、「チュートリアル: クライアントアプリケーションを作成して Azure IoT Central アプリケーションに接続する」で使われているサンプルコードをご覧ください。

デバイスモデル

デバイスモデルでは、デバイスが IoT Central アプリケーションと対話する方法を定義します。デバイス開発者は、IoT Central でデバイスを監視、管理できるように、デバイスモデルで定義された動作がデバイスに実装されていることを確認する必要があります。デバイスモデルは、1 つ以上の "インターフェイス" で構成され、各インターフェイスでは、"テレメトリ" の種類、"デバイスプロパティ"、"コマンド" のコレクションを定義できます。ソリューション開発者は次のことができます。

完全なデバイスモデルまたは個々のインターフェイスが定義されている JSON ファイルをデバイステンプレートにインポートします。
IoT Central の Web UI を使って、デバイスモデルを作成または編集します。

Note

IoT Central は、デバイスからの有効な JSON ペイロードを受け入れますが、データを視覚化に使用できるのは、デバイスモデルでの定義と一致している場合のみです。定義に一致していないデータをエクスポートできます。「Blob Storage を使用してクラウドの宛先に IoT データをエクスポートする」を参照してください。

デバイスモデルの編集の詳細については、「既存のデバイステンプレートの編集」を参照してください。

ソリューション開発者は、完全なデバイスモデルまたは個別のインターフェイスを含むデバイステンプレートから JSON ファイルをエクスポートすることもできます。デバイス開発者は、この JSON ドキュメントを使用して、デバイスが IoT Central アプリケーションと通信する方法を理解することができます。

デバイスモデルを定義する JSON ファイルでは、デジタルツイン定義言語 (DTDL) v2 が使用されます。 IoT Central では、JSON ファイルに、個別のファイルではなく、インラインで定義されたインターフェイスがあるデバイスモデルが含まれていると想定しています。 IoT Central で作成されたモデルでは、モデルが IoT Central で作成されたことを示すコンテキスト dtmi:iotcentral:context;2 が定義されています。

"@context": [
  "dtmi:iotcentral:context;2",
  "dtmi:dtdl:context;2"
]

DTDL モデルについて詳しくは、「IoT プラグアンドプレイモデリングガイド」をご覧ください。

Note

IoT Central では、DTDL v2 言語に対するいくつかの拡張機能が定義されています。詳細については、「IoT Central 拡張機能」を参照してください。

プロパティ

既定では、プロパティは読み取り専用です。読み取り専用のプロパティは、デバイスがプロパティ値の更新を IoT Central アプリケーションに報告することを意味します。 IoT Central アプリケーションでは、読み取り専用のプロパティの値を設定することはできません。

インターフェイスでは、プロパティを書き込み可能としてマークすることもできます。デバイスは、IoT Central アプリケーションから書き込み可能なプロパティに対する更新を受け取り、プロパティ値の更新をアプリケーションに報告することができます。

プロパティ値を設定するためにデバイスを接続する必要はありません。更新された値は、デバイスが次にアプリケーションに接続したときに転送されます。この動作は、読み取り専用プロパティと書き込み可能なプロパティの両方に適用されます。

デバイスからテレメトリを送信するために、プロパティを使用しないでください。たとえば、temperatureSetting=80 などの読み取り専用プロパティは、デバイスの温度が 80 に設定されており、デバイスがこの目標の温度に達しようとしている、または維持しようとしていることを意味します。

書き込み可能なプロパティの場合、デバイスアプリケーションは、必要な状態の状態コード、バージョン、および説明を返して、プロパティ値を受け取って適用したかどうかを示します。

クラウドプロパティ

モデルのルートコンポーネントにクラウドプロパティを追加することもできます。クラウドプロパティを使うと、IoT Central アプリケーションに格納するデバイスメタデータを指定できます。クラウドプロパティの値は IoT Central アプリケーションに格納され、デバイスと同期されることはありません。クラウドプロパティは、デバイスモデルを実装するためにデバイス開発者が作成するコードには影響しません。

ソリューション開発者は、デバイスプロパティと共にクラウドプロパティをデバイスビューおよびフォームに追加して、オペレーターがアプリケーションに接続されたデバイスを管理できるようにすることができます。さらに、ソリューション開発者は、クラウドプロパティをルール定義の一部として使用して、オペレーターがしきい値を編集できるようにすることもできます。

次に示す DTDL のスニペットは、クラウドプロパティ定義の例です。

{
    "@id": "dtmi:azureiot:Thermostat:CustomerName",
    "@type": [
        "Property",
        "Cloud",
        "StringValue"
    ],
    "displayName": {
        "en": "Customer Name"
    },
    "name": "CustomerName",
    "schema": "string"
}

テレメトリ

IoT Central を使用すると、デバイスビューやグラフにテレメトリを表示したり、しきい値に達したときにアクションをトリガーするためのルールを使用したりすることができます。 IoT Central では、データ型、ユニット、表示名などのデバイスモデル内の情報を使用して、テレメトリ値の表示方法が決定されます。また、アプリケーションや個人用ダッシュボードにテレメトリ値を表示することもできます。

IoT Central のデータエクスポート機能を使用して、ストレージや Event Hubs などの他の保存先にテレメトリをストリーミングすることができます。

コマンド

コマンドは、既定で 30 秒以内に実行する必要があり、コマンドが到着したときにデバイスを接続する必要があります。デバイスが時間内に応答しない場合、またはデバイスが接続されていない場合、コマンドは失敗します。

コマンドは、要求パラメーターを使用して応答を返すことができます。

オフラインコマンド

デバイステンプレートでコマンドの [Queue if offline]\(オフラインの場合にキュー\) オプションを有効にすることで、デバイスが現在オフラインになっている場合にキューコマンドを選択できます。

オフラインコマンドは、ご利用のソリューションからデバイスへの一方向通知です。オフラインコマンドは、要求パラメーターを使用できますが、応答を返すことはできません。

Note

オフラインコマンドは、モデルを DTDL としてエクスポートした場合、durable としてマークされます。

オフラインコマンドは、IoT Hub のクラウドからデバイスへのメッセージを使用して、コマンドとペイロードをデバイスに送信します。

デバイスが受信するメッセージのペイロードは、パラメーターの生の値です。 method-name というカスタムプロパティは、IoT Central コマンドの名前を格納します。ペイロードの例を次の表に示します。

IoT Central 要求スキーマ	デバイスによって受信されたペイロードの例
要求パラメーターなし	`@`
倍精度浮動小数点型	`1.23`
String	`sample string`
Object	`{"StartTime":"2021-01-05T08:00:00.000Z","Bank":2}`

デバイスモデルの次のスニペットは、コマンドの定義を示しています。このコマンドには、datetime フィールドと列挙型を持つオブジェクトパラメーターが含まれています。

{
  "@type": "Command",
  "displayName": {
    "en": "Generate Diagnostics"
  },
  "name": "GenerateDiagnostics",
  "request": {
    "@type": "CommandPayload",
    "displayName": {
      "en": "Payload"
    },
    "name": "Payload",
    "schema": {
      "@type": "Object",
      "displayName": {
        "en": "Object"
      },
      "fields": [
        {
          "displayName": {
            "en": "StartTime"
          },
          "name": "StartTime",
          "schema": "dateTime"
        },
        {
          "displayName": {
            "en": "Bank"
          },
          "name": "Bank",
          "schema": {
            "@type": "Enum",
            "displayName": {
              "en": "Enum"
            },
            "enumValues": [
              {
                "displayName": {
                  "en": "Bank 1"
                },
                "enumValue": 1,
                "name": "Bank1"
              },
              {
                "displayName": {
                  "en": "Bank2"
                },
                "enumValue": 2,
                "name": "Bank2"
              },
              {
                "displayName": {
                  "en": "Bank3"
                },
                "enumValue": 3,
                "name": "Bank3"
              }
            ],
            "valueSchema": "integer"
          }
        }
      ]
    }
  }
}

前のスニペットにあるコマンドのデバイステンプレート UI で [オフラインの場合にキューに入れる] オプションを有効にした場合、デバイスが受信するメッセージには次のプロパティが含まれます。

プロパティ名	例値
`custom_properties`	`{'method-name': 'GenerateDiagnostics'}`
`data`	`{"StartTime":"2021-01-05T08:00:00.000Z","Bank":2}`

ビュー

ソリューション開発者は、オペレーターが接続されたデバイスを監視および管理できるビューを作成します。ビューはデバイステンプレートの一部であるため、特定のデバイスの種類に関連付けられます。ビューには、次のものを含めることができます。

テレメトリをプロットするグラフ。
読み取り専用デバイスのプロパティを表示するタイル。
オペレーターが書き込み可能なデバイスプロパティを編集できるようにするタイル。
オペレーターがクラウドプロパティを編集できるようにするタイル。
オペレーターが、ペイロードを想定するコマンドなどのコマンドを呼び出すために使用するタイル。
ラベル、画像、またはマークダウンテキストを表示するタイル。

次のステップ

デバイステンプレートについて学習したので、次のステップとしては、「テレメトリ、プロパティ、コマンドのペイロード」を読んで、デバイスが IoT Central とやり取りするデータの詳細を理解することをお勧めします。

次の方法で共有

デバイステンプレートとは

デバイスをデバイステンプレートに割り当てる

自動割り当て

デバイスモデル

プロパティ

クラウドプロパティ

テレメトリ

コマンド

オフラインコマンド

ビュー

次のステップ

フィードバック

その他のリソース

次の方法で共有

デバイス テンプレートとは

デバイスをデバイス テンプレートに割り当てる

自動割り当て

デバイス モデル

プロパティ

クラウド プロパティ

テレメトリ

コマンド

オフライン コマンド

ビュー

次のステップ

フィードバック

その他のリソース

デバイステンプレートとは

デバイスをデバイステンプレートに割り当てる

デバイスモデル

クラウドプロパティ

オフラインコマンド