デバイステンプレートの編集

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

デバイステンプレートには、デバイスが IoT Central とどのようにやり取りするかを記述するモデルが含まれています。このモデルによって、デバイスの機能と、IoT Central がそれらとどのようにやり取りするかが定義されます。デバイスではテレメトリとプロパティ値を IoT Central に送信でき、IoT Central ではプロパティの更新とコマンドをデバイスに送信できます。 IoT Central では、モデルを使用して、ジョブ、ルール、エクスポートなどの IoT Central 機能とのやり取りも定義されます。

デバイステンプレート内のモデルに対する変更は、接続されているデバイスを含め、アプリケーション全体に影響を与える可能性があります。ルール、エクスポート、デバイスグループ、またはジョブによって使用される機能を変更すると、予期しない動作が発生したり、まったく機能しなかったりする可能性があります。たとえば、テンプレートからテレメトリ定義を削除したとします。

IoT Central で値を解釈できなくなります。 IoT Central によって、モデル化されていないデータとして解釈できないデバイスデータが、デバイスの [生データ] ページに表示されます。
IoT Central に、データエクスポート内の値が含まれなくなります。

デバイステンプレートの編集による意図しない結果を回避するために、この記事には、現在の開発ライフサイクルステージに基づく推奨事項が含まれています。一般に、開発ライフサイクルの早い段階のほうが、デバイステンプレートの変更をより許容できます。

デバイステンプレートとデバイステンプレートの作成方法の詳細については、「デバイステンプレートとは」と「デバイステンプレートを設定する」を参照してください。

IoT Central REST API を使用してデバイステンプレートを管理する方法については、「IoT Central REST API を使用してデバイステンプレートを管理する方法」を参照してください。

デバイステンプレートを変更する

機能やインターフェイスをモデルに追加するなどの加法的変更は、非破壊的変更です。開発ライフサイクルの任意の段階で、モデルに加法的変更を行うことができます。

破壊的変更には、モデルの一部の削除や、機能名またはスキーマの種類の変更が含まれます。これらの変更を行うと、ルール、エクスポート、ダッシュボードなどのアプリケーション機能でエラーメッセージが表示され、動作が停止する可能性があります。

デバイス開発の初期段階で、まだモデルの設計とテストを行っている間は、デバイスモデルに直接変更を加える余地が十分にあります。実稼働デバイスをデバイステンプレートに接続する前に、デバイステンプレートを直接編集できます。デバイステンプレートを発行すると、これらの変更が IoT Central によってデバイスに自動的に適用されます。

デバイステンプレートに実稼働デバイスをアタッチした後は、デバイステンプレートを編集する前に、変更の影響を評価してください。実稼働環境で、デバイステンプレートに破壊的変更を加えるべきではありません。このような変更を行うには、新しいバージョンのデバイステンプレートを作成します。新しいデバイステンプレートをテストした後、実稼働デバイスをスケジュールされたダウンタイムで新しいテンプレートに移行します。

IoT Edge デバイステンプレートを更新する

IoT Edge デバイスの場合、モデルでは、デバイスで実行される IoT Edge モジュールに対応するモジュール別に機能がグループ化されます。配置マニフェストは、インストールするモジュールとその構成方法、およびモジュールに設定されているプロパティを IoT Edge デバイスに指示する別個の JSON ドキュメントです。配置マニフェストを変更した場合は、マニフェストで定義されているモジュールとプロパティを含むようにデバイステンプレートを更新できます。

デバイステンプレートの [モジュール] ノードに移動します。
[モジュールの概要] ページで、[マニフェストからモジュールをインポートする] を選択します。
適切な配置マニフェストを選択し、[インポート] を選択します。

詳細については、IoT Edge デバイスと IoT Central に関する記事を参照してください。

編集および発行アクション

デバイステンプレートを編集するときは、次のアクションが役立ちます。

