Mehrstufige geordnete Ausführung
Mit einer geordneten mehrstufigen Ausführung in Azure Device Update for IoT Hub können Sie Vor- und Nachinstallationsaufgaben ausführen, wenn Sie ein Over-the-Air-Update bereitstellen. Diese Funktion ist Teil von Version 4 des Device Update-Manifestschemas. Weitere Informationen finden Sie unter Device Update-Updatemanifest.
Die geordnete mehrstufige Ausführung kann zwei Typen von Schritten umfassen: Inlineschritte und Referenzschritte. Der Standardtyp sind Inlineschritte. Dabei handelt es sich um Anweisungen zur Codeausführung. Ein Referenzschritt enthält einen Bezeichner für ein anderes Update.
Übergeordnete Updates und untergeordnete Updates
Wenn ein Updatemanifest auf ein anderes Updatemanifest verweist, wird das Manifest der obersten Ebene als übergeordnetes Update bezeichnet und das im Referenzschritt angegebene Manifest als untergeordnetes Update. Ein untergeordnetes Update darf keine weiteren Referenzschritte enthalten, sondern nur Inlineschritte. Device Update überprüft diese Einschränkung direkt beim Import und löst einen Fehler für das Update aus, wenn die Bedingung nicht erfüllt ist.
Inlineschritte in einem übergeordneten Update
Der Device Update-Agent wendet die Inlineschritte, die in einem übergeordneten Update auf angegeben sind, auf das Hostgerät an. Das ADUC_WorkflowData-Objekt, das an den Schritthandler (auch als Updateinhaltshandler bezeichnet) übergeben wird, enthält keine Selected Components-Daten. Der Handler für diesen Schritttyp sollte kein Component-Aware-Handler sein.
Der Schritthandler des Device Update-Agents wendet in jedem Schritt IsInstalled-Validierungslogik an. Der Schritthandler überprüft, ob das Update bereits installiert wurde, indem er abfragt, ob IsInstalled() den Ergebniscode 900 oder TRUE zurückgibt. Mithilfe dieses Ergebnisses bestimmt er dann, ob der Schritt ausgeführt wird. Um zu vermeiden, dass ein bereits auf dem Gerät installiertes Update erneut installiert wird, überspringt der Device Update-Agent zukünftige Schritte, wenn ein Update bereits installiert ist.
Um ein Updateergebnis zu melden, schreiben Sie das Ergebnis einer Ausführung des Schritthandlers in die ADUC_Result-Struktur der gewünschten Ergebnisdatei, wie in der --result-file-Option angegeben. Basierend auf den Ergebnissen der Ausführung wird bei einem Erfolg 0 und bei schwerwiegenden Fehlern -1 oder 0xFF zurückgegeben.
Weitere Informationen finden Sie unter Schritthandler und Implementieren eines benutzerdefinierten komponentenbezogenen Inhaltshandlers.
Referenzschritte in einem übergeordneten Update
Der Device Update-Agent wendet Referenzschritte, die in einem übergeordneten Update angegeben sind, auf Komponenten an, die sich auf dem Hostgerät befinden oder mit diesem verbunden sind. Bei der Verarbeitung eines Referenzschritts lädt der Schritthandler eine im Schritt angegebene getrennte Updatemanifestdatei herunter und überprüft deren Dateiintegrität.
Anschließend analysiert der Schritthandler das untergeordnete Updatemanifest und erstellt ein ADUC_Workflow-Objekt (auch als untergeordnete Workflowdaten bezeichnet), indem er die Daten aus dem untergeordneten Updatemanifest und Datei-URL-Informationen aus dem übergeordneten Updatemanifest kombiniert. Bei diesen untergeordneten Workflowdaten ist die level-Eigenschaft auf 1 festgelegt.
Beispiele
Das folgende Beispielupdatemanifest enthält einen Inlineschritt:
{
"updateId": {...},
"isDeployable": true,
"compatibility": [
{
"manufacturer": "du-device",
"model": "e2e-test"
}
],
"instructions": {
"steps": [
{
"description": "Example APT update that installs 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"
}
Das folgende Beispielupdatemanifest enthält zwei Inlineschritte:
{
"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"
}
Das folgende übergeordnete Updatemanifest enthält einen Referenzschritt, der auf ein untergeordnetes Update verweist:
{
"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"
}
Das untergeordnete Update enthält Inlineschritte.
{
"updateId": {
"provider": "contoso",
"name": "virtual-camera",
"version": "1.2"
},
"isDeployable": false,
"compatibility": [
{
"group": "cameras"
}
],
"instructions": {
"steps": [
{
"description": "Cameras Update - preinstall 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 - postinstall 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-step-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\""
}
Hinweis
Wenn Sie mit installedCriteria bestimmen, ob der Schritt ausgeführt werden soll, sollten Sie jedem Schritt im Updatemanifest einen anderen installedCriteria-Wert zuweisen.
Getrennte Updatemanifeste
Um Bereitstellungsfehler aufgrund der Größenbeschränkungen für Azure IoT Hub-Zwillingsdaten zu vermeiden, übermittelt Device Update große Updatemanifeste als JSON-Datendateien an Geräte, die als getrennte Updatemanifeste bezeichnet werden. Wenn Sie ein großes Inhaltsupdate in Device Update importieren, enthält das generierte Updatemanifest eine weitere Nutzdatendatei Detached Update Manifest, die die vollständigen Updatemanifestdaten enthält.
Die UpdateManifest-Eigenschaft auf dem Geräte- oder Modulzwilling enthält die Informationen aus der getrennten Updatemanifestdatei. Bei der Verarbeitung des PnP-PropertyChanged-Ereignisses lädt der Device Update-Agent automatisch die getrennte Updatemanifestdatei herunter und erstellt ein ADUC_WorkflowData-Objekt, das die vollständigen Updatemanifestdaten enthält.