Azure Device Update for IoT Hub での IoT プラグアンドプレイ

[アーティクル]
02/21/2025

IoT Hub 用のデバイス更新では、無線更新対応のデバイスを検出して管理するために、IoT プラグアンドプレイが使用されます。この記事では、Device Update サービスにより、IoT プラグアンドプレイインターフェイスを使用して、デバイスとの間でプロパティとメッセージが送受信する方法について説明します。

詳細については、「IoT プラグアンドプレイデバイス開発者ガイド」および「Device Update エージェントをビルドする方法」を参照してください。

Device Update モデル

スマートデバイスでは、IoT プラグアンドプレイモデル ID を使用して、その機能を Azure IoT アプリケーションに公開します。 Device Update では、IoT プラグアンドプレイスマートデバイスがデバイス接続の一部としてモデル ID を通知する必要があります。詳細については、「モデル ID の通知」を参照してください。

Device Update には、Device Update 機能をサポートする定義済みの IoT プラグアンドプレイモデルがいくつか用意されています。 Device Update モデル **dtmi:azure:iot:deviceUpdateContractModel;3** は Device Update のコア機能をサポートし、Device Update のコアインターフェイスを使用して更新アクションとメタデータをデバイスに送信し、デバイスから更新状態を受信します。

サポートされているもう 1 つのモデル **dtmi:azure:iot:deviceUpdateModel;3** は **deviceUpdateContractModel;3** の拡張版で、デバイスのプロパティ情報を送信して診断機能を有効にする IoT プラグアンドプレイインターフェイスも使用します。これらのバージョンとその他のバージョンについては、「Azure IoT プラグアンドプレイ Device Update モデル」を参照してください。

Device Update エージェントは、 Device Update 1.1.0 リリースのすべての最新機能をサポートする **dtmi:azure:iot:deviceUpdateModel;3** を使用します。このモデルでは、インポートマニフェストバージョン 5.0 がサポートされています。古いマニフェストは最新のエージェントで動作しますが、新機能には最新のマニフェストバージョンが必要です。

エージェントメタデータ

Device Update エージェントでは次のエージェントメタデータフィールドを使用して、Device Update サービスに情報が送信されます。

