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 運行時間的兩個模組。 如需每個運行時間模組責任的詳細資訊，請參閱 瞭解 Azure IoT Edge 運行時間及其架構。
本文提供運行時間模組對應項所需的屬性和報告屬性。 如需如何在IoT Edge裝置上部署模組的詳細資訊，請參閱 瞭解如何在IoT Edge中部署模組和建立路由。
模組對應項包括：
預期屬性。 解決方案後端可以設定所需屬性，模組可加以讀取。 模組也可以收到所需屬性變更的通知。 預期屬性會搭配回報的屬性使用，以便同步處理模組的設定或條件。
回報的屬性。 模組可以設定報告的屬性，解決方案後端可加以讀取並查詢。 報告的屬性會搭配所需屬性使用，以同步模組設定或條件。
EdgeAgent 預期屬性
IoT Edge 代理程式的模組對應項稱為 $edgeAgent，且可協調在裝置上執行的 IoT Edge 代理程式和 IoT 中樞之間的通訊。 在特定裝置上套用部署資訊清單以成為單一裝置或大規模部署的一部分時，即會設定預期屬性。
| 屬性 | 描述 | 必要 |
|---|---|---|
| imagePullPolicy | 何時在 OnCreate 或 Never 中提取映像（如果映射已在裝置上，則永遠無法使用） | Yes |
| restartPolicy | 應該重新啟動模組時。 可能的值為：永不：若未執行，請勿重新啟動模組，一律：一律重新啟動模組，如果未執行，則為 On-Unhealthy：如果狀況不良，請重新啟動模組。 狀況不良是 Docker 根據健康情況檢查所報告的內容，例如「狀況不良 - 容器無法正常運作」、 On-Failed：如果失敗，請重新啟動。 | Yes |
| runtime.type | 必須是 docker。 | Yes |
| runtime.settings.minDockerVersion | 設定為此部署資訊清單所需的最小 Docker 版本。 | Yes |
| runtime.settings.loggingOptions | 包含適用於 IoT Edge 代理程式容器之記錄選項的字串化 JSON。 Docker 記錄選項 | No |
| runtime.settings.registryCredentials。{registryId}.username | 容器登錄的使用者名稱。 針對 Azure Container Registry，使用者名稱通常是登錄名稱。 任何私人模組映像都需要登錄認證。 | No |
| runtime.settings.registryCredentials。{registryId}.password | 容器登錄的密碼。 | No |
| runtime.settings.registryCredentials。{registryId}.address | 容器登錄的位址。 針對 Azure Container Registry，位址通常是 {registry name}.azurecr.io。 | No |
| schemaVersion | 1.0 或 1.1。 1.1 版隨 IoT Edge 1.0.10 版推出，建議使用。 | Yes |
| status | 模組的所需狀態： 執行 中或 已停止。 | 必要 |
| systemModules.edgeAgent.type | 必須是 docker。 | Yes |
| systemModules.edgeAgent.startupOrder | 模組在啟動順序中的位置整數值。 0 是第一個，最大整數 （4294967295） 是最後一個。 如果未提供值，則預設值為 最大整數。 | No |
| systemModules.edgeAgent.settings.image | IoT Edge 代理程式映像的 URI。 目前，IoT Edge 代理程式無法自行更新。 | Yes |
| systemModules.edgeAgent.settings.createOptions | 包含適用於建立 IoT Edge 代理程式容器之選項的字串化 JSON。 Docker 建立選項 | No |
| systemModules.edgeAgent.configuration.id | 部署此模組的部署識別碼。 | IoT 中樞會在使用部署套用資訊清單時設定此屬性。 並非部署資訊清單的一部分。 |
| systemModules.edgeHub.type | 必須是 docker。 | Yes |
| systemModules.edgeHub.status | 必須 執行。 | Yes |
| systemModules.edgeHub.restartPolicy | 必須 永遠。 | Yes |
| systemModules.edgeHub.startupOrder | 整數值，會在啟動順序中找出模組。 0 是第一個，最大整數 （4294967295） 是最後一個。 如果未提供值，則預設值為 最大整數。 | No |
| systemModules.edgeHub.settings.image | IoT Edge 中樞映像的 URI。 | Yes |
| systemModules.edgeHub.settings.createOptions | 包含適用於建立 IoT Edge 中樞容器之選項的字串化 JSON。 Docker 建立選項 | No |
| systemModules.edgeHub.configuration.id | 部署此模組的部署識別碼。 | IoT 中樞會在使用部署套用資訊清單時設定此屬性。 並非部署資訊清單的一部分。 |
| modules.{moduleId}.version | 代表此模組版本的使用者定義字串。 | Yes |
| modules.{moduleId}.type | 必須是 docker。 | Yes |
| modules.{moduleId}.status | {執行 | 已停止} | Yes |
| modules.{moduleId}.restartPolicy | {永遠不 | 一定} | Yes |
| modules.{moduleId}.startupOrder | 模組在啟動順序中的位置整數值。 0 是第一個，最大整數 （4294967295） 是最後一個。 如果未提供值，則預設值為 最大整數。 | No |
| modules.{moduleId}.imagePullPolicy | {on-create | never} | No |
| 模組。{moduleId}.env | 要傳遞至模組的環境變數清單。 採用格式 "<name>": {"value": "<value>"}。 |
No |
| modules.{moduleId}.settings.image | 模組映像的 URI。 | Yes |
| modules.{moduleId}.settings.createOptions | 包含適用於建立模組容器之選項的字串化 JSON。 Docker 建立選項 | No |
| modules.{moduleId}.configuration.id | 部署此模組的部署識別碼。 | IoT 中樞會在使用部署套用資訊清單時設定此屬性。 並非部署資訊清單的一部分。 |
| version | 目前具有版本、認可和建置的反覆專案。 | No |
EdgeAgent 回報的屬性
IoT Edge 代理程式回報的屬性包括資訊的三個主要部分：
- 最後看到之預期屬性的應用程式狀態；
- 目前在裝置上執行的模組狀態，如同 IoT Edge 代理程式所回報；以及
- 目前在裝置上執行之預期屬性的複本。
目前所需屬性的複本有助於判斷裝置是否已套用最新的部署，或仍在執行先前的部署指令清單。
注意
IoT Edge 代理程式的回報屬性很有用，因為可以使用 IoT 中樞 查詢語言來查詢，以大規模調查部署的狀態。 如需如何使用IoT Edge代理程式屬性狀態的詳細資訊，請參閱 瞭解單一裝置或大規模IoT Edge部署。
下表不包括從預期屬性複製的資訊。
| 屬性 | 說明 |
|---|---|
| lastDesiredStatus.code | 此狀態代碼代表 IoT Edge 代理程式上次看到的所需屬性。 允許的值： 200 成功、 400 無效的組態、 412 無效的架構版本、 417 Desired 屬性是空的、 500 失敗的。 |
| lastDesiredStatus.description | 狀態的文字說明。 |
| lastDesiredVersion | 此整數是指 IoT Edge 代理程式所處理之預期屬性的最新版本。 |
| runtime.platform.OS | 報告在裝置上執行的作業系統。 |
| runtime.platform.architecture | 報告裝置上的 CPU 結構。 |
| schemaVersion | 報告屬性的架構版本。 |
| systemModules.edgeAgent.runtimeStatus | IoT Edge 代理程序的回報狀態： {執行 | 狀況不良}。 |
| 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 中樞的狀態：{ 執行 | 停止的 | 容錯 | 回復 | 狀況不良 }。 |
| 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 | 模組的狀態：{ 執行 | 中已停止 | 的容錯 | 回復 | 狀況不良 }。 |
| modules.{moduleId}.statusDescription | 如果狀況不良，則為模組狀態的文字描述。 |
| modules.{moduleId}.exitCode | 如果容器結束時，模組容器所報告的結束代碼。 |
| 模組。{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 中樞之間的通訊。 在特定裝置上套用部署資訊清單以成為單一裝置或大規模部署的一部分時，即會設定預期屬性。
| 屬性 | 說明 | 部署資訊清單中的必要項 |
|---|---|---|
| schemaVersion | 1.0 或 1.1。 1.1 版隨 IoT Edge 1.0.10 版推出，建議使用。 | Yes |
| routes.{routeName} | 代表 IoT Edge 中樞路由的字串。 如需詳細資訊，請參閱 宣告路由。 | 元素 routes 可以存在，但空白。 |
| storeAndForwardConfiguration.timeToLiveSecs | 如果與路由端點中斷連線，IoT Edge 中樞會在 IoT 中樞 或本機模組時，以秒為單位來保留訊息。 這次會在任何關閉電源或重新啟動時持續存在。 如需詳細資訊，請參閱 離線功能。 | Yes |
EdgeHub 回報的屬性
| 屬性 | 說明 |
|---|---|
| lastDesiredVersion | 此整數是指 IoT Edge 中樞所處理之預期屬性的最新版本。 |
| lastDesiredStatus.code | 此狀態代碼代表 IoT Edge 中樞上次看到的所需屬性。 允許的值： 200 成功、 400 無效的設定、 500 失敗 |
| lastDesiredStatus.description | 狀態的文字說明。 |
| 用戶端 | 所有連線到edgeHub的用戶端，其狀態和上次連線時間。 範例：“clients”： { “device2/SimulatedTemperatureSensor”： { “status”： “連線 ed”， “last 連線 edTimeUtc”： “2022-11-17T21：49：16.4781564Z” } }。 |
| clients.{device or moduleId}.status | 此裝置或模組的連線狀態。 可能的值 {已 | 中斷連線}。 只有模組身分識別可以處於中斷連線的狀態。 連線到 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模組。