Exécution ordonnée en plusieurs étapes
L’exécution ordonnée en plusieurs étapes dans Azure Device Update pour IoT Hub vous permet d’exécuter des tâches de préinstallation et de post-installation quand vous déployez une mise à jour via un réseau sans fil. Cette fonctionnalité fait partie du schéma du manifeste de mise à jour de Device Update version 4. Pour plus d’informations, consultez Manifeste de mise à jour de Device Update.
L’exécution ordonnée en plusieurs étapes peut avoir deux types d’étapes : des étapes inline et des étapes de référence. Une étape inline est une instruction qui exécute du code ; c’est le type d’étape par défaut. Une étape de référence est une étape qui contient un identificateur pour une autre mise à jour.
Mises à jour parentes et mises à jour enfants
Quand un manifeste de mise à jour fait référence à un autre manifeste de mise à jour, le manifeste de plus haut niveau est appelé la mise à jour parente et le manifeste spécifié dans l’étape de référence est appelé mise à jour enfant. Une mise à jour enfant ne peut pas contenir d’étapes de référence, mais seulement des étapes inline. Device Update vérifie cette restriction au moment de l’importation et met en échec la mise à jour si elle n’est pas satisfaite.
Étapes inline dans une mise à jour parente
L’agent Device Update applique à l’appareil hôte les étapes inline spécifiées dans une mise à jour parente. L’objet ADUC_WorkflowData qui passe au gestionnaire d’étapes, également appelé gestionnaire de contenu de mise à jour, ne contient aucune donnée de Selected Components. Le gestionnaire pour ce type d’étape ne doit pas être un gestionnaire Component-Aware.
Le gestionnaire de contenu d’étape de l’agent Device Update applique une logique de validation IsInstalled pour chaque étape. Le gestionnaire d’étapes recherche si la mise à jour est déjà installée en vérifiant si IsInstalled() retourne le code de résultat 900, ou vrai (true), et utilise ce résultat pour déterminer s’il faut effectuer l’étape. Pour éviter de réinstaller une mise à jour déjà présente sur l’appareil, l’agent Device Update ignore les étapes futures si une mise à jour est déjà installée.
Pour indiquer le résultat d’une mise à jour, écrivez le résultat de l’exécution d’un gestionnaire d’étapes dans le struct ADUC_Result dans un fichier de résultats de votre choix, spécifié dans l’option --result-file. En fonction des résultats de l’exécution, retournez 0 pour une réussite et, retournez -1 ou 0xFF pour des erreurs irrécupérables.
Pour plus d’informations, consultez Gestionnaire d’étapes et Comment implémenter un gestionnaire de contenu prenant en charge les composants personnalisés.
Étapes de référence dans une mise à jour parente
L’agent Device Update applique les étapes de référence spécifiées dans une mise à jour parente aux composants présents sur l’appareil hôte ou qui y sont connectés. Quand il traite 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 l’étape, puis il vérifie l’intégrité du fichier.
Le gestionnaire d’étapes analyse ensuite le manifeste de mise à jour enfant, et il crée un objet ADUC_Workflow (également appelé « données de workflow enfant ») en combinant les données du manifeste de mise à jour enfant et les informations d’URL de fichier provenant du manifeste de mise à jour parente. Ces données de workflow enfant ont une propriété level définie sur 1.
Exemples
L’exemple de manifeste de mise à jour suivant a une seule étape inline :
{
"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"
}
L’exemple de manifeste de mise à jour suivant a 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"
}
Le manifeste de mise à jour parente suivant a une étape de référence qui fait 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"
}
La mise à jour enfant contient des étapes inline.
{
"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\""
}
Remarque
Si vous utilisez installedCriteria pour déterminer si l’étape doit s’exécuter ou non, vous devez donner à chaque étape une valeur différente pour installedCriteria dans le manifeste de mise à jour.
Manifestes de mise à jour détachés
Pour éviter un échec de déploiement en raison des limites de taille des données des jumeaux Azure IoT Hub, Device Update fournit aux appareils des manifestes de mise à jour de grande taille sous forme de fichiers de données JSON appelés manifestes de mise à jour détachés. Quand vous importez une mise à jour de contenu de grande taille dans Device Update, 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 du manifeste de mise à jour.
La propriété UpdateManifest du jumeau d’appareil ou de module contient les informations du fichier manifeste de mise à jour détaché. Quand il traite l’événement PnP PropertyChanged, l’agent Device Update télécharge automatiquement le fichier manifeste de mise à jour détaché et crée un objet ADUC_WorkflowData qui contient les données complètes du manifeste de mise à jour.