差異更新（預覽）

發行項
02/25/2025

差異更新可讓您產生小型更新，只代表兩個完整更新、來源映像和目標映像之間的變更。這種方法很適合用來將更新下載到裝置的頻寬降低，特別是來源和目標更新之間只有一些變更時。

注意

IoT 中樞 Azure 裝置更新中的差異更新功能目前處於公開預覽狀態。

在 IoT 中樞裝置更新中使用 delta 更新的需求

來源和目標更新檔案必須是 SWUpdate （SWU）格式。
在每個 SWUpdate 檔案內，都必須有使用 Ext2、Ext3 或 Ext4 檔案系統的原始映像。

差異產生程式會使用 gzip 壓縮來重新壓縮目標 SWU 更新，以產生最佳的差異。您會將重新壓縮的目標 SWU 更新匯入到裝置更新服務，以及產生的差異更新檔案。

差異處理器元件的裝置更新代理程序設定

若要從裝置更新服務下載並安裝差異更新，您的裝置需要裝置更新代理程式，並顯示並設定更新處理程式和差異處理器元件。

裝置更新代理程式

裝置更新代理程式會「協調」裝置上的更新程序，包括下載、安裝及重新開機動作。若要將裝置更新代理程式新增至裝置並加以設定以供使用，請參閱裝置更新代理程式布建。請使用代理程式 1.0 或更新版本。

更新處理常式

更新處理常式會與裝置更新代理程式整合，以執行實際的更新安裝。對於 delta 更新，如果您還沒有想要修改的 SWUpdate 更新處理常式，請從 microsoft/swupdate:2 更新處理常式開始。

差異處理器

Azure/iot-hub-device-update-delta 的差異處理器會在下載差異檔案之後，在您的裝置上重新建立原始 SWU 映射檔，因此您的更新處理程式可以安裝 SWU 檔案。若要將差異處理器元件新增至您的裝置映像並加以設定以供使用，您可以從下載適用於Ubuntu20.04和更新版本的 https://github.com/Azure/iot-hub-device-update-delta/tree/main/preview/2.0.0Debian套件。

如果您使用另一個散發版本，請遵循 README.md 指示，改用 CMAKE 從來源建置差異處理器。從該處，將共用物件複製到 /usr/lib 目錄，直接安裝共用物件 libadudiffapi.so，如下所示：

sudo cp <path to libadudiffapi.so> /usr/lib/libadudiffapi.so
sudo ldconfig

將來源 SWU 映像檔新增至您的裝置

在差異更新檔案下載到裝置之後，它會與先前在裝置上快取的有效 <source_archive> 檔案進行比較。此程式可讓差異更新重新建立完整的目標映像。

填入此快取映像的最簡單方式是透過裝置更新服務匯入和部署完整的映像更新至裝置。如果裝置已使用裝置更新代理程式 1.0 版或更新版本和差異處理器進行設定，代理程式會自動快取已安裝的 SWU 檔案，以供後續的差異更新使用。

如果您要改為直接預先填入裝置上的來源映像，則預期影像的路徑為 <BASE_SOURCE_DOWNLOAD_CACHE_PATH>/sha256-<ENCODED HASH>。根據預設，<BASE_SOURCE_DOWNLOAD_CACHE_PATH>是 /var/lib/adu/sdc/<provider> 的路徑。此值provider是provider來源 SWU 檔案 updateId 的一部分。

ENCODED_HASH 是二進位 SHA256 的 base64 十六進位字串，但在編碼為 base64 十六進位字串之後，它對字元的編碼如下所示：

+ 編碼為 octets _2B
/ 編碼為 octets _2F
= 編碼為 octets _3D

使用 DiffGen 工具產生差異更新

您可以使用 Diff Generation （DiffGen）工具來建立差異更新。

環境必要條件

使用 DiffGen 建立差異之前，您必須在環境機器上下載並安裝數個專案。在理想情況下，請使用Ubuntu 20.04 Linux環境，或是在 Windows 上 Windows 子系統 Linux 版。

下表顯示所需的內容、取得位置，並視需要建議安裝。

