Conceptos de importación de Azure Device Update for IoT Hub
Para implementar una actualización en dispositivos mediante Azure Device Update for IoT Hub, primero se importa la actualización en el servicio Device Update, que almacena la actualización importada y la implementa en los dispositivos. En este artículo se proporciona información general sobre algunos conceptos importantes que se deben conocer en relación con la importación de actualizaciones.
Manifiesto de importación
Un manifiesto de importación es un archivo JSON que define información importante acerca de la actualización que va a importar. Enviará el manifiesto de importación y el archivo o archivos de actualización asociados, por ejemplo, un paquete de actualización de firmware, como parte del proceso de importación. Los metadatos definidos en el manifiesto de importación se usan para ingerir la actualización. Parte de los metadatos también se usan en el momento de la implementación. Por ejemplo, para validar si una actualización se instaló correctamente.
El siguiente código JSON muestra un archivo de manifiesto de importación de ejemplo:
{
"updateId": {
"provider": "Contoso",
"name": "Toaster",
"version": "1.0"
},
"isDeployable": false,
"compatibility": [
{
"manufacturer": "Contoso",
"model": "Toaster"
}
],
"instructions": {
"steps": [
{
"handler": "microsoft/swupdate:2",
"files": [
"firmware.swu"
],
"handlerProperties": {
"installedCriteria": "1.0"
}
}
]
},
"files": [
{
"filename": "firmware.swu",
"sizeInBytes": 7558,
"hashes": {
"sha256": "/CD7Sn6fiknWa3NgcFjGlJ+ccA81s1QAXX4oo5GHiFA="
}
}
],
"createdDateTime": "2022-01-19T06:23:52.6996916Z",
"manifestVersion": "5.0"
}
Las secciones del archivo de manifiesto de importación representan conceptos importantes de Device Update, como se describe en las secciones siguientes. Para obtener información sobre el esquema de manifiesto de importación completo, consulte Importar esquema JSON del manifiesto.
Identidad de actualización
La identidad de actualización o updateId es el identificador único de una actualización en Device Update y contiene las siguientes propiedades:
- Proveedor es la entidad que crea o es responsable por la actualización. Proveedor suele ser un nombre de empresa.
- Nombre es el identificador de una clase de actualización. Nombre suele ser un nombre de modelo o clase de dispositivo.
- Versión es un número que distingue esta actualización de otras con el mismo proveedor y nombre.
Por ejemplo:
{
"updateId": {
"provider": "Contoso",
"name": "Toaster",
"version": "1.0"
}
}
Nota:
El servicio Device Update solo usa el updateId y es diferente de las identidades de componentes de software de los dispositivos.
Compatibilidad
La sección Compatibilidad usa uno o varios pares clave-valor arbitrarios para definir los dispositivos que pueden instalar una actualización. Solo los dispositivos que notifican propiedades que coinciden con los valores de compatibilidad son aptos para implementar la actualización. Puede hacer que una actualización sea compatible con varias clases de dispositivo mediante la inclusión de más de un conjunto de propiedades de compatibilidad de dispositivos.
En el ejemplo siguiente se muestra una actualización que solo se puede implementar en dispositivos que informan Contoso y Toaster como su fabricante y modelo de dispositivo.
{
"compatibility": [
{
"manufacturer": "Contoso",
"model": "Toaster"
}
]
}
Instrucciones
La sección Instrucciones contiene la información necesaria o los pasos necesarios para que el agente de dispositivo instale la actualización. La actualización más sencilla contiene un solo paso insertado que ejecuta el archivo de carga de actualización mediante un controlador registrado con el agente de dispositivo. En el ejemplo siguiente se muestra una sección de instrucciones de un solo paso.
{
"instructions": {
"steps": [
{
"handler": "microsoft/swupdate:2",
"files": [
"contoso.toaster.1.0.swu"
]
}
]
}
}
Nota:
La propiedad handler es equivalente a la propiedad updateType en la versión 3.0 o anterior del manifiesto de importación.
Una actualización puede contener más de un paso, como en el ejemplo siguiente:
{
"instructions": {
"steps": [
{
"description": "pre-install script",
"handler": "microsoft/script:1",
"handlerProperties": {
"arguments": "--pre-install"
},
"files": [
"configure.sh"
]
},
{
"description": "firmware package",
"handler": "microsoft/swupdate:2",
"files": [
"contoso.toaster.1.0.swu"
]
}
]
}
}
Una actualización puede contener pasos de referencia que indican al agente de dispositivo que instale otra actualización con su propio manifiesto de importación, estableciendo una relación de actualización primaria y secundaria. Una actualización puede contener cualquier combinación de pasos insertados y de referencia.
Por ejemplo, una actualización para Toaster puede contener dos actualizaciones secundarias:
{
"instructions": {
"steps": [
{
"type": "reference",
"updateId": {
"provider": "Contoso",
"name": "Toaster.HeatingElement",
"version": "1.0"
}
},
{
"type": "reference",
"updateId": {
"provider": "Contoso",
"name": "Toaster.Sensors",
"version": "1.0"
}
}
]
}
}
Archivos
La sección Archivos del manifiesto de importación contiene metadatos de archivo de carga de actualización como name, size y hash. Device Update usa estos metadatos para la validación de integridad durante el proceso de importación y reenvía la misma información al agente de dispositivo para la validación de integridad antes de la instalación.
Nota:
Una actualización primaria que contiene solo los pasos de referencia no define ningún archivo de carga de actualización.
Creación de un manifiesto de importación
Aunque es posible crear manualmente un JSON de manifiesto de importación mediante un editor de texto, la CLI de Azure simplifica considerablemente el proceso. Cuando esté listo para probar la creación de un manifiesto de importación, puede usar la guía paso a paso.
Importante
Para importar en el servicio Device Update a través de Azure Portal, un nombre de archivo JSON de manifiesto de importación debe terminar con .importmanifest.json.
Sugerencia
Puede usar Visual Studio Code para habilitar la validación de esquemas JSON y el autocompletado al crear un manifiesto de importación.
Actualizar los límites de importación
En todas las instancias de Device Update for IoT Hub, se aplican los determinados límites. Si aún no los ha revisado, consulte Límites de actualización de dispositivos.