IoT Edge エージェントと IoT Edge ハブのモジュール ツインのプロパティ
適用対象:
IoT Edge 1.5 IoT Edge 1.4
重要
サポートされているリリースは、IoT Edge 1.5 LTS と IoT Edge 1.4 LTS です。 IoT Edge 1.4 LTS は、2024 年 11 月 12 日にサポートが終了します。 以前のリリースの場合は、「IoT Edge を更新する」を参照してください。
IoT Edge エージェントと IoT Edge ハブは、IoT Edge ランタイムを構成する 2 つのモジュールです。 各ランタイム モジュールの役割について詳しくは、「Azure IoT Edge ランタイムとそのアーキテクチャの概要」をご覧ください。
この記事では、ランタイム モジュール ツインの必要なプロパティと報告されるプロパティを示します。 IoT Edge デバイスにモジュールをデプロイする方法の詳細については、IoT Edge にモジュールをデプロイしてルートを確立する方法に関する記事をご覧ください。
モジュール ツインには以下が含まれます。
必要なプロパティ。 ソリューション バックエンドにより必要なプロパティを設定でき、モジュールによりそれらを読み取れます。 モジュールでは、必要なプロパティに対する変更を知らせる通知を受け取ることもできます。 モジュールの構成や状態を同期するために、必要なプロパティを報告されるプロパティと共に使用します。
報告されるプロパティ。 モジュールにより、報告されたプロパティを設定でき、ソリューション バックエンドによりそれらを読み取って、クエリを実行できます。 モジュールの構成や状態を同期するために、報告されたプロパティが必要なプロパティと共に使用されます。
edgeAgent の必要なプロパティ
IoT Edge エージェントのモジュール ツインは $edgeAgent と呼ばれ、デバイス上で実行されている IoT Edge エージェントと IoT Hub の間の通信を調整します。 必要なプロパティは、単一デバイスまたは大規模デプロイの一部として特定のデバイスにデプロイ マニフェストを適用するときに設定されます。
| プロパティ | 内容 | 必須 |
|---|---|---|
| imagePullPolicy | OnCreate または Never でイメージをプルする場合 (イメージが既にデバイス上にある場合は使用できません) | はい |
| restartPolicy | モジュールを再起動する必要がある場合。 使用可能な値: Never: 実行されていない場合はモジュールを再起動しません。Always: 実行中でない場合は常にモジュールを再起動します。On-Unhealthy: 異常な場合はモジュールを再起動します。 異常とは、正常性チェックに基づいて Docker が報告するものです。たとえば、"Unhealthy - the container is not working correctly"、 On-Failed: Failed の場合は再起動します。 | はい |
| runtime.type | docker である必要があります。 | はい |
| runtime.settings.minDockerVersion | この配置マニフェストに必要な最小 Docker バージョンに設定されます。 | はい |
| runtime.settings.loggingOptions | IoT Edge エージェント コンテナーのログ オプションを含む文字列化された JSON。 Docker のログ オプション | いいえ |
| runtime.settings.registryCredentials.{registryId}.username | コンテナー レジストリのユーザー名です。 Azure Container Registry では、ユーザー名は通常、レジストリ名です。 すべてのプライベート モジュール イメージにおいて、レジストリの資格情報が必要です。 | いいえ |
| runtime.settings.registryCredentials.{registryId}.password | コンテナー レジストリのパスワード。 | いいえ |
| runtime.settings.registryCredentials.{registryId}.address | コンテナー レジストリのアドレス。 Azure Container Registry の場合、アドレスは通常 {registry name}.azurecr.io です。 | いいえ |
| schemaVersion | 1.0 または 1.1 のいずれかです。 バージョン 1.1 は IoT Edge バージョン 1.0.10 で導入されました。こちらが推奨されます。 | はい |
| status | モジュールの目的の状態: 実行中 または 停止済み。 | 必須 |
| systemModules.edgeAgent.type | docker である必要があります。 | はい |
| systemModules.edgeAgent.startupOrder | モジュールの起動場所を示す整数値。 0 が最初で、最大の整数 (4294967295) は最後です。 値が指定されていない場合、既定値は最大の整数になります。 | いいえ |
| systemModules.edgeAgent.settings.image | IoT Edge エージェントのイメージの URI。 現在、IoT Edge エージェントは自動更新できません。 | はい |
| systemModules.edgeAgent.settings.createOptions | IoT Edge エージェント コンテナーの作成のためのオプションを含む文字列化された JSON。 Docker の作成オプション | いいえ |
| systemModules.edgeAgent.configuration.id | このモジュールをデプロイしたデプロイの ID。 | このプロパティは、マニフェストがデプロイを使用して適用されるときに IoT Hub によって設定されます。 デプロイ マニフェストの一部ではありません。 |
| systemModules.edgeHub.type | docker である必要があります。 | はい |
| systemModules.edgeHub.status | running である必要があります。 | はい |
| systemModules.edgeHub.restartPolicy | always である必要があります。 | はい |
| systemModules.edgeHub.startupOrder | モジュールの起動順序を示す整数値。 0 が最初で、最大の整数 (4294967295) は最後です。 値が指定されていない場合、既定値は最大の整数になります。 | いいえ |
| systemModules.edgeHub.settings.image | IoT Edge ハブのイメージの URI。 | はい |
| systemModules.edgeHub.settings.createOptions | IoT Edge ハブ コンテナーの作成のためのオプションを含む文字列化された JSON。 Docker の作成オプション | いいえ |
| systemModules.edgeHub.configuration.id | このモジュールをデプロイしたデプロイの ID。 | このプロパティは、マニフェストがデプロイを使用して適用されるときに IoT Hub によって設定されます。 デプロイ マニフェストの一部ではありません。 |
| modules.{moduleId}.version | このモジュールのバージョンを表すユーザー定義の文字列。 | はい |
| modules.{moduleId}.type | docker である必要があります。 | はい |
| modules.{moduleId}.status | {running | stopped} | はい |
| modules.{moduleId}.restartPolicy | {never | always} | はい |
| modules.{moduleId}.startupOrder | モジュールの起動場所を示す整数値。 0 が最初で、最大の整数 (4294967295) は最後です。 値が指定されていない場合、既定値は最大の整数になります。 | いいえ |
| modules.{moduleId}.imagePullPolicy | {on-create | never} | いいえ |
| modules.{moduleId}.env | モジュールに渡す環境変数の一覧。 "<name>": {"value": "<value>"} の形式を取ります。 |
いいえ |
| modules.{moduleId}.settings.image | モジュール イメージへの URI。 | はい |
| modules.{moduleId}.settings.createOptions | モジュール コンテナーの作成のためのオプションを含む文字列化された JSON。 Docker の作成オプション | いいえ |
| modules.{moduleId}.configuration.id | このモジュールをデプロイしたデプロイの ID。 | このプロパティは、マニフェストがデプロイを使用して適用されるときに IoT Hub によって設定されます。 デプロイ マニフェストの一部ではありません。 |
| version | バージョン、コミット、ビルドを含む現在のイテレーション。 | いいえ |
edgeAgent の報告されるプロパティ
IoT Edge エージェントの報告されるプロパティには、次の 3 つの主な情報が含まれます。
- 最後に表示された必要なプロパティのアプリケーションの状態
- IoT Edge エージェントによって報告された、現在デバイス上で実行されているモジュールの状態
- 現在デバイス上で実行されている必要なプロパティのコピー。
現在の必要なプロパティのコピーは、デバイスに最新のデプロイが適用されているか、または以前のデプロイ マニフェストが引き続き実行されているかを判断するのに役立ちます。
Note
IoT Edge エージェントの報告されるプロパティは、デプロイの状態を大規模に調査するために IoT Hub クエリ言語でクエリできるため有効です。 状態のために IoT Edge エージェント プロパティを使用する方法の詳細については、1 台または多数のデバイスを対象とした IoT Edge デプロイに関する記事を参照してください。
次の表には、必要なプロパティからコピーされる情報は含まれません。
| プロパティ | 説明 |
|---|---|
| lastDesiredStatus.code | これは、IoT Edge エージェントによって表示された最後の必要なプロパティを参照する状態コードです。 許可される値: 200 成功、400 無効な構成、412 無効なスキーマ バージョン、417 必要なプロパティが空、500 失敗。 |
| lastDesiredStatus.description | 状態を説明するテキスト。 |
| lastDesiredVersion | この整数は、IoT Edge エージェントによって処理された必要なプロパティの最後のバージョンを参照します。 |
| runtime.platform.OS | デバイスで実行されている OS を報告します。 |
| runtime.platform.architecture | デバイス上の CPU のアーキテクチャを報告します。 |
| schemaVersion | 報告されたプロパティのスキーマのバージョン。 |
| systemModules.edgeAgent.runtimeStatus | IoT Edge エージェントの報告された状態: {running | unhealthy}。 |
| systemModules.edgeAgent.statusDescription | IoT Edge エージェントの報告された状態のテキストでの説明。 |
| systemModules.edgeAgent.exitCode | コンテナーが終了した場合に、IoT Edge エージェント コンテナーによって報告された終了コード。 |
| systemModules.edgeAgent.lastStartTimeUtc | IoT Edge エージェントが最後に起動された時間 |
| systemModules.edgeAgent.lastExitTimeUtc | IoT Edge エージェントが最後に終了した時間。 |
| systemModules.edgeHub.runtimeStatus | IoT Edge ハブの状態: { running | stopped | failed | backoff | unhealthy }。 |
| systemModules.edgeHub.statusDescription | 異常な場合の IoT Edge ハブの状態のテキストでの説明。 |
| systemModules.edgeHub.exitCode | コンテナーが終了した場合に、IoT Edge ハブ コンテナーによって報告された終了コード。 |
| systemModules.edgeHub.lastStartTimeUtc | IoT Edge ハブが最後に起動された時刻。 |
| systemModules.edgeHub.lastExitTimeUtc | IoT Edge ハブが最後に終了された時間。 |
| systemModules.edgeHub.lastRestartTimeUtc | IoT Edge ハブが最後に再起動された時刻。 |
| systemModules.edgeHub.restartCount | このモジュールが再起動ポリシーの一部として再起動された回数。 |
| modules.{moduleId}.runtimeStatus | モジュールの状態: { running | stopped | failed | backoff | unhealthy }。 |
| modules.{moduleId}.statusDescription | 異常な場合のモジュールの状態のテキストでの説明。 |
| modules.{moduleId}.exitCode | コンテナーが終了した場合に、モジュール コンテナーによって報告された終了コード。 |
| modules.{moduleId}.lastStartTimeUtc | モジュールが最後に起動された時刻。 |
| modules.{moduleId}.lastExitTimeUtc | モジュールが最後に終了された時間。 |
| modules.{moduleId}.lastRestartTimeUtc | モジュールが最後に再起動された時刻。 |
| modules.{moduleId}.restartCount | このモジュールが再起動ポリシーの一部として再起動された回数。 |
| version | イメージのバージョン。 例: "version": { "version": "1.2.7", "build": "50979330", "commit": "d3ec971caa0af0fc39d2c1f91aef21e95bd0c03c" }。 |
edgeHub の必要なプロパティ
IoT Edge ハブのモジュール ツインは $edgeHub と呼ばれ、デバイス上で実行されている IoT Edge ハブと IoT Hub の間の通信を調整します。 必要なプロパティは、単一デバイスまたは大規模デプロイの一部として特定のデバイスにデプロイ マニフェストを適用するときに設定されます。
| プロパティ | 説明 | デプロイ マニフェストに必要 |
|---|---|---|
| schemaVersion | "1.0" または "1.1" のいずれかです。 バージョン 1.1 は IoT Edge バージョン 1.0.10 で導入されました。こちらが推奨されます。 | はい |
| routes.{routeName} | IoT Edge ハブのルートを表す文字列。 詳細については、「ルートの宣言」を参照してください。 | routes 要素は存在できますが、空です。 |
| storeAndForwardConfiguration.timeToLiveSecs | ルーティング エンドポイント (IoT Hub またはローカル モジュール) から切断された場合に、IoT Edge ハブがメッセージを保持するデバイスの時間 (秒数)。 この時間は、電源をオフにした後または再起動後も保持されます。 詳細については、オフライン機能に関するページを参照してください。 | はい |
edgeHub の報告されるプロパティ
| プロパティ | 説明 |
|---|---|
| lastDesiredVersion | この整数は、IoT Edge ハブによって処理された必要なプロパティの最後のバージョンを参照します。 |
| lastDesiredStatus.code | IoT Edge ハブによって表示された最後の必要なプロパティを参照する状態コード。 許可される値: 200 成功、400 無効な構成、500 失敗 |
| lastDesiredStatus.description | 状態を説明するテキスト。 |
| クライアント | 状態と最後の接続時刻で edgeHub に接続されているすべてのクライアント。 例: "clients": { "device2/SimulatedTemperatureSensor": { "status": "Connected", "lastConnectedTimeUtc": "2022-11-17T21:49:16.4781564Z" } }。 |
| clients.{device or moduleId}.status | このデバイスまたはモジュールの接続状態。 可能性のある値 {connected | disconnected}。 切断された状態になることができるのはモジュール ID だけです。 IoT Edge ハブに接続されるダウンストリーム デバイスは、接続されている場合にのみ表示されます。 |
| clients.{device or moduleId}.lastConnectTime | デバイスまたはモジュールが接続された最後の時間。 |
| clients.{device or moduleId}.lastDisconnectTime | デバイスまたはモジュールが切断された最後の時間。 |
| schemaVersion | 報告されたプロパティのスキーマのバージョン。 |
| version | イメージのバージョン。 例: "version": { "version": "1.2.7", "build": "50979330", "commit": "d3ec971caa0af0fc39d2c1f91aef21e95bd0c03c" }。 |
次のステップ
これらのプロパティを使って配置マニフェストを作成する方法については、「IoT Edge モジュールをどのように使用、構成、および再利用できるかを理解する」をご覧ください。