二進位檔名稱	取得位置	安裝方式
DiffGen	Azure/iot-hub-device-update-delta GitHub 存放庫	下載符合計算機上OS或散發版本的版本，以用來產生差異更新。
.NETCore 運行時間，版本 8.0.0	透過終端機或套件管理員	在 Linux 上安裝 .NET。只需要運行時間。

使用 DiffGen 建立差異更新

DiffGen 工具會使用下列必要自變數和語法執行：

DiffGenTool <source_archive> <target_archive> <output_path> <log_folder> <working_folder> <recompressed_target_archive>

這個指令會 執行recompress_tool.py 文稿，以建立 <recompressed_target_file>。 DiffGen 接著會使用 <recompressed_target_file>而非 <target_archive> 作為目標檔案來建立差異。中的 <recompressed_target_archive> 圖像檔會使用 gzip 壓縮。

如果您的 SWU 檔案已簽署，它們也需要 <signing_command> DiffGen 命令中的自變數：

DiffGenTool <source_archive> <target_archive> <output_path> <log_folder> <working_folder> <recompressed_target_archive> "<signing_command>"

具有簽署命令字串參數的 DiffGenTool 會執行recompress_and_sign_tool.py 腳本。此文稿會 <recompressed_target_file>建立。此外，此腳本也會簽署 封存內的 sw-description 檔案，以建立 sw-description.sig 檔案。

您可以使用 Azure/iot-hub-device-update-delta GitHub 存放庫的範例sign_file.sh腳本，在輸入來源檔案與重新壓縮和重新簽署的目標檔案之間建立差異。開啟文稿，加以編輯以將路徑新增至私鑰檔案，並加以儲存。如需範例使用方式，請參閱範例一節。

下表將詳細說明引數：

Argument	描述
`<source_archive>`	DiffGen 用來作為建立差異的起點基底映像。重要事項：此映像必須與裝置上已存在的映像相同，例如從先前更新快取。
`<target_archive>`	差異更新裝置的映像。
`<output_path>`	建立之後要放置差異檔案之主計算機上的路徑，包括所產生差異檔案的所需名稱。如果路徑不存在，工具會加以建立。
`<log_folder>`	要建立記錄之主電腦上的路徑。最好將此位置定義為輸出路徑的子資料夾。如果路徑不存在，工具會加以建立。
`<working_folder>`	在差異產生期間，機器上放置附隨品和其他工作檔案的路徑。最好將此位置定義為輸出路徑的子資料夾。如果路徑不存在，工具會加以建立。
`<recompressed_target_archive>`	要建立 `<recompressed_target_file>` 之主電腦上的路徑。 `<recompressed_target_file>`會使用，而不是 `<target_archive>` 做為差異產生的目標檔案。如果此路徑存在於呼叫 DiffGen 工具之前，就會遭到覆寫。最好是在輸出路徑的子資料夾中定義這個檔案。
`"<signing_command>"` (選擇性)	自定義命令，用於簽署中的 `<recompressed_target_archive>`sw-description 檔案。重新壓縮封存中的 sw-description 檔案會當做簽署命令的輸入參數使用。 DiffGen 預期簽署命令會使用附加 .sig 的輸入名稱來建立新的簽章檔案。您必須以雙引弧括住參數，以單一參數的形式傳入整個命令。也請避免在用於簽署的密鑰路徑中使用 `~` 字元，並改用完整的主路徑。例如，使用 /home/USER/keys/priv.pem ，而不是 ~/keys/priv.pem。

DiffGen 範例

下列範例會從 Windows 子系統 Linux 版中的 /mnt/o/temp 目錄運作。

下列程式代碼會在輸入來源檔案與重新壓縮的目標檔案之間建立差異：

sudo ./DiffGenTool  
/mnt/o/temp/<source file>.swu
/mnt/o/temp/<target file>.swu
/mnt/o/temp/<delta file to create>
/mnt/o/temp/logs
/mnt/o/temp/working
/mnt/o/temp/<recompressed target file to create>.swu

