Exécution ordonnée en plusieurs étapes
L’exécution ordonnée en plusieurs étapes vous permet d’exécuter des tâches de préinstallation et de post-installation lors du déploiement d’une mise à jour OTA. Cette fonctionnalité fait partie du schéma du manifeste de mise à jour d’actualisation de la préversion publique v4.
Consultez la documentation du manifeste de mise à jour avant d’examiner les changements ci-dessous apportés par la version d’actualisation de la préversion publique.
Avec l’exécution ordonnée en plusieurs étapes, il existe deux types d’étapes :
- Étape inline (par défaut)
- Étape de référence
Exemple de manifeste de mise à jour avec une seule étape inline :
{
"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"
}
Exemple de manifeste de mise à jour avec deux étapes inline :
{
"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"
}
Exemple de manifeste de mise à jour avec une seule étape de référence :
Mise à jour parente qui référence une mise à jour enfant
{ "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" }Mise à jour enfant avec étapes inline
{ "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\"" }
Notes
Dans le manifeste de mise à jour, chaque étape doit avoir une chaîne installedCriteria différente si cette chaîne est utilisée pour déterminer si l’étape doit être effectuée ou non.
Mises à jour parentes et mises à jour enfants
Lorsque les manifestes de mise à jour font référence les uns aux autres, le manifeste de niveau supérieur est appelé la mise à jour parente et un manifeste spécifié dans une étape de référence est appelé mise à jour enfant.
Actuellement, une mise à jour enfant ne peut pas contenir d’étapes de référence. Cette restriction est vérifiée au moment de l’importation et, si elle n’est pas respectée, l’importation échoue.
Étapes inline dans une mise à jour parente
Les étapes inline spécifiées dans une mise à jour parente sont appliquées à l’appareil hôte. Ici, l’objet ADUC_WorkflowData est passé à un gestionnaire d’étapes (également appelé gestionnaire de contenu de mise à jour) et ne contient pas les données Selected Components. Le gestionnaire de ce type d’étape ne doit pas être un gestionnaire Component-Aware.
Le gestionnaire de contenu des étapes applique la logique de validation IsInstalled pour chaque étape. Le gestionnaire d’étapes de l’agent Device Update contrôle si une mise à jour particulière est déjà installée en vérifiant si IsInstalled() a entraîné un code de résultat « 900 » qui signifie « true ». Si une mise à jour est déjà installée, pour éviter de réinstaller une mise à jour déjà sur l’appareil, l’agent DU ignore les étapes futures, car nous l’utilisons pour déterminer s’il faut effectuer l’étape ou non.
Pour signaler un résultat de mise à jour, le résultat de l’exécution d’un gestionnaire d’étapes doit être écrit dans un struct ADUC_Result dans un fichier de résultats souhaité, comme spécifié dans l’option --result-file. Ensuite, en fonction des résultats de l’exécution, pour le retour de l’état de réussite 0, pour toutes les erreurs irrécupérables, retournez -1 ou 0xFF.
Pour plus d’informations, consultez Gestionnaire de contenu des étapes et Implémentation d’un gestionnaire de contenu prenant en charge les composants personnalisés.
Étapes de référence dans une mise à jour parente
Les étapes de référence spécifiées dans une mise à jour parente sont appliquées aux composants sur l’appareil hôte ou connectés à celui-ci. Une étape de référence est une étape qui contient l’identificateur de mise à jour d’une autre mise à jour, appelée mise à jour enfant.
Lors du traitement d’une étape de référence, le gestionnaire d’étapes télécharge un fichier manifeste de mise à jour détaché qui est spécifié dans les données de l’étape de référence, puis il vérifie l’intégrité du fichier. Ensuite, le gestionnaire d’étapes analyse le manifeste de mise à jour enfant et il crée un objet ADUC_Workflow (également connu sous le nom de données de workflow enfant) en combinant les données du manifeste de mise à jour enfant et les informations d’URL de fichier contenues dans le manifeste de mise à jour parent. Ces données de workflow enfant ont également une propriété « level » définie sur « 1 ».
Notes
Actuellement, les mises à jour enfants ne peuvent pas contenir d’étapes de référence.
Manifestes de mise à jour détachés
Pour éviter un échec du déploiement en raison des limites de taille des données du jumeau IoT Hub, tout manifeste de mise à jour volumineux est remis sous la forme d’un fichier de données JSON, également appelé manifeste de mise à jour détaché.
Si une mise à jour avec du contenu volumineux est importée dans Device Update pour IoT Hub, le manifeste de mise à jour généré contient un autre fichier de charge utile appelé Detached Update Manifest, qui contient les données complètes de ce manifeste.
La propriété UpdateManifest du jumeau d’appareil ou de module contient les informations du fichier manifeste de mise à jour détaché.
Lors du traitement d’un événement property changed PnP, l’agent Device Update télécharge automatiquement le fichier manifeste de mise à jour détaché et il crée un objet ADUC_WorkflowData qui contient les données complètes du manifeste de mise à jour.