Многоэтапное упорядоченное выполнение

Статья
11/12/2021

Многоэтапное упорядоченное выполнение позволяет выполнять задачи перед и после установки при развертывании обновления беспроводным способом. Эта возможность является частью схемы Public Preview Refresh Update Manifest v4.

Ознакомьтесь с документацией Манифеста обновления, прежде чем просматривать следующие изменения в рамках общедоступной предварительной версии обновления.

При многоэтапном упорядоченном выполнении существует два типа этапов:

встроенный этап (по умолчанию);
эталонный этап.

Пример манифеста обновления с одним встроенным этапом:

{
    "updateId": {...},
    "isDeployable": true,
    "compatibility": [
        {
            "deviceManufacturer": "du-device",
            "deviceModel": "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": [
        {
            "deviceManufacturer": "du-device",
            "deviceModel": "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": [
        {
            "deviceManufacturer": "du-device",
            "deviceModel": "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() приводит к результату с кодом 900, что означает true. Если обновление уже установлено, чтобы избежать повторной установки обновления, которое уже находится на устройстве, агент Обновления устройств пропустит дальнейшие действия, так как он используется для определения того, следует ли выполнять шаг.

Чтобы сообщить о результате обновления, результат выполнения обработчика этапов должен быть записан в структуру ADUC_Result в нужном файле результатов, указанном в параметре --result-file. Затем на основе результатов выполнения возвращается 0 для успешного завершения либо –1 или 0xFF для любых неустранимых ошибок.

Дополнительные сведения см. в статьях Обработчик содержимого этапов и Реализация пользовательского обработчика содержимого, учитывающего компоненты.

Эталонные этапы в родительском обновлении

Эталонные этапы, указанные в родительском обновлении, применяются к компонентам, подключенным к устройству узла, или находящимся на нем непосредственно. Эталонный этап — это этап, который содержит идентификатор другого обновления, называемого дочерним обновлением.

При обработке эталонного этапа обработчик этапов загружает файл отключенного манифеста обновления, указанный в разделе данных эталонного этапа, а затем проверяет целостность файла. После этого обработчик этапов анализирует манифест обновления дочернего элемента и создает объект ADUC_Workflow (также называется данные дочернего рабочего процесса), объединяя данные из манифеста обновления дочернего элемента и URL-адреса файлов из манифеста обновления родительского элемента. Эти данные дочернего рабочего процесса также имеют свойство level со значением "1".

Примечание

Сейчас дочерние обновления не могут содержать эталонные этапы.

Отключенные манифесты обновлений

Чтобы избежать сбоя развертывания из-за ограничений по размеру данных цифрового двойника в Центре Интернета вещей, все манифесты обновления большого размера будут доставляться в виде файла данных JSON (также называемого отключенный манифест обновления).

Если обновление с содержимым большого размера импортируется в Обновление устройств для Центра Интернета вещей, созданный манифест обновления будет содержать другой файл полезных данных под названием Detached Update Manifest, который содержит все данные манифеста обновления.

Свойство UpdateManifest на устройстве или в цифровом двойнике модуля будет содержать сведения о файле отключенного манифеста обновления.

При обработке события изменения свойства PnP агент Обновления устройств автоматически загрузит файл отключенного манифеста обновления и создаст объект ADUC_WorkflowData, который содержит все данные манифеста обновления.

Поделиться через

Многоэтапное упорядоченное выполнение

Родительские и дочерние обновления

Встроенные этапы в родительском обновлении

Эталонные этапы в родительском обновлении

Отключенные манифесты обновлений

Дополнительные ресурсы