Manifeste apt Device Update

  • Article

Le manifeste apt est un fichier JSON qui décrit les détails d’une mise à jour dont le gestionnaire de mise à jour apt a besoin. Ce fichier peut être importé dans Device Update pour IoT Hub comme n’importe quelle autre mise à jour.

Pour plus d’informations, consultez Importer une mise à jour vers Device Update pour IoT Hub.

Vue d’ensemble

Quand un manifeste apt est délivré à un agent Device Update en tant que mise à jour, l’agent traite le manifeste et effectue les opérations nécessaires. Ces opérations incluent le téléchargement et l’installation des packages spécifiés dans le fichier manifeste apt et leurs dépendances à partir d’un référentiel désigné.

Device Update prend en charge apt UpdateType et le gestionnaire de mise à jour apt. Cette prise en charge permet à l’agent Device Update d’évaluer les packages Debian installés et de mettre à jour les packages nécessaires.

schéma

Un fichier manifeste apt est un fichier JSON avec un schéma versionné.

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

Par exemple :

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

Chaque manifeste apt inclut les propriétés suivantes :

  • Name : Nom de ce manifeste apt. Il peut s’agir de n’importe quel nom ou ID significatif pour vos scénarios. Par exemple : contoso-iot-edge.
  • Version : Numéro de version pour ce manifeste apt. Par exemple : 1.0.0.0.
  • Packages : Liste d’objets contenant des propriétés spécifiques au package.
    • Nom : Nom ou ID du package. Par exemple : iotedge.
    • Version : Les critères de la version souhaitée pour le package. Par exemple : 1.0.8-2. La valeur de version ne doit pas contenir de signe égal. Si la version est omise, la dernière version disponible du package spécifié sera installée.

Actuellement, seul le numéro de version exact est pris en charge. Le numéro de version est la version souhaitée du paquet Debian au format [epoch:]upstream_version[-debian_revision], où epoch est un int non signé et upstream_version peut inclure des caractères alphanumériques et des caractères tels que « . », « + », « - » et « ~ ». Il doit commencer par un chiffre.

Notes

« 1.0.8 » équivaut à « 1.0.8-0 »

Par exemple, "name":"iotedge" et "version":"1.0.8-2" équivaut à installer un package en utilisant la commande apt-get install iotedge=1.0.8-2

Pour plus d’informations sur la façon dont les packages Debian sont versionnés, consultez le manuel de stratégie Debian

Notes

Le gestionnaire de package apt ignore les spécifications de version données par un package quand les packages dépendants à installer sont résolus automatiquement. À moins que des versions explicites des packages dépendants ne soient fournies, elles utiliseront la dernière version, même si le package lui-même peut spécifier une exigence stricte (=) sur une version donnée. Cette résolution automatique peut entraîner des erreurs concernant une dépendance non satisfaite. En savoir plus

Si vous mettez à jour une version spécifique du démon de sécurité d’Azure IoT Edge, vous devez inclure la version souhaitée du package aziot-edge et son package dépendant aziot-identity-service dans votre manifeste apt. Pour plus d’informations, consultez Comment mettre à jour IoT Edge.

Un manifeste APT peut être utilisé pour mettre à jour l’agent Device Update et ses dépendances. Spécifiez le nom et la version souhaitée de l’agent Device Update dans le manifeste APT, comme vous le feriez pour n’importe quel autre package. Ce manifeste APT peut ensuite être importé et déployé via le pipeline Device Update pour IoT Hub.

Suppression de packages

Vous pouvez aussi utiliser un manifeste APT pour supprimer des packages installés de votre appareil. Un même manifeste apt peut être utilisé pour supprimer, ajouter et mettre à jour plusieurs packages.

Pour supprimer un package, ajoutez un signe moins « - » après le nom du package. Vous ne devez pas inclure un numéro de version pour les packages que vous supprimez. La suppression d’un package via un manifeste apt ne supprime pas ses dépendances ni ses configurations.

Par exemple :

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

Ce manifeste apt va supprimer le package « foo » du ou des appareils sur lesquels il est déployé.

Le critère installé pour un manifeste apt est <name>-<version>, où <name> est le nom du manifeste apt et <version> est la version du manifeste apt. Par exemple : contoso-iot-edge-1.0.0.0.

Instructions pour la création d’un manifeste apt

Lors de la création du manifeste apt, tenez compte des instructions suivantes :

  • Vérifiez toujours que le manifeste apt est un fichier JSON bien formé.
  • Chaque manifeste apt doit avoir une version unique. Essayez de trouver une méthodologie standardisée pour incrémenter la version du manifeste apt, afin qu’il soit logique pour vos scénarios et puisse être facilement suivi.
  • Quand il s’agit de l’état souhaité de chaque package individuel, spécifiez le nom et la version exacts du package que vous voulez installer sur votre appareil. Vérifiez toujours les valeurs par rapport au référentiel de packages que vous prévoyez d’utiliser comme source pour le package.
  • Vérifiez que les packages du manifeste apt sont listés dans l’ordre où ils doivent être installés/supprimés.
  • Vérifiez toujours l’installation des packages sur un appareil de test pour être sûr que le résultat est bien ce que vous souhaitez.
  • Lors de l’installation d’une version spécifique d’un package (par exemple iotedge 1.0.9-1), c’est une bonne pratique que d’avoir aussi dans le manifeste apt les versions explicites des packages dépendants à installer (par exemple libiothsm 1.0.9-1).
  • Bien que ce ne soit pas obligatoire, vérifiez toujours que votre manifeste apt est cumulatif pour éviter de placer votre appareil dans un état inconnu. Une mise à jour cumulative garantit que vos appareils disposent de la version souhaitée de chaque package qui vous intéresse, même si l’appareil a ignoré un déploiement de mise à jour apt en raison d’une défaillance dans l’installation ou en cas de déconnexion.

Par exemple :

Manifeste apt de base

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

Mise à jour incorrecte

Cette mise à jour inclut le package « bar », mais pas le package « foo ».

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

Mise à jour correcte

Cette mise à jour inclut le package « foo » et inclut également le package « bar ».

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

Étapes suivantes

Importer une mise à jour dans Mise à jour d’appareil