多步驟排序執行

發行項
03/21/2023

多步驟排序的執行可讓您在部署無線更新時執行預先安裝與後續安裝工作。這項功能是公開預覽重新整理更新資訊清單 v4 結構描述的一部分。

請先參閱更新資訊清單文件，再檢閱公開預覽重新整理版本中的下列變更。

使用多步驟排序執行時，有兩種類型的步驟：

內嵌步驟 (預設)
參考步驟

使用一個內嵌步驟的更新資訊清單範例：

{
    "updateId": {...},
    "isDeployable": true,
    "compatibility": [
        {
            "manufacturer": "du-device",
            "model": "e2e-test"
        }
    ],
    "instructions": {
        "steps": [
            {
                "description": "Example APT update that install libcurl4-doc on a host device.",
                "handler": "microsoft/apt:1",
                "files": [
                    "apt-manifest-1.0.json"
                ],
                "handlerProperties": {
                    "installedCriteria": "apt-update-test-1.0"
                }
            }
        ]
    },
    "manifestVersion": "4.0",
    "importedDateTime": "2021-11-16T14:54:55.8858676Z",
    "createdDateTime": "2021-11-16T14:50:47.3511877Z"
}

使用兩個內嵌步驟的更新資訊清單範例：

{
    "updateId": {...},
    "isDeployable": true,
    "compatibility": [
        {
            "manufacturer": "du-device",
            "model": "e2e-test"
        }
    ],
    "instructions": {
        "steps": [
            {
                "description": "Install libcurl4-doc on host device",
                "handler": "microsoft/apt:1",
                "files": [
                    "apt-manifest-1.0.json"
                ],
                "handlerProperties": {
                    "installedCriteria": "apt-update-test-2.2"
                }
            },
            {
                "description": "Install tree on host device",
                "handler": "microsoft/apt:1",
                "files": [
                    "apt-manifest-tree-1.0.json"
                ],
                "handlerProperties": {
                    "installedCriteria": "apt-update-test-tree-2.2"
                }
            }
        ]
    },
    "manifestVersion": "4.0",
    "importedDateTime": "2021-11-16T20:21:33.6514738Z",
    "createdDateTime": "2021-11-16T20:19:29.4019035Z"
}

使用一個參考步驟的更新資訊清單範例：

參考子系更新的父代更新

{
    "updateId": {...},
    "isDeployable": true,
    "compatibility": [
        {
            "manufacturer": "du-device",
            "model": "e2e-test"
        }
    ],
    "instructions": {
        "steps": [
            {
                "type": "reference",
                "description": "Cameras Firmware Update",
                "updateId": {
                    "provider": "contoso",
                    "name": "virtual-camera",
                    "version": "1.2"
                }
            }
        ]
    },
    "manifestVersion": "4.0",
    "importedDateTime": "2021-11-17T07:26:14.7484389Z",
    "createdDateTime": "2021-11-17T07:22:10.6014567Z"
}

使用內嵌步驟的子系更新

{
    "updateId": {
        "provider": "contoso",
        "name": "virtual-camera",
        "version": "1.2"
    },
    "isDeployable": false,
    "compatibility": [
        {
            "group": "cameras"
        }
    ],
    "instructions": {
        "steps": [
            {
                "description": "Cameras Update - pre-install step",
                "handler": "microsoft/script:1",
                "files": [
                    "contoso-camera-installscript.sh"
                ],
                "handlerProperties": {
                    "scriptFileName": "contoso-camera-installscript.sh",
                    "arguments": "--pre-install-sim-success --component-name --component-name-val --component-group --component-group-val --component-prop path --component-prop-val path",
                    "installedCriteria": "contoso-virtual-camera-1.2-step-0"
                }
            },
            {
                "description": "Cameras Update - firmware installation (failure - missing file)",
                "handler": "microsoft/script:1",
                "files": [
                    "contoso-camera-installscript.sh",
                    "camera-firmware-1.1.json"
                ],
                "handlerProperties": {
                    "scriptFileName": "missing-contoso-camera-installscript.sh",
                    "arguments": "--firmware-file camera-firmware-1.1.json --component-name --component-name-val --component-group --component-group-val --component-prop path --component-prop-val path",
                    "installedCriteria": "contoso-virtual-camera-1.2-step-1"
                }
            },
            {
                "description": "Cameras Update - post-install step",
                "handler": "microsoft/script:1",
                "files": [
                    "contoso-camera-installscript.sh"
                ],
                "handlerProperties": {
                    "scriptFileName": "contoso-camera-installscript.sh",
                    "arguments": "--post-install-sim-success --component-name --component-name-val --component-group --component-group-val --component-prop path --component-prop-val path",
                    "installedCriteria": "contoso-virtual-camera-1.2-stop-2"
                }
            }
        ]
    },
    "referencedBy": [
        {
            "provider": "DU-Client-Eng",
            "name": "MSOE-Update-Demo",
            "version": "3.1"
        }
    ],
    "manifestVersion": "4.0",
    "importedDateTime": "2021-11-17T07:26:14.7376536Z",
    "createdDateTime": "2021-11-17T07:22:09.2232968Z",
    "etag": "\"ad7a553d-24a8-492b-9885-9af424d44d58\""
}

