Importación de actualizaciones a Device Update para IoT Hub

  • Artículo

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