Ordnad körning i flera steg
Med ordnad körning i Flera steg i Azure Device Update för IoT Hub kan du köra förinstallations- och postinstall-uppgifter när du distribuerar en over-the-air-uppdatering. Den här funktionen är en del av manifestschemat för enhetsuppdatering version 4. Mer information finns i Uppdateringsmanifest för enhetsuppdatering.
Ordnad körning i flera steg kan ha två typer av steg, infogade steg och referenssteg. Ett infogat steg är en instruktion som kör kod och är standardtypen. Ett referenssteg är ett steg som innehåller en identifierare för en annan uppdatering.
Överordnade uppdateringar och underordnade uppdateringar
När ett uppdateringsmanifest refererar till ett annat uppdateringsmanifest kallas manifestet på den översta nivån för den överordnade uppdateringen och manifestet som anges i referenssteget kallas för en underordnad uppdatering. En underordnad uppdatering får inte innehålla några referenssteg, bara infogade steg. Enhetsuppdatering validerar den här begränsningen vid importtillfället och misslyckas med uppdateringen om den inte uppfylls.
Infogade steg i en överordnad uppdatering
Enhetsuppdateringsagenten tillämpar infogade steg som anges i en överordnad uppdatering av värdenheten. Objektet ADUC_WorkflowData som skickas till steghanteraren, även kallat en uppdateringsinnehållshanterare, innehåller inga Selected Components data. Hanteraren för den här typen av steg ska inte vara en Component-Aware hanterare.
Enhetsuppdateringsagentens steginnehållshanterare tillämpar valideringslogik IsInstalled för varje steg. Steghanteraren kontrollerar om uppdateringen redan har installerats genom att kontrollera om IsInstalled() returnerar resultatkoden 900, eller true, och använder det här resultatet för att avgöra om steget ska utföras. För att undvika att installera om en uppdatering som redan finns på enheten hoppar enhetsuppdateringsagenten över framtida steg om en uppdatering redan är installerad.
Om du vill rapportera ett uppdateringsresultat skriver du resultatet av en steghanterarkörning till structen ADUC_Result i en önskad resultatfil enligt vad som anges i --result-file alternativet. Baserat på resultatet av körningen returnerar du 0 för framgång och returnerar -1 eller 0xFF för allvarliga fel.
Mer information finns i Steghanterare och Så här implementerar du en anpassad komponentmedveten innehållshanterare.
Referenssteg i en överordnad uppdatering
Enhetsuppdateringsagenten tillämpar referenssteg som anges i en överordnad uppdatering på komponenter på eller anslutna till värdenheten. När den bearbetar ett referenssteg laddar steghanteraren ned en fristående uppdateringsmanifestfil som anges i steget och validerar filintegriteten.
Steghanteraren parsar sedan det underordnade uppdateringsmanifestet och skapar ett ADUC_Workflow objekt, även kallat underordnade arbetsflödesdata, genom att kombinera data från det underordnade uppdateringsmanifestet och fil-URL-informationen från det överordnade uppdateringsmanifestet. Dessa underordnade arbetsflödesdata har en level egenskap inställd på 1.
Exempel
Följande exempel på uppdateringsmanifestet har ett infogat steg:
{
"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"
}
Följande exempel på uppdateringsmanifestet har två infogade steg:
{
"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"
}
Följande överordnade uppdateringsmanifest har ett referenssteg som refererar till en underordnad uppdatering:
{
"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"
}
Den underordnade uppdateringen innehåller infogade steg.
{
"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\""
}
Kommentar
Om du använder installedCriteria för att avgöra om steget ska köras eller inte bör du ge varje steg ett annat installedCriteria värde i uppdateringsmanifestet.
Frånkopplade uppdateringsmanifest
För att undvika distributionsfel på grund av datastorleksgränser för Azure IoT Hub-tvillingdata levererar Enhetsuppdatering stora uppdateringsmanifest till enheter som JSON-datafiler som kallas fristående uppdateringsmanifest. När du importerar en stor innehållsuppdatering till Enhetsuppdatering innehåller det genererade uppdateringsmanifestet en annan nyttolastfil med namnet Detached Update Manifest, som innehåller fullständiga uppdateringsmanifestdata.
Egenskapen UpdateManifest i enhets- eller modultvillingen innehåller information om den frånkopplade uppdateringsmanifestfilen. När den bearbetar PnP-händelsen PropertyChanged laddar enhetsuppdateringsagenten automatiskt ned den frånkopplade uppdateringsmanifestfilen och skapar ett ADUC_WorkflowData objekt som innehåller fullständiga uppdateringsmanifestdata.