Udostępnij za pośrednictwem

Wykonywanie uporządkowane w wielu krokach

  • Artykuł

Wykonywanie uporządkowane w wielu krokach umożliwia uruchamianie zadań przed instalacją i po instalacji podczas wdrażania aktualizacji over-the-air. Ta funkcja jest częścią schematu manifestu aktualizacji aktualizacji w wersji 4 w publicznej wersji zapoznawczej.

Zapoznaj się z dokumentacją aktualizacji manifestu przed przejrzeniem poniższych zmian w ramach publicznej wersji zapoznawczej odświeżania.

W przypadku wykonywania uporządkowanego w wielu krokach istnieją dwa typy kroków:

  • Krok wbudowany (wartość domyślna)
  • Krok odwołania

Przykładowy manifest aktualizacji z jednym krokiem wbudowanym:

{
    "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"
}

Przykładowy manifest aktualizacji z dwoma krokami wbudowanymi:

{
    "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"
}

Przykładowy manifest aktualizacji z jednym krokiem referencyjnym:

  • Aktualizacja nadrzędna, która odwołuje się do aktualizacji podrzędnej

    {
    "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"
}

  • Aktualizacja podrzędna z wbudowanymi krokami

    {
    "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\""
}

Uwaga

W manifeście aktualizacji każdy krok powinien mieć inny zainstalowany ciągCriteria , jeśli ten ciąg jest używany do określenia, czy krok powinien zostać wykonany, czy nie.

Aktualizacje nadrzędne i aktualizacje podrzędne

Gdy manifesty aktualizacji odwołują się do siebie nawzajem, manifest najwyższego poziomu jest nazywany aktualizacją nadrzędną , a manifest określony w kroku odwołania jest nazywany aktualizacją podrzędną.

Obecnie aktualizacja podrzędna nie może zawierać żadnych kroków referencyjnych. To ograniczenie jest weryfikowane w czasie importowania, a jeśli nie następuje importowanie, zakończy się niepowodzeniem.

Kroki wbudowane w aktualizacji nadrzędnej

Kroki wbudowane określone w aktualizacji nadrzędnej są stosowane do urządzenia hosta. W tym miejscu obiekt ADUC_WorkflowData przekazywany do procedury obsługi kroków (nazywanej również procedurą obsługi zawartości aktualizacji) i nie będzie zawierać Selected Components danych. Procedura obsługi tego typu kroku nie powinna być procedurą Component-Aware obsługi.

Procedura obsługi zawartości stosuje logikę walidacji IsInstalled dla każdego kroku. Procedura obsługi kroków agenta aktualizacji urządzeń sprawdza, czy określona aktualizacja jest już zainstalowana, sprawdzając, czy isInstalled() spowodowało kod wyniku "900", co oznacza "true". Jeśli aktualizacja jest już zainstalowana, aby uniknąć ponownej instalacji aktualizacji, która jest już zainstalowana na urządzeniu, agent DU pominie przyszłe kroki, ponieważ użyjemy go do określenia, czy wykonać krok, czy nie.

Aby zgłosić wynik aktualizacji, wynik wykonania procedury obsługi kroków musi zostać zapisany w ADUC_Result struktura w żądanym pliku wynikowym określonym w opcji --result-file. Następnie na podstawie wyników wykonania, dla powodzenia zwracany jest 0, w przypadku błędów krytycznych zwracany jest -1 lub 0xFF.

Aby uzyskać więcej informacji, zobacz Procedura obsługi zawartości i Implementowanie niestandardowej procedury obsługi zawartości obsługującej składniki.

Kroki referencyjne w aktualizacji nadrzędnej

Kroki referencyjne określone w aktualizacji nadrzędnej są stosowane do składników na urządzeniu hosta lub połączone z nim. Krok referencyjny to krok zawierający identyfikator aktualizacji innej aktualizacji o nazwie aktualizacja podrzędna.

Podczas przetwarzania kroku odniesienia procedura obsługi kroków pobiera odłączony plik manifestu aktualizacji określony w danych kroku odniesienia, a następnie weryfikuje integralność pliku. Następnie procedura obsługi analizuje manifest aktualizacji podrzędnej i tworzy obiekt ADUC_Workflow (znany również jako dane przepływu pracy podrzędnego) przez połączenie danych z manifestu aktualizacji podrzędnej i adresów URL plików z manifestu aktualizacji nadrzędnej. Te podrzędne dane przepływu pracy mają również właściwość "level" ustawioną na wartość "1".

Uwaga

Obecnie aktualizacje podrzędne nie mogą zawierać żadnych kroków referencyjnych.

Odłączone manifesty aktualizacji

Aby uniknąć niepowodzenia wdrażania z powodu IoT Hub limitów rozmiaru danych bliźniaczej reprezentacji, każdy duży manifest aktualizacji zostanie dostarczony w postaci pliku danych JSON, nazywany również odłączonym manifestem aktualizacji.

Jeśli aktualizacja z dużą zawartością zostanie zaimportowana do usługi Device Update dla IoT Hub, wygenerowany manifest aktualizacji będzie zawierać inny plik ładunku o nazwie Detached Update Manifest, który zawiera pełne dane manifestu aktualizacji.

Właściwość UpdateManifest w bliźniaczej reprezentacji urządzenia lub modułu będzie zawierać informacje o odłączonym pliku manifestu aktualizacji.

Podczas przetwarzania zdarzenia zmienionej właściwości PnP agent aktualizacji urządzenia automatycznie pobierze odłączony plik manifestu aktualizacji i utworzy obiekt ADUC_WorkflowData zawierający pełne dane manifestu aktualizacji.