注意

在更新資訊清單中，如果使用該字串來判斷是否應該執行步驟，則每個步驟都應該有不同的 installedCriteria 字串。

父代更新和子系更新

當更新資訊清單彼此參考時，最上層資訊清單稱為父代更新，而參考步驟中指定的資訊清單稱為子系更新。

目前，子系更新不能包含任何參考步驟。執行匯入時會驗證這項限制，若未遵循，匯入便會失敗。

父代更新中的內嵌步驟

在父代更新中指定的內嵌步驟會套用至主機裝置。系統會將 ADUC_WorkflowData 物件傳遞給步驟處理常式 (又稱為更新內容處理常式)，且其中不會包含 Selected Components 資料。這類型步驟的處理常式「不得」為 Component-Aware 處理常式。

步驟內容處理常式會針對每個步驟套用 IsInstalled 驗證邏輯。裝置更新代理程式的步驟處理常式會檢查是否已經安裝特定更新，方法是檢查 IsInstalled() 是否產生表示 'true' 的結果碼 “900”。如果已安裝更新，為了避免重新安裝已在裝置上的更新，DU 代理程式將會略過未來的步驟，因為我們使用它來判斷是否要執行步驟。

若要報告更新結果，步驟處理常式執行的結果必須寫入至所需的結果檔 (如 --result-file 選項中所指定) 中的 ADUC_Result 結構。然後，根據執行的結果，針對成功傳回 0，針對任何嚴重錯誤傳回 -1 或 0xFF。

如需詳細資料，請參閱步驟內容處理常式 (英文) 和實作自訂元件感知內容處理常式 (英文)。

父代更新中的參考步驟

父代更新中指定的參考步驟會套用至主機裝置上的元件，或連線到主機裝置。 參考步驟是一種步驟，其中包含另一項更新 (稱為子系更新) 的更新識別碼。

處理參考步驟時，步驟處理常式會下載參考步驟資料中指定的中斷連結更新資訊清單檔案，然後驗證該檔案的完整性。接著，步驟處理常式會合併子系更新資訊清單中的資料和父系更新資訊清單中的檔案 URL 資訊，以剖析子系更新資訊清單，並建立 ADUC_Workflow 物件 (又稱為子系工作流程資料)。此子系工作流程資料還會將 'level' 屬性設為 '1'。

注意

目前，子系更新不能包含任何參考步驟。

中斷連結更新資訊清單

為了避免 IoT 中樞對應項資料大小限制造成部署失敗，所有大型更新資訊清單都會以 JSON 資料檔案的形式傳遞，又稱為中斷連結更新資訊清單。

如果具有大型內容的更新匯入 IoT 中樞裝置更新，則產生的更新資訊清單會包含另一個稱作 Detached Update Manifest 的承載檔案，其中含有更新資訊清單的完整資料。

裝置或模組對應項中的 UpdateManifest 屬性會包含中斷連結更新資訊清單檔案的資訊。

處理 PnP 屬性變更事件時，裝置更新代理程式會自動下載中斷連結更新資訊清單檔案，並建立包含完整更新資訊清單資料的 ADUC_WorkflowData 物件。

共用方式為

多步驟排序執行

父代更新和子系更新

父代更新中的內嵌步驟

父代更新中的參考步驟

中斷連結更新資訊清單

意見反應

其他資源