Ejecución ordenada de varios pasos
La ejecución ordenada de varios pasos en Azure Device Update for IoT Hub le permite ejecutar tareas preinstaladas y posteriores al implementar una actualización inalámbrica. Esta funcionalidad forma parte del esquema del manifiesto de actualización de Device Update versión 4. Para obtener más información, consulte Manifiesto de actualización de Device Update.
La ejecución ordenada con varios pasos puede tener dos tipos de pasos, pasos insertados y pasos de referencia. Un paso insertado es una instrucción que ejecuta código y es el tipo predeterminado. Un paso de referencia es un paso que contiene un identificador para otra actualización.
Actualizaciones primarias y secundarias
Cuando un manifiesto de actualización hace referencia a otro manifiesto de actualización, el manifiesto de nivel superior se denomina actualización primaria y el manifiesto especificado en el paso de referencia se denomina actualización secundaria. Una actualización secundaria no puede contener ningún paso de referencia, solo pasos insertados. Device Update valida esta restricción en el momento de la importación y produce un error en la actualización si no se cumple.
Pasos insertados en una actualización primaria
El agente de Device Update aplica los pasos insertados especificados en una actualización primaria al dispositivo host. El objeto ADUC_WorkflowData que pasa al controlador de pasos, también denominado controlador de contenido de actualización, no contiene datos de Selected Components. El controlador de este tipo de paso no debe ser un controlador de Component-Aware.
El controlador de contenido de pasos del agente de Device Update aplica lógica de validación de IsInstalled para cada paso. El controlador de pasos comprueba si la actualización ya está instalada comprobando si IsInstalled() devuelve código de resultado 900, o true, y usa este resultado para determinar si se debe realizar el paso. Para evitar volver a instalar una actualización que ya está en el dispositivo, el agente de Device Update omite los pasos futuros si ya está instalada una actualización.
Para notificar un resultado de actualización, escriba el resultado de una ejecución del controlador de pasos en la estructura de ADUC_Result en un archivo de resultados deseado tal como se especifica en la opción --result-file. En función de los resultados de la ejecución, devuelva 0 para éxito y devuelva -1 o 0xFF para errores irrecuperables.
Para obtener más información, consulte Controladores de paso y Cómo implementar un controlador de contenido personalizado compatible con componentes.
Pasos de referencia en una actualización primaria
El agente de Device Update aplica los pasos de referencia especificados en una actualización primaria a los componentes activados o conectados al dispositivo host. Cuando procesa un paso de referencia, el controlador de pasos descarga un archivo de manifiesto de actualización desasociado especificado en el paso y valida la integridad del archivo.
A continuación, el controlador de pasos analiza el manifiesto de actualización secundario y crea un objeto ADUC_Workflow, también denominado datos de flujo de trabajo secundarios, combinando los datos del manifiesto de actualización secundario y la información de dirección URL del archivo del manifiesto de actualización principal. Estos datos de flujo de trabajo secundarios tienen una propiedad level establecida en 1.
Ejemplos
El siguiente manifiesto de actualización de ejemplo tiene un paso insertado:
{
"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"
}
El siguiente manifiesto de actualización de ejemplo tiene dos pasos insertados:
{
"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"
}
El siguiente manifiesto de actualización principal tiene un paso de referencia que hace referencia a una actualización secundaria:
{
"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 actualización secundaria contiene pasos insertados.
{
"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\""
}
Nota:
Si usa installedCriteria para determinar si el paso debe ejecutarse o no, debe asignar a cada paso un valor de installedCriteria diferente en el manifiesto de actualización.
Manifiestos de actualización desasociados
Para evitar errores de implementación debido a los límites de tamaño de datos gemelos de Azure IoT Hub, Device Update entrega manifiestos de actualización grandes a dispositivos como archivos de datos JSON denominados manifiestos de actualización desasociados. Al importar una actualización de contenido grande en Device Update, el manifiesto de actualización generado contiene otro archivo de carga denominado Detached Update Manifest, que contiene los datos de manifiesto de actualización completa.
La propiedad UpdateManifest del dispositivo o módulo gemelo contiene la información del archivo de manifiesto de actualización desasociada. Cuando procesa el evento PnP PropertyChanged, el agente de Device Update descarga automáticamente el archivo de manifiesto de actualización desasociado y crea un objeto ADUC_WorkflowData que contiene los datos completos del manifiesto de actualización.