Manifiesto APT de Device Update

  • Artículo

El manifiesto APT es un archivo JSON en el que se describen los detalles de una actualización que necesita el controlador de actualización APT. Este archivo se puede importar en Device Update para IoT Hub igual que cualquier otra actualización.

Para obtener más información, consulte Importación de una actualización a Device Update for IoT Hub.

Información general

Cuando un manifiesto APT se entrega a un agente de Device Update como una actualización, el agente procesa el manifiesto y lleva a cabo las operaciones necesarias. Estas operaciones incluyen la descarga y la instalación de los paquetes especificados en el archivo de manifiesto APT y sus dependencias desde un repositorio designado.

Device Update admite UpdateType APT y el controlador de actualización APT. Esta compatibilidad permite al agente de Device Update evaluar los paquetes de Debian instalados y actualizar los paquetes necesarios.

Schema

Un archivo de manifiesto APT es un archivo JSON que incluye un esquema con versiones.

{
    "name": "<name>",
    "version": "<version>",
    "packages": [
        {
            "name": "<package name>",
            "version": "<version specifier>"
        }
    ]
}

Por ejemplo:

{
    "name": "contoso-iot-edge",
    "version": "1.0.0.0",
    "packages": [
        {
            "name" : "thermocontrol",
            "version" : "1.0.1"
        },
        {
            "name" : "tempreport",
            "version" : "2.0.0"
        }
    ]
}

Cada manifiesto APT incluye las propiedades siguientes:

  • Nombre: nombre de este manifiesto APT. Puede ser cualquier nombre o identificador significativo para sus escenarios. Por ejemplo, contoso-iot-edge.
  • Version: número de versión de este manifiesto APT. Por ejemplo, 1.0.0.0.
  • Paquetes: lista de objetos que contiene propiedades específicas de los paquetes.
    • nombre: nombre o identificador del paquete. Por ejemplo, iotedge.
    • Versión: criterios de versión deseados para el paquete. Por ejemplo, 1.0.8-2. El valor de versión no debe contener un signo igual. Si se omite la versión, se instalará la última versión disponible del paquete especificado.

Actualmente solo se admite el número de versión exacto. El número de versión es la versión deseada del paquete de Debian en formato [epoch:]upstream_version[-debian_revision], donde epoch es un entero sin signo y upstream_version puede incluir caracteres alfanuméricos y caracteres como ".","+","-" y "~". Debe empezar por un dígito.

Nota

"1.0.8" es igual a "1.0.8-0".

Por ejemplo, "name":"iotedge" y "version":"1.0.8-2" es equivalente a instalar un paquete mediante el comando apt-get install iotedge=1.0.8-2.

Para obtener más información sobre cómo se controlan las versiones de los paquetes de Debian, consulte el manual de directivas de Debian

Nota

El administrador de paquetes APT omite los requisitos de control de versiones que indica un paquete cuando los paquetes dependientes que se van a instalar se resuelven automáticamente. A menos que se proporcionen versiones explícitas de los paquetes dependientes, se usará la más reciente, aunque el propio paquete pueda especificar un requisito estricto (=) en una versión determinada. Esta resolución automática puede provocar errores relacionados con una dependencia que no se ha cumplido. Más información

Si va a actualizar una versión específica del demonio de seguridad de Azure IoT Edge, debe incluir la versión deseada del paquete aziot-edge y su paquete aziot-identity-service dependiente en el manifiesto APT. Para más información, consulte Actualización de IoT Edge.

Se puede usar un manifiesto APT para actualizar el agente de Device Update y sus dependencias. Enumere el nombre del agente de Device Update y la versión deseada en el manifiesto APT, como lo haría con cualquier otro paquete. Este manifiesto APT se puede importar e implementar a través de la canalización de Device Update para IoT Hub.

Eliminación de paquetes

También puede usar un manifiesto APT para quitar paquetes instalados del dispositivo. Se puede usar un único manifiesto APT para quitar, agregar y actualizar varios paquetes.

Para quitar un paquete, agregue un signo menos "-" después del nombre del paquete. No debe incluir ningún número de versión para los paquetes que va a quitar. La eliminación de un paquete mediante un manifiesto APT no quita sus dependencias ni configuraciones.

Por ejemplo:

{
    "name": "contoso-video",
    "version": "2.0.0.1",
    "packages": [
        {
            "name" : "foo-"
        }
    ]
}

Este manifiesto APT quitará el paquete "foo" de los dispositivos en los que se implementa.

Los criterios instalados de un manifiesto APT es <name>-<version> donde <name> es el nombre del manifiesto APT y <version> es la versión del manifiesto APT. Por ejemplo, contoso-iot-edge-1.0.0.0.

Directrices para crear un manifiesto APT

Al crear el manifiesto APT, hay algunas instrucciones que se deben tener en cuenta:

  • Asegúrese siempre de que el manifiesto APT sea un archivo JSON con el formato correcto.
  • Cada manifiesto APT debe tener una versión única. Intente crear una metodología normalizada para incrementar la versión del manifiesto APT, de modo que tenga sentido para sus escenarios y se pueda seguir fácilmente.
  • En cuanto al estado deseado de cada paquete individual, especifique el nombre exacto y la versión del paquete que desea instalar en el dispositivo. Valide siempre los valores en el repositorio de paquetes que desea utilizar como origen del paquete.
  • Asegúrese de que los paquetes del manifiesto APT aparecen en el orden en que se deben instalar o quitar.
  • Valide siempre la instalación de paquetes en un dispositivo de prueba para asegurarse de que el resultado es el previsto.
  • Al instalar una versión específica de un paquete (por ejemplo, iotedge 1.0.9-1), se recomienda tener también en el manifiesto APT las versiones explícitas de los paquetes dependientes que se van a instalar (por ejemplo, libiothsm 1.0.9-1).
  • Aunque no es obligatorio, asegúrese siempre de que el manifiesto APT sea acumulativo para evitar que el dispositivo tenga un estado desconocido. Una actualización acumulativa garantizará que los dispositivos tengan la versión deseada de cada paquete que le interese, aunque el dispositivo haya omitido una implementación de actualización APT debido a un error en la instalación o se haya desconectado.

Por ejemplo:

Manifiesto APT base

{
    "name": "contoso-iot-edge",
    "version": "1.0",
    "packages": [
        {
            "name": "foo",
            "version": "1.0.1"
        }
    ]
}

Actualización incorrecta

Esta actualización incluye el paquete bar, pero no el paquete foo.

{
    "name": "contoso-iot-edge",
    "version": "2.0",
    "packages": [
        {
            "name": "bar",
            "version": "3.0.2"
        }
    ]
}

Actualización correcta

Esta actualización incluye el paquete foo y también el paquete bar.

{
    "name": "contoso-iot-edge",
    "version": "2.0",
    "packages": [
        {
            "name": "foo",
            "version": "1.0.1"
        },
        {
            "name": "bar",
            "version": "3.0.2"
        }
    ]
}

Pasos siguientes

Importación de una actualización a Device Update