適用於 IoT 中樞 的 Azure 裝置更新中的 IoT 隨插即用
IoT 中樞的裝置更新使用 IoT 隨插即用探索及管理支援無線更新的裝置。 本文說明裝置更新服務如何使用 IoT 隨插即用 介面，來回傳送和接收裝置的屬性和訊息。
如需詳細資訊，請參閱 IoT 隨插即用 裝置開發人員指南和如何建置裝置更新代理程式。
裝置更新模型
智慧型手機裝置會使用 IoT 隨插即用 模型標識碼，將其功能公告給 Azure IoT 應用程式。 裝置更新需要 IoT 隨插即用 智慧型手機裝置，才能在裝置連線時宣告型號標識碼。 如需詳細資訊，請參閱 模型標識符公告。
裝置更新有數個定義的 IoT 隨插即用 模型，可支援裝置更新功能。 裝置更新模型 **dtmi:azure:iot:deviceUpdateContractModel;3** 支援核心裝置更新功能，並使用裝置更新核心介面將更新動作和元數據傳送至裝置，並從裝置接收更新狀態。
另一個支援的模型是 **dtmi:azure:iot:deviceUpdateModel;3**，它會擴充**deviceUpdateContractModel;3**並使用 IoT 隨插即用 介面來傳送裝置屬性資訊並啟用診斷功能。 如需這些和其他版本，請參閱 Azure IoT 隨插即用 裝置更新模型。
Device Update 代理程式會使用 **dtmi:azure:iot:deviceUpdateModel;3** ，其支援 Device Update 1.1.0 版本中的所有最新功能。 此模型支持 匯入指令清單 5.0 版。 舊版指令清單可與最新的代理程式搭配使用，但新功能需要最新的指令清單版本。
代理程式中繼資料
裝置更新代理程式會使用下列代理程式元數據欄位，將資訊傳送至裝置更新服務。
| 名稱 | 結構描述 | 方向 | 描述 |
|---|---|---|---|
| deviceProperties | 地圖 | 裝置到雲端 | 包含製造商、型號和其他裝置資訊的屬性集和。 如需詳細資訊，請參閱 裝置屬性 。 |
| compatPropertyNames | 字串 (逗號分隔) | 裝置到雲端 | 最多五個用來檢查裝置相容性的屬性，以將更新部署設為目標。 範例：“compatPropertyNames”： “manufacturer，model” |
| lastInstallResult | 地圖 | 裝置到雲端 | 代理程式所報告的結果，包含結果碼、擴充的結果碼，以及主要更新和其他步驟更新的結果詳細數據。 |
| resultCode | 整數 | 裝置到雲端 | 包含上次更新動作結果相關資訊的程式碼。 成功或失敗皆可填入。 範例：700 |
| extendedResultCode | 整數 | 裝置到雲端 | 包含結果詳細資訊的程序代碼。 成功或失敗皆可填入。 範例：0x80004005 |
| resultDetails | string | 裝置到雲端 | 使用者提供的手繪多邊形字串，可提供更多結果詳細數據。 傳回至對應項而不剖析。 |
| stepResults | map | 裝置到雲端 | 代理程式所報告的結果，包含結果碼、擴充的結果碼，以及步驟更新的結果詳細數據。 範例：“step_1”： { “resultCode”： 0，“extendedResultCode”： 0， “resultDetails”： “”} |
| state | 整數 | 裝置到雲端 | 表示裝置更新代理程式目前狀態的整數。 如需詳細資訊，請參閱 狀態 。 |
| 工作流程 | complex | 裝置到雲端 | 一組值，指出代理程式目前正在執行的部署、目前安裝的部署標識碼，以及認可從服務傳送至代理程式的任何重試要求。 標識碼 workflow 會在 "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\“}” |
IoT 中樞裝置對應項範例：
"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\"}"
},
注意
裝置或模組必須新增 {"__t": "c"} 標記，以指出參考元件的元素。 如需詳細資訊，請參閱 IoT 隨插即用慣例。
裝置屬性
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;3 針對使用裝置更新代理程式 1.1.0 版的裝置。 注意： 使用 dtmi:azure:iot:deviceUpdateModel;2 的代理程式必須將 回報 contractModelId 為 dtmi:azure:iot:deviceUpdateContractModel;3，因為 deviceUpdateModel;3 是從 deviceUpdateContractModel;3延伸。 |
| aduVer | string | 裝置到雲端 | 裝置上執行的裝置更新代理程式版本。 只有在 ENABLE_ADU_TELEMETRY_REPORTING 編譯期間設定為 1 （true） 時，才會從組建讀取此值。 您可以選擇退出宣告版本報告，方法是將值設定為 0 [false]。 如需詳細資訊，請參閱 如何建置裝置更新代理程式。 |
| doVer | string | 裝置到雲端 | 在裝置上執行的傳遞最佳化代理程式版本。 只有在 ENABLE_ADU_TELEMETRY_REPORTING 編譯期間設定為 1 （true） 時，才會從組建讀取值。 您可以選擇退出宣告版本報告，方法是將值設定為 0 [false]。 如需詳細資訊，請參閱 如何自定義傳遞優化代理程序屬性。 |
| 自定義相容性屬性 | 使用者定義 | 裝置到雲端 | 以更新部署為目標時，要用於相容性檢查的其他使用者定義裝置屬性。 |
州/省
狀態欄位是裝置更新代理程式回報的狀態，以回應從裝置更新服務傳送至裝置更新代理程式的動作。 如需裝置更新服務和裝置更新代理程式之間流動之要求的詳細資訊，請參閱 代理程式工作流程。
| 名稱 | 數值 | Description |
|---|---|---|
| 閒置 | 0 | 裝置已準備好從裝置更新服務接收動作。 成功更新之後，狀態會回到 Idle 狀態。 |
| DeploymentInprogress | 6 | 正在進行部署。 |
| 失敗 | 255 | 更新期間發生失敗。 |
| DownloadSucceeded | 2 | 發生成功的下載。 只有代理程式 0.7.0 版或更新版本的裝置會回報此狀態。 |
| InstallSucceeded | 4 | 發生成功的安裝。 只有代理程式 0.7.0 版或更新版本的裝置會回報此狀態。 |
動作
動作欄位代表裝置更新代理程式應依照裝置更新服務指示採取的動作。 裝置更新代理程式會報告 處理其接收動作的狀態 。 如需裝置更新服務和裝置更新代理程式之間流動之要求的詳細資訊，請參閱 代理程式工作流程。
| 名稱 | 數值 | Description |
|---|---|---|
| applyDeployment | 3 | 套用已部署的更新。 |
| cancel | 255 | 停止處理目前的動作並返回 Idle，或告訴處於 Failed 狀態的代理程式返回 Idle。 |
| 下載 | 0 | 下載已發佈的內容或更新，以及所需的任何其他內容。 此動作只會傳送至代理程式0.7.0版或更新版本的裝置。 |
| 安裝 | 1 | 安裝內容或更新，通常是呼叫內容或更新的安裝程式。 裝置更新只會將此動作傳送給代理程式版本 0.7.0 或更新版本的裝置。 |
| 套用 | 2 | 視需要重新啟動以完成更新。 裝置更新只會將此動作傳送給代理程式版本 0.7.0 或更新版本的裝置。 |
服務中繼資料
服務元數據包含裝置更新服務用來將動作和數據傳達給裝置更新代理程式的欄位。
| 名稱 | 結構描述 | 方向 | 描述 |
|---|---|---|---|
| action | 整數 | 雲端到裝置 | 對應至代理程式應執行之動作的整數。 如需詳細資訊，請參閱 動作 。 |
| updateManifest | string | 雲端到裝置 | 描述更新的內容。 已從匯入資訊清單產生。 |
| updateManifestSignature | JSON 物件 | 雲端到裝置 | JSON Web 簽章 （JWS） 與要用於來源驗證的 JSON Web 金鑰。 |
| fileUrls | 地圖 | 雲端到裝置 |
FileID 和 DownloadUrl 的地圖。 告知代理程式要下載哪些檔案，以及用來確認檔案已正確下載的哈希。 |
裝置資訊介面
裝置資訊介面是 IoT 隨插即用架構中使用的概念。 介面包含裝置到雲端屬性，可提供裝置硬體和作系統的相關信息。 裝置更新會使用 DeviceInformation.manufacturer 和 DeviceInformation.model 屬性進行遙測和診斷。 如需裝置資訊介面的範例，請參閱 https://devicemodels.azure.com/dtmi/azure/devicemanagement/deviceinformation-1.json。
當您實作這個介面時，模型中的預期元件名稱是 deviceInformation。 如需詳細資訊，請參閱 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 |