Importación de actualizaciones a Device Update para IoT Hub
Para implementar una actualización en dispositivos desde Device Update para IoT Hub, primero hay que importar esa actualización al servicio Device Update. La actualización importada se almacenará en el servicio Device Update y se puede implementar desde allí 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. Como parte del proceso de importación, se enviarán el manifiesto de importación y el archivo o archivos de actualización asociado/s (por ejemplo, un paquete de actualización de firmware). Los metadatos definidos en el manifiesto de importación se usarán para ingerir la información de 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 ha instalado correctamente.
Por ejemplo:
{
"updateId": {
"provider": "Contoso",
"name": "Toaster",
"version": "1.0"
},
"isDeployable": false,
"compatibility": [
{
"manufacturer": "Contoso",
"model": "Toaster"
}
],
"instructions": {
"steps": [
{
"handler": "microsoft/swupdate:1",
"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"
}
El manifiesto de importación contiene varios elementos que representan conceptos importantes sobre Device Update para IoT Hub. Estos elementos se esbozan en esta sección. Para obtener información sobre el esquema de importación completo, consulte el artículo sobre el esquema JSON del manifiesto de importación.
Identidad de actualización
La identidad de actualización o updateId es el identificador único de una actualización en Device Update for IoT Hub. Consta de tres partes:
- Proveedor: entidad que está creando la actualización o que es directamente responsable de ella. Suele ser un nombre de empresa.
- Nombre: identificador de una clase de actualizaciones. Suele ser una clase de dispositivo o un nombre de modelo.
- Versión: número de versión que diferencia esta actualización de otras con el mismo proveedor y nombre.
Por ejemplo:
{
"updateId": {
"provider": "Contoso",
"name": "Toaster",
"version": "1.0"
}
}
Nota
UpdateId solo se usa por el servicio Device Update y puede ser diferente de las identidades de los componentes de software reales en el dispositivo.
Compatibilidad
La compatibilidad define los criterios de un dispositivo que puede instalar la actualización. Contiene las propiedades de dispositivo, que son un conjunto de pares de valores de clave arbitrarios que se notifican desde un dispositivo. Solo los dispositivos con propiedades que coincidan serán aptos para la implementación. Una actualización puede ser compatible con varias clases de dispositivos al tener más de un conjunto de propiedades de dispositivo.
Este es un ejemplo de una actualización que solo se puede implementar en un dispositivo que notifica Contoso y Toaster como fabricante y modelo de su dispositivo.
{
"compatibility": [
{
"manufacturer": "Contoso",
"model": "Toaster"
}
]
}
Instrucciones
La parte Instrucciones contiene la información o los pasos necesarios para que el agente de dispositivo instale la actualización. La actualización más sencilla contiene un solo paso en línea. En este paso se ejecuta el archivo de carga incluido mediante un controlador registrado en el agente de dispositivo:
{
"instructions": {
"steps": [
{
"handler": "microsoft/swupdate:1",
"files": [
"contoso.toaster.1.0.swu"
]
}
]
}
}
Sugerencia
handler
es equivalente a updateType
en la versión 3.0 o anterior del manifiesto de importación.
Una actualización puede contener más de un paso:
{
"instructions": {
"steps": [
{
"description": "pre-install script",
"handler": "microsoft/script:1",
"handlerProperties": {
"arguments": "--pre-install"
},
"files": [
"configure.sh"
]
},
{
"description": "firmware package",
"handler": "microsoft/swupdate:1",
"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. 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"
}
}
]
}
}
Nota
Una actualización puede contener cualquier combinación de pasos en línea y de referencia.
Archivos
La parte Archivos contiene los metadatos de los archivos de carga de actualización, como sus nombres, tamaños y hash. Device Update for IoT Hub usa estos metadatos para la validación de integridad durante el proceso de importación. A continuación, se reenvía la misma información al agente de dispositivo para repetir la validación de integridad antes de la instalación.
Nota
Una actualización que contiene solo pasos de referencia no tendrá ningún archivo de carga de actualización en la actualización primaria.
Creación de un manifiesto de importación
Aunque es posible crear manualmente un archivo JSON de manifiesto de importación mediante un editor de texto, la interfaz de línea de comandos (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
El nombre de archivo JSON del manifiesto de importación debe terminar en .importmanifest.json
cuando se importa a través de Azure Portal.
Sugerencia
Use Visual Studio Code para habilitar la validación de esquemas JSON y la función de autocompletar al crear un manifiesto de importación.
Límites en la importación de actualizaciones
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.
Pasos siguientes
- Para obtener más información sobre el proceso de importación, consulte Preparación de una actualización para importarla.
- Revise Esquema del manifiesto de importación.