保存。デバイステンプレートの一部を変更したときは、変更を保存することで、戻ることができるドラフトが作成されます。これらの変更は、接続されているデバイスにはまだ影響しません。このテンプレートから作成されたデバイスでは、保存された変更を発行するまで、変更は反映されません。
発行。デバイステンプレートを発行すると、保存したすべての変更が既存のデバイスインスタンスに適用されます。新しく作成されたデバイスインスタンスでは、常に最新の発行済みテンプレートが使用されます。
テンプレートのバージョン作成。デバイステンプレートのバージョンを作成すると、保存された最新のすべての変更を含む新しいテンプレートが作成されます。新しいバージョンに加えられた変更は、既存のデバイスインスタンスには影響しません。詳細については、「デバイステンプレートのバージョン作成」を参照してください。
インターフェイスのバージョン作成。インターフェイスのバージョンを作成すると、保存された最新のすべての機能を含む新しいインターフェイスが作成されます。テンプレート内の複数の場所でインターフェイスを再利用できます。このため、インターフェイスへの 1 つの参照に対して行われた変更によって、そのインターフェイスを使用するテンプレート内のすべての場所で変更が行われます。インターフェイスのバージョンを作成すると、新しいバージョンは別のインターフェイスになるので、この動作が変わります。詳細については、「インターフェイスのバージョン作成」を参照してください。
デバイスの移行。デバイスを移行すると、デバイスインスタンスがデバイステンプレート間でスワップされます。デバイスの移行では、IoT Central で変更が処理される間、不足が発生する可能性があります。詳細については、「バージョン間でデバイスを移行する」を参照してください。

バージョン番号

デバイスモデルとインターフェイスの両方にバージョン番号があります。異なるバージョン番号によって、モデルまたはインターフェイスで @id 値を共有しながら、更新履歴を提供できます。バージョン番号は、テンプレートまたはインターフェイスのバージョン作成を選択した場合、またはバージョン番号を意図的に変更した場合にのみインクリメントされます。テンプレートまたはインターフェイスに大きな変更を行った場合は、バージョン番号を変更する必要があります。

次のスニペットは、あるサーモスタットデバイスのデバイスモデルを示しています。デバイスモデルに、1 つのインターフェイスがあります。 @id フィールドの末尾のバージョン番号 1 を確認できます。

{
  "@context": "dtmi:dtdl:context;2",
  "@id": "dtmi:com:example:Thermostat;1",
  "@type": "Interface",
  "displayName": "Thermostat",
  "description": "Reports current temperature and provides desired temperature control.",
  "contents": [
    // ...
  ]
}

IoT Central UI でこの情報を表示するには、デバイステンプレートエディターで [ID の表示] を選択します。

デバイステンプレートのバージョンを更新する

デバイステンプレートのバージョンを更新するには次を行います。

[デバイステンプレート] ページに移動します。
バージョンを作成するデバイステンプレートを選択します。
ページ上部にある [バージョン] を選択して、テンプレートに新しい名前を付けます。 IoT Central が新しい名前を提案します。この名前は編集できます。
[作成] を選択します。

これで、既存のデバイスにアタッチされていない一意の ID を持つ新しいテンプレートが作成されました。

インターフェイスのバージョンを更新する

インターフェイスのバージョンを更新するには次を行います。

[デバイステンプレート] ページに移動します。
ドラフトモードになっているデバイステンプレートを選択します。
バージョンを作成して編集する、発行済みのインターフェイスを選択します。
インターフェイスページの上部にある [バージョン] ボタンを選択します。
［作成］ を選択します

これで、以前のインターフェイスバージョンと同期されていない一意の ID を持つ新しいインターフェイスが作成されました。

デバイスを複数のバージョンに移行する

複数のバージョンのデバイステンプレートを作成できます。時間の経過と共に、接続された複数のデバイスがこれらのデバイステンプレートを使用するようになります。デバイステンプレートの 1 つのバージョンから、別のバージョンに、デバイスを移行できます。次の手順では、デバイスを移行する方法について説明します。

[デバイス] ページに移動します。
別のバージョンに移行する必要があるデバイスを選択します。
[移行] を選択します。
デバイスの移行先のバージョンが設定されているデバイステンプレートを選択し、 [移行] を選択します。

ヒント

ジョブを使用することで、あるデバイスグループに属するすべてのデバイスを新しいデバイステンプレートに同時に移行できます。

デバイス テンプレートの編集

デバイス テンプレートを変更する

IoT Edge デバイス テンプレートを更新する