IoT 中樞和 IoT 隨插即用的裝置更新

發行項
05/29/2024

IoT 中樞的裝置更新使用 IoT 隨插即用探索及管理支援無線更新的裝置。裝置更新服務會使用 IoT 隨插即用介面，從裝置傳送和接收屬性和訊息。

如需詳細資訊，請參閱：

了解 IoT 隨插即用裝置用戶端。
查看如何實作裝置更新代理程式。

裝置更新模型

模型識別碼是智慧型裝置使用 IoT 隨插即用向 Azure IoT 應用程式宣告其功能的方式。若要深入了解如何建置智慧型裝置以向 Azure IoT 應用程式宣告其功能，請造訪 IoT 隨插即用裝置開發人員指南。

IoT 中樞裝置更新需要使用 IoT 隨插即用智慧型裝置，宣告模型識別碼為裝置連線的一部分。了解如何宣告模型識別碼。

裝置更新已定義 2 個 PnP 模型，這些模型皆支援 DU 功能。裝置更新模型 'dtmi:azure:iot:deviceUpdateContractModel;2' 支援核心功能，使用裝置更新核心介面將更新動作和中繼資料傳送至裝置，並從裝置接收更新狀態。

另一個支援的模型是 dtmi:azure:iot:deviceUpdateModel;2，可擴充 deviceUpdateContractModel;2，也使用其他 PnP 介面傳送裝置屬性和資訊並啟用診斷功能。深入了解 [裝置更新模型和介面版本] (https://github.com/Azure/iot-plugandplay-models/tree/main/dtmi/azure/iot)。

裝置更新代理程式使用 dtmi:azure:iot:deviceUpdateModel;2，其支援 1.0.0 版中的所有最新功能。此模型支援 V5 資訊清單版本。

代理程式中繼資料

裝置更新代理程式會使用代理程式中繼資料欄位，將資訊傳送至裝置更新服務。

名稱	結構描述	方向	描述	範例
deviceProperties	地圖	裝置到雲端	包含製造商、型號和其他裝置資訊的屬性集和。	如需詳細資訊請參閱裝置屬性一節。
compatPropertyNames	字串 (逗號分隔)	裝置到雲端	裝置回報的屬性，用來檢查裝置的相容性，以瞄準更新部署。限制為五個裝置屬性。	"compatPropertyNames": "manufacturer,model"
lastInstallResult	地圖	裝置到雲端	代理程式報告的結果。其中包含主要更新和其他步驟更新的結果碼、擴充結果碼以及結果詳細資料。
resultCode	整數	裝置到雲端	包含上次更新動作結果相關資訊的程式碼。成功或失敗皆可填入。	700
extendedResultCode	整數	裝置到雲端	包含有關結果其他資訊的程式碼。成功或失敗皆可填入。	0x80004005
resultDetails	string	裝置到雲端	客戶定義的自由格式字串，提供其他結果詳細資料。傳回至對應項而不剖析
stepResults	map	裝置到雲端	代理程式報告的結果，其中包含結果碼、擴充結果碼，以及步驟更新結果的詳細資料。	"step_1": { "resultCode": 0,"extendedResultCode": 0, "resultDetails": ""}
state	整數	裝置到雲端	表示裝置更新代理程式目前狀態的整數。	如需詳細資訊，請參閱狀態一節。
工作流程	complex	裝置到雲端	一組值，顯示代理程式目前正在處理的部署、目前部署的識別碼，以及從服務傳送至代理程式的任何重試要求通知。請注意，工作流程識別碼會在取消部署後報告「nodeployment」值。	"workflow": {"action": 3,"ID": "11b6a7c3-6956-4b33-b5a9-87fdd79d2f01","retryTimestamp": "2022-01-26T11:33:29.9680598Z"}
installedUpdateId	string	裝置到雲端	目前安裝之更新的識別碼 (透過裝置更新)。這個值是一個字串，會擷取從未透過裝置更新取得更新裝置的更新識別碼 JSON 或 Null。	installedUpdateID{"provider":"contoso","name":"image-update","version":"1.0.0"}"

裝置屬性

deviceProperties 欄位包含裝置的製造商和型號資訊。

名稱	結構描述	方向	描述
製造商	string	裝置到雲端	裝置的裝置製造商，透過 `deviceProperties` 回報。此屬性是從兩個位置的其中一個讀取 - 首先，DeviceUpdateCore 介面會嘗試從組態檔讀取 'aduc_manufacturer' 值。如果值未填入組態檔，則預設會報告 ADUC_DEVICEPROPERTIES_MANUFACTURER 的編譯時間定義。此屬性僅於開機時間報告。預設值：'Contoso'。
機型	string	裝置到雲端	裝置的裝置型號，透過 `deviceProperties` 回報。此屬性是從兩個位置的其中一個讀取 - 首先，DeviceUpdateCore 介面會嘗試從組態檔讀取 'aduc_model' 值。如果值未填入組態檔，則預設會報告 ADUC_DEVICEPROPERTIES_MODEL 的編譯時間定義。此屬性僅於開機時間報告。預設值為：'Video'
contractModelId	string	裝置到雲端	服務會使用這個屬性來識別裝置更新代理程式用來管理及與代理程式通訊的基底模型版本。值：'dtmi:azure:iot:deviceUpdateContractModel;2' 適用於使用 DU 代理程式 1.0.0 版的裝置。注意：使用 'dtmi:azure:iot:deviceUpdateModel;2' 的代理程式必須將 contractModelId 回報為 'dtmi:azure:iot:deviceUpdateContractModel;2'，因為 deviceUpdateModel;2 是由 deviceUpdateModel;2 擴充而來
aduVer	string	裝置到雲端	裝置上執行的裝置更新代理程式版本。只有在編譯時間將 ENABLE_ADU_TELEMETRY_REPORTING 設為 1 (true) 時，才會從編譯讀取此值。客戶可以將值設定為 0 (false)，選擇退出宣告版本報告。如何自訂裝置更新代理程式屬性。
doVer	string	裝置到雲端	在裝置上執行的傳遞最佳化代理程式版本。只有在編譯時間將 ENABLE_ADU_TELEMETRY_REPORTING 設為 1 (true) 時，才會從編譯讀取值。客戶可以將值設定為 0 (false)，選擇退出宣告該版本報告。如何自訂傳遞最佳化代理程式屬性。
自訂相容性屬性	使用者定義	裝置到雲端	實作者可以在瞄準更新部署時，定義其他裝置屬性，以用於相容性檢查。

IoT 中樞裝置對應項範例：

"deviceUpdate": {
                "__t": "c",
                "agent": {
                    "deviceProperties": {
                        "manufacturer": "contoso",
                        "model": "virtual-vacuum-v1",
                        "contractModelId": "dtmi:azure:iot:deviceUpdateContractModel;2",
                        "aduVer": "DU;agent/0.8.0-rc1-public-preview",
                        "doVer": "DU;lib/v0.6.0+20211001.174458.c8c4051,DU;agent/v0.6.0+20211001.174418.c8c4051"
                    },
                    "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\"}"
                },

注意

裝置或模組必須新增 {"__t": "c"} 標記，以指出參考元件的元素。如需詳細資訊，請參閱 IoT 隨插即用慣例。

州/省

[狀態] 欄位是從裝置更新服務收到動作之後，裝置更新 (DU) 代理程式所報告的狀態。狀態會以回應動作進行報告 (請參閱動作一節了解詳細內容)，從裝置更新服務傳送至裝置更新代理程式。如需流動於裝置更新服務與裝置更新代理程式之間要求的詳細資訊，請參閱概覽工作流程。

名稱	數值	Description
閒置	0	裝置已準備好從裝置更新服務接收動作。成功更新後，狀態會回到 `Idle` 狀態。
DeploymentInprogress	6	正在進行部署。
失敗	255	更新期間發生失敗。
DownloadSucceeded	2	成功下載。此狀態只會由代理程式版本 0.7.0 或更舊版本的裝置進行報告。
InstallSucceeded	4	安裝成功。此狀態只會由代理程式版本 0.7.0 或更舊版本的裝置進行報告。

服務中繼資料

服務中繼資料包含裝置更新服務用來將動作和資料傳達給裝置更新代理程式的欄位。

名稱	結構描述	方向	描述
action	整數	雲端到裝置	對應至代理程式應執行之動作的整數。如需詳細資訊，請參閱動作一節。
updateManifest	string	雲端到裝置	用來描述更新的內容。已從匯入資訊清單產生。
updateManifestSignature	JSON 物件	雲端到裝置	JSON Web 簽章 (JWS) 的 JSON Web 金鑰可用來驗證來源。
fileUrls	地圖	雲端到裝置	`FileID` 和 `DownloadUrl` 的地圖。告知代理程式要下載哪些檔案，以及用來驗證檔案是否已正確下載的雜湊。

動作

動作欄位代表裝置更新代理程式依照裝置更新服務指示所採取的動作。裝置更新代理程式會報告處理接收動作的狀態。如需流動於裝置更新服務與裝置更新代理程式之間要求的詳細資訊，請參閱概覽工作流程。

名稱	數值	Description
applyDeployment	3	套用更新。會向裝置發出套用已部署更新的訊號
cancel	255	停止處理目前的動作並返回 `Idle`，或告訴處於 `Failed` 狀態的代理程式返回 `Idle`。
下載	0	下載已發佈的內容或更新，以及任何所需的其他內容。此動作只會傳送至代理程式版本 0.7.0 或更舊版本的裝置。
安裝	1	安裝內容或更新。此動作通常表示針對內容或更新呼叫安裝程式。此動作只會傳送至代理程式版本 0.7.0 或更舊版本的裝置。
套用	2	完成更新。視需要向系統發出重新開機訊號。此動作只會傳送至代理程式版本 0.7.0 或更舊版本的裝置。

裝置資訊介面

裝置資訊介面是 IoT 隨插即用架構中使用的概念。包含裝置到雲端屬性，可提供裝置硬體和作業系統的相關資訊。 IoT 中樞裝置更新會使用遙測和診斷的 DeviceInformation.manufacturer 和 DeviceInformation.model 屬性。若要深入了解，請參閱裝置資訊介面的範例。

實作此介面時，模型中的預期元件名稱是 deviceInformation。深入了解 Azure IoT 隨插即用元件

名稱	類型	結構描述	方向	描述	範例
製造商	屬性	string	裝置到雲端	裝置製造商的公司名稱。此屬性可能與原始設備製造商 (OEM) 的名稱相同。	Contoso
機型	屬性	string	裝置到雲端	裝置型號名稱或識別碼。	IoT Edge 裝置
swVersion	屬性	string	裝置到雲端	裝置上的軟體版本。 swVersion 可能是韌體的版本。	4.15.0-122
osName	屬性	string	裝置到雲端	裝置的作業系統名稱。	Ubuntu Server 18.04
processorArchitecture	屬性	string	裝置到雲端	裝置上處理器的架構。	ARM64
processorManufacturer	屬性	string	裝置到雲端	裝置上處理器製造商的名稱。	Microsoft
totalStorage	屬性	string	裝置到雲端	裝置上可用的儲存體總量，以 KB 為單位。	2048
totalMemory	屬性	string	裝置到雲端	裝置上可用的記憶體總量，以 KB 為單位。	256

共用方式為

IoT 中樞和 IoT 隨插即用的裝置更新

裝置更新模型

代理程式中繼資料

裝置屬性

州/省

服務中繼資料

動作

裝置資訊介面

後續步驟

意見反應

其他資源