如果您也使用簽署參數，則必須在 SWU 檔案簽署時使用先前所述的範例 sign_file.sh 腳本。開啟腳本，加以編輯以將路徑新增至私鑰檔案、儲存腳本，然後執行 DiffGen，如下所示。

下列程式代碼會在輸入來源檔案與重新壓縮和重新簽署的目標檔案之間建立差異：

sudo ./DiffGenTool  
/mnt/o/temp/<source file>.swu
/mnt/o/temp/<target file>.swu   
/mnt/o/temp/<delta file to create>  
/mnt/o/temp/logs  
/mnt/o/temp/working  
/mnt/o/temp/<recompressed target file to create>.swu  
/mnt/o/temp/<path to script>/<sign_file>.sh

產生的差異更新匯入

將差異更新匯入至裝置更新服務的基本程式與任何其他更新相同。如果您尚未這麼做，請務必檢閱如何準備要匯入 Azure 裝置更新以進行 IoT 中樞的更新。

產生匯入指令清單

若要將更新匯入裝置更新服務，您必須擁有或建立匯入指令清單檔案。如需詳細資訊，請參閱將更新匯入裝置更新。

匯入差異更新的指令清單檔必須參考 DiffGen 工具建立的下列檔案：

<recompressed_target_file> SWU 影像
<delta file>

差異更新功能會使用稱為相關檔案的功能，需要第 5 版或更新版本的匯入指令清單。若要使用相關的檔案功能，您必須在匯入指令清單中包含 relatedFiles 和 downloadHandler 物件。

您可以使用 relatedFiles 物件來指定差異更新檔案的相關信息，包括檔名、檔案大小和sha256哈希。最重要的是，您也必須指定下列兩個對差異更新功能而言唯一的屬性：

"properties": {
      "microsoft.sourceFileHashAlgorithm": "sha256",
      "microsoft.sourceFileHash": "<source SWU image file hash>"
}

這兩個屬性都是您在 <source image file> 建立差異更新時用來做為 DiffGen 工具輸入的專屬屬性。即使您實際上未匯入來源映像，匯入指令清單仍需要來源 SWU 映像的相關信息。裝置上的差異元件會在下載差異更新之後，使用此有關來源映像的元數據，在裝置上找出該映像。

downloadHandler使用物件來指定 Device Update 代理程式如何使用相關檔案功能協調差異更新。除非您針對差異功能自定義自己的裝置更新代理程式版本，否則請使用下列專案 downloadHandler：

"downloadHandler": {
  "id": "microsoft/delta:1"
}

您可以使用 Azure CLI az iot du update init v5 命令來產生差異更新的匯入指令清單。如需詳細資訊，請參閱建立基本匯入指令清單。

--update-provider <replace with your Provider> --update-name <replace with your update Name> --update-version <replace with your update Version> --compat manufacturer=<replace with the value your device will report> model=<replace with the value your device will report> --step handler=microsoft/swupdate:2 properties=<replace with any desired handler properties (JSON-formatted), such as '{"installedCriteria": "1.0"}'> --file path=<replace with path(s) to your update file(s), including the full file name> downloadHandler=microsoft/delta:1 --related-file path=<replace with path(s) to your delta file(s), including the full file name> properties='{"microsoft.sourceFileHashAlgorithm": "sha256", "microsoft.sourceFileHash": "<replace with the source SWU image file hash>"}'

使用擴展名 儲存產生的匯入指令清單 JSON .importmanifest.json。

使用 Azure 入口網站進行匯入

建立匯入指令清單之後，請遵循將更新新增至裝置更新中的指示來匯入差異更新，以進行 IoT 中樞。您必須在匯入中包含下列專案：

您先前在先前步驟中建立的 *importmanifest.json 檔案
建立 <recompressed_target_file> DiffGen 工具的 SWU 映像
建立 <delta file> 的 DiffGen 工具

對裝置的差異更新部署

Azure 入口網站中的差異更新部署體驗與部署一般映像更新相同。如需詳細資訊，請參閱使用裝置更新部署更新。