Name	スキーマ	Direction	説明
deviceProperties	マップ	デバイスからクラウド	製造元、モデル、その他のデバイス情報が含まれるプロパティのセット。詳細については、「デバイスのプロパティ」を参照してください。
compatPropertyNames	文字列 (コンマ区切り)	デバイスからクラウド	更新プログラムのデプロイの対象となるデバイスの互換性を確認するために使用される最大 5 つのプロパティ。例: "compatPropertyNames": "manufacturer,model"
lastInstallResult	マップ	デバイスからクラウド	結果コード、拡張結果コード、およびメインの更新とその他のステップ更新のための結果の詳細を含む、エージェントによって報告された結果。
resultCode	整数 (integer)	デバイスからクラウド	前回の更新操作の結果に関する情報が含まれているコード。成功または失敗のいずれでも設定できます。例: 700
extendedResultCode	整数 (integer)	デバイスからクラウド	結果に関する詳細情報を含むコード。成功または失敗のいずれでも設定できます。例: 0x80004005
resultDetails	string	デバイスからクラウド	結果の詳細を提供するユーザー指定のフリーフォーム文字列。解析せずにツインに返されます。
stepResults	map	デバイスからクラウド	結果コード、拡張結果コード、およびステップ更新のための結果の詳細を含む、エージェントによって報告された結果。例: "step_1": { "resultCode": 0,"extendedResultCode": 0, "resultDetails": ""}
州	整数 (integer)	デバイスからクラウド	デバイス更新エージェントの現在の状態を示す整数。詳細については、「状態」を参照してください。
ワークフロー	複雑	デバイスからクラウド	エージェントが現在動作しているデプロイ、現在インストールされているデプロイの ID、およびサービスからエージェントに送信された再試行要求の受信確認を示す値のセット。 `workflow` ID は、デプロイが取り消されると、`"nodeployment"` 値を報告します。例: "workflow": {"action": 3,"ID": "11b6a7c3-6956-4b33-b5a9-87fdd79d2f01","retryTimestamp": "2022-01-26T11:33:29.9680598Z"}
installedUpdateId	string	デバイスからクラウド	現在インストールされている Device Update デプロイの ID。この値は、更新 ID JSON をキャプチャするか、Device Update を使用して更新を行ったことのないデバイスの場合は `null` をキャプチャします。例: installedUpdateID": "{\"provider\":\"contoso\",\"name\":\"image-update\",\"version\":\"1.0.0\"}"

IoT Hub デバイスツインのサンプル:

"deviceUpdate": {
                "__t": "c",
                "agent": {
                    "deviceProperties": {
                        "manufacturer": "contoso",
                        "model": "virtual-vacuum-v1",
                        "contractModelId": "dtmi:azure:iot:deviceUpdateContractModel;3",
                        "aduVer": "DU;agent/1.1.0",
                        },
                    "compatPropertyNames": "manufacturer,model",
                    "lastInstallResult": {
                        "resultCode": 700,
                        "extendedResultCode": 0,
                        "resultDetails": "",
                        "stepResults": {
                            "step_0": {
                                "resultCode": 700,
                                "extendedResultCode": 0,
                                "resultDetails": ""
                            }
                        }
                    },
                    "state": 0,
                    "workflow": {
                        "action": 3,
                        "id": "11b6a7c3-6956-4b33-b5a9-87fdd79d2f01",
                        "retryTimestamp": "2022-01-26T11:33:29.9680598Z"
                    },
                    "installedUpdateId": "{\"provider\":\"Contoso\",\"name\":\"Virtual-Vacuum\",\"version\":\"5.0\"}"
                },

Note

この要素からコンポーネントを参照していることを示すために、デバイスまたはモジュールは {"__t": "c"} マーカーを追加する必要があります。詳細については、「IoT プラグアンドプレイ規則」を参照してください。

デバイスのプロパティ

deviceProperties フィールドには、デバイスの製造元とモデルの情報が含まれています。

名前	スキーマ	Direction	説明
manufacturer	string	デバイスからクラウド	`deviceProperties` によって報告されたデバイスの製造元。 `DeviceUpdateCore` インターフェイスは、最初に構成ファイルから `aduc_manufacturer` 値の読み取りを試みます。構成ファイルに値が設定されていない場合、インターフェイスは既定で `ADUC_DEVICEPROPERTIES_MANUFACTURER` のコンパイル時の定義を報告します。このプロパティは、起動時にのみ報告されます。既定値: 'Contoso'
モデル	string	デバイスからクラウド	`deviceProperties` によって報告されたデバイスのデバイスモデル。 `DeviceUpdateCore` インターフェイスは、最初に構成ファイルから `aduc_model` 値の読み取りを試みます。構成ファイルに値が設定されていない場合、インターフェイスは既定で `ADUC_DEVICEPROPERTIES_MODEL` のコンパイル時の定義を報告します。このプロパティは、起動時にのみ報告されます。既定値: 'Video'
contractModelId	string	デバイスからクラウド	Device Update エージェントがエージェントの管理と通信に使用している基本モデルバージョンを識別するためにサービスが使用するプロパティ。値: `dtmi:azure:iot:deviceUpdateContractModel;3` (Device Update エージェントバージョン 1.1.0 を使用するデバイスの場合)。注:`dtmi:azure:iot:deviceUpdateModel;2` を使用するエージェントは、`deviceUpdateModel;3` が `deviceUpdateContractModel;3` から拡張されるため、`contractModelId` を `dtmi:azure:iot:deviceUpdateContractModel;3` として報告する必要があります。
aduVer	string	デバイスからクラウド	デバイスで実行されているデバイス更新エージェントのバージョン。この値は、コンパイル時に `ENABLE_ADU_TELEMETRY_REPORTING` が `1` (true) に設定されている場合にのみ、ビルドから読み取られます。値を `0` (false) に設定することにより、バージョンの報告をオプトアウトすることができます。詳細については、「Device Update エージェントをビルドする方法」を参照してください。
doVer	string	デバイスからクラウド	デバイスで実行されている配信最適化エージェントのバージョン。この値は、コンパイル時に `ENABLE_ADU_TELEMETRY_REPORTING` が `1` (true) に設定されている場合にのみ、ビルドから読み取られます。値を `0` (false) に設定することにより、バージョンの報告をオプトアウトすることができます。詳細については、「配信の最適化エージェントのプロパティをカスタマイズする方法」を参照してください。
カスタム互換性プロパティ	ユーザー定義	デバイスからクラウド	更新プログラムのデプロイを対象とするときに互換性チェックに使用するその他のユーザー定義デバイスプロパティ。

都道府県

state フィールドは、Device Update サービスから Device Update エージェントに送信された Action に応答して Device Update エージェントによって報告される状態です。 Device Update サービスと Device Update エージェントの間でやり取りされる要求の詳細については、「エージェントワークフロー」を参照してください。

名前	値	説明
アイドル	0	デバイスは、デバイス更新サービスからアクションを受け取る準備ができています。正常に更新されると、状態は `Idle` 状態に戻ります。
DeploymentInprogress	6	デプロイが進行中です。
失敗	255	更新の間にエラーが発生しました。
DownloadSucceeded	2	ダウンロードが成功しました。エージェントバージョン 0.7.0 以前のデバイスのみが、この状態を報告します。
InstallSucceeded	4	正常にインストールされました。エージェントバージョン 0.7.0 以前のデバイスのみが、この状態を報告します。

アクション

action フィールドは、Device Update サービスによって指示されて Device Update エージェントが実行すべきアクションを表します。 Device Update エージェントは、受信したアクションを処理するための状態を報告します。 Device Update サービスと Device Update エージェントの間でやり取りされる要求の詳細については、「エージェントワークフロー」を参照してください。

名前	値	説明
applyDeployment	3	デプロイされた更新プログラムを適用します。
cancel	255	現在のアクションの処理を停止して `Idle` に戻るか、`Failed` 状態のエージェントに `Idle` に戻るように指示します。
download	0	発行されたコンテンツまたは更新プログラム、および必要なその他のコンテンツをダウンロードします。このアクションは、エージェントバージョン 0.7.0 以前のデバイスにのみ送信されます。
インストール	1	通常は、コンテンツまたは更新プログラムのインストーラーを呼び出すために、コンテンツまたは更新プログラムをインストールします。 Device Update は、エージェントバージョン 0.7.0 以前のデバイスにのみこのアクションを送信します。
apply	2	必要に応じて再起動して更新を完了します。 Device Update は、エージェントバージョン 0.7.0 以前のデバイスにのみこのアクションを送信します。

サービスメタデータ

サービスメタデータには、Device Update サービスによってアクションとデータを Device Update エージェントに伝えるために使用されるフィールドが含まれています。

Name	スキーマ	Direction	説明
action	整数 (integer)	クラウドからデバイス	エージェントが実行する必要のあるアクションに対応する整数。詳細については、「アクション」を参照してください。
updateManifest	string	クラウドからデバイス	更新プログラムの内容について説明します。インポートマニフェストから生成されます。
updateManifestSignature	JSON オブジェクト	クラウドからデバイス	ソースの検証に使用される JSON Web Signature (JWS) と JSON Web キー。
fileUrls	マップ	クラウドからデバイス	`DownloadUrl` への `FileID` のマップ。ダウンロードするファイルと、ファイルが正しくダウンロードされたことを検証するために使用するハッシュを、エージェントに指示します。

デバイス情報インターフェイス

デバイス情報インターフェイスは、IoT プラグアンドプレイアーキテクチャで使用される概念です。このインターフェイスには、デバイスのハードウェアとオペレーティングシステムに関する情報を提供する、デバイスからクラウドへのプロパティが含まれています。 Device Update では、テレメトリと診断のための DeviceInformation.manufacturer および DeviceInformation.model プロパティが使用されます。デバイス情報インターフェイスの例については、https://devicemodels.azure.com/dtmi/azure/devicemanagement/deviceinformation-1.json を参照してください。

このインターフェイスが実装される場合、モデルで予想されるコンポーネント名は deviceInformation です。詳細については、「IoT プラグアンドプレイモデリングガイド」を参照してください。

名前	種類	スキーマ	Direction	説明	例
manufacturer	プロパティ	string	デバイスからクラウド	デバイスの製造元の会社名。製造元は、相手先ブランド供給 (OEM) の名前と同じにすることができます。	Contoso
model	プロパティ	string	デバイスからクラウド	デバイスモデルの名前または ID。	IoT Edge デバイス
swVersion	プロパティ	string	デバイスからクラウド	デバイス上のソフトウェアのバージョン。 swVersion は、ファームウェアのバージョンである場合があります。	4.15.0-122
osName	プロパティ	string	デバイスからクラウド	デバイス上のオペレーティングシステムの名前。	Ubuntu Server 18.04
processorArchitecture	プロパティ	string	デバイスからクラウド	デバイスのプロセッサのアーキテクチャ。	ARM64
processorManufacturer	プロパティ	string	デバイスからクラウド	デバイスのプロセッサの製造元の名前。	Microsoft
totalStorage	プロパティ	string	デバイスからクラウド	デバイスで使用可能な記憶域の合計 (キロバイト単位)。	2048
totalMemory	プロパティ	string	デバイスからクラウド	デバイスで使用可能なメモリの合計 (キロバイト単位)。	256

次の方法で共有

Azure Device Update for IoT Hub での IoT プラグアンドプレイ

Device Update モデル

エージェントメタデータ

デバイスのプロパティ

都道府県

アクション

サービスメタデータ

デバイス情報インターフェイス

フィードバック

その他のリソース

次の方法で共有

Azure Device Update for IoT Hub での IoT プラグ アンド プレイ

Device Update モデル

エージェント メタデータ

デバイスのプロパティ

都道府県

アクション

サービス メタデータ

デバイス情報インターフェイス

関連するコンテンツ

フィードバック

その他のリソース

Azure Device Update for IoT Hub での IoT プラグアンドプレイ

エージェントメタデータ

サービスメタデータ