建立差異更新的部署之後，裝置更新服務和用戶端會自動判斷您要部署的每個裝置是否有有效的差異更新。如果他們找到有效的差異，他們會在該裝置上下載並安裝差異更新。

如果找不到有效的差異更新，則會改為將完整映像更新（重新壓縮的目標 SWU 映射）下載為後援。此方法可確保您要部署更新的所有裝置皆為適當的版本。

delta 更新部署有三個可能的結果：

已成功安裝差異更新，且裝置位於新版本上。
差異更新無法使用或無法安裝，但完整映像的後援安裝成功，且裝置處於新版本。
差異和後援安裝都失敗，且裝置仍處於舊版本。

若要判斷發生的失敗結果，您可以選取處於失敗狀態的任何裝置，以錯誤碼和擴充錯誤碼來檢視安裝結果。如有必要，您也可以從多個失敗的裝置收集記錄。

如果差異更新成功，裝置會顯示 [ 成功] 狀態。
如果差異更新失敗，但完整映像的後援成功，裝置會顯示下列錯誤狀態：
- resultCode： <大於 0 的值>
- extendedResultCode： <非零值>

針對失敗的更新進行疑難解答

失敗的更新會顯示您可以使用下列指示解譯的錯誤狀態。從 result.h 中的裝置更新代理程式錯誤開始。

來自差異更新下載處理程式功能專屬裝置更新代理程式的錯誤，開頭為 0x9：

元件	Decimal	Hex	注意
EXTENSION_MANAGER	0	0x00	表示延伸模組管理員下載處理常式邏輯的錯誤。範例: `0x900XXXXX`
PLUGIN	1	0x01	表示下載處理常式外掛程式共用程式庫的使用錯誤。範例: `0x901XXXXX`
已保留	2 - 7	0x02 - 0x07	保留給下載處理程式。範例: `0x902XXXXX`
通用	8	0x08	指出差異下載處理程式延伸模組最上層邏輯中的錯誤。範例: `0x908XXXXX`
SOURCE_UPDATE_CACHE	9	0x09	指出差異下載處理程式延伸模組來源更新快取中的錯誤。範例: `0x909XXXXX`
DELTA_PROCESSOR	10	0x0A	差異處理器 API 錯誤的錯誤碼。範例: `0x90AXXXXX`

如果錯誤碼未出現在 result.h 中，則可能是差異處理器元件中的錯誤，與裝置更新代理程式不同。如果是， extendedResultCode 則為十六進位格式 0x90AXXXXX的負十進位值。

9 為 “Delta Facility”
0A 為「差異處理器元件」（ADUC_COMPONENT_DELTA_DOWNLOAD_HANDLER_DELTA_PROCESSOR）
XXXXX 是現場安裝工具（FIT）差異處理器的 20 位錯誤碼

如果您無法根據錯誤碼資訊解決問題，請提出 GitHub 問題以取得進一步的協助。

共用方式為

差異更新（預覽）

在 IoT 中樞裝置更新中使用 delta 更新的需求

差異處理器元件的裝置更新代理程序設定

裝置更新代理程式

更新處理常式

差異處理器

將來源 SWU 映像檔新增至您的裝置

使用 DiffGen 工具產生差異更新

環境必要條件

使用 DiffGen 建立差異更新

DiffGen 範例

產生的差異更新匯入

產生匯入指令清單

使用 Azure 入口網站進行匯入

對裝置的差異更新部署

針對失敗的更新進行疑難解答

意見反應

其他資源

共用方式為

差異更新 （預覽）

在 IoT 中樞裝置更新中使用 delta 更新的需求

差異處理器元件的裝置更新代理程序設定

裝置更新代理程式

更新處理常式

差異處理器

將來源 SWU 映像檔新增至您的裝置

使用 DiffGen 工具產生差異更新

環境必要條件

使用 DiffGen 建立差異更新

DiffGen 範例

產生的差異更新匯入

產生匯入指令清單

使用 Azure 入口網站進行匯入

對裝置的差異更新部署

針對失敗的更新進行疑難解答

相關內容

意見反應

其他資源

差異更新（預覽）