Importation de mises à jour dans Device Update pour IoT Hub

  • Article

Pour déployer une mise à jour sur des appareils à partir de Device Update pour IoT Hub, vous devez d’abord importer cette mise à jour dans le service Device Update. La mise à jour importée est stockée dans le service Device Update, d’où elle peut être déployée sur les appareils. Cet article propose une vue d’ensemble de certains concepts importants à comprendre en ce qui concerne l’importation de mises à jour.

Manifeste d’importation

Un manifeste d’importation est un fichier JSON qui définit des informations importantes sur la mise à jour que vous importez. Vous soumettez à la fois votre manifeste d’importation et le ou les fichiers de mise à jour associés (par exemple, un package de mise à jour de microprogramme) dans le cadre du processus d’importation. Les métadonnées définies dans ce manifeste d’importation sont utilisées pour l’ingestion de la mise à jour. Certaines métadonnées sont également utilisées au moment du déploiement, par exemple, pour vérifier si une mise à jour a été correctement installée.

Par exemple :

{
  "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"
}

Le manifeste d’importation contient plusieurs éléments qui représentent des concepts importants de Device Update pour IoT Hub. Ces éléments sont décrits dans cette section. Pour plus d’informations sur le schéma d’importation complet, consultez Schéma JSON du manifeste d’importation.

Identité de la mise à jour

L’élément update identity ou updateId correspond à l’identificateur unique dd'une mise à jour dans Device Update pour IoT Hub. Cet identificateur se compose de trois parties :

  • Fournisseur : entité qui crée ou qui est directement responsable de la mise à jour. Souvent, il s’agit d’un nom d’entreprise.
  • Nom : identificateur d’une classe de mises à jour. Il s’agit souvent d’un nom de classe ou de modèle d’appareil.
  • Version : numéro de version permettant de différencier cette mise à jour d’autres mises à jour ayant le même fournisseur et le même nom.

Par exemple :

{
  "updateId": {
    "provider": "Contoso",
    "name": "Toaster",
    "version": "1.0"
  }
}

Notes

UpdateId est uniquement utilisé par le service Device Update et peut être différent des identités du composant logiciel installé sur l’appareil.

Compatibilité

La partie compatibility définit les critères que doit remplir un appareil pour installer la mise à jour. Elle contient des propriétés d’appareil correspondant à un ensemble de paires clé-valeur arbitraires qui sont signalées à partir d’un appareil. Seuls les appareils avec les propriétés correspondantes sont éligibles pour le déploiement. Une mise à jour peut être compatible avec plusieurs classes d’appareils si elle propose plusieurs ensembles de propriétés d’appareil.

Voici un exemple de mise à jour qui ne peut être déployée que sur un appareil qui signale Contoso et Toaster comme fabricant et modèle d’appareil.

{
  "compatibility": [
    {
      "manufacturer": "Contoso",
      "model": "Toaster"
    }
  ]
}

Instructions

La partie instructions contient les informations ou les étapes (steps) dont a besoin l’agent de l’appareil pour installer la mise à jour. La mise à jour la plus simple contient une seule étape inlined. Cette étape exécute le fichier de charge utile inclus avec un gestionnaire (handler) inscrit auprès de l’agent de l’appareil :

{
  "instructions": {
    "steps": [
      {
        "handler": "microsoft/swupdate:1",
        "files": [
          "contoso.toaster.1.0.swu"
        ]
      }
    ]
  }
}

Conseil

handler équivaut à updateType dans le manifeste d’importation version 3.0 ou ultérieure.

Une mise à jour peut contenir plusieurs étapes :

{
  "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"
        ]
      }
    ]
  }
}

Une mise à jour peut contenir une étape de référence (reference) qui indique à l’agent de l’appareil d’installer une autre mise à jour avec son propre manifeste d’importation, établissant ainsi une relation de mise à jour parent et enfant. Par exemple, une mise à jour pour un toaster peut contenir deux mises à jour enfants :

{
  "instructions": {
    "steps": [
      {
        "type": "reference",
        "updateId": {
          "provider": "Contoso",
          "name": "Toaster.HeatingElement",
          "version": "1.0"
        }
      },
      {
        "type": "reference",
        "updateId": {
          "provider": "Contoso",
          "name": "Toaster.Sensors",
          "version": "1.0"
        }
      }
    ]
  }
}

Notes

Une mise à jour peut contenir n’importe quelle combinaison d’étapes inlined et de référence.

Fichiers

La partie files contient les métadonnées des fichiers de charge utile de la mise à jour (nom, taille, hachage, etc.). Device Update pour IoT Hub utilise ces métadonnées pour valider l’intégrité lors du processus d’importation. Les mêmes informations sont ensuite transférées à l’agent de l’appareil pour répéter la validation de l’intégrité avant l’installation.

Notes

Une mise à jour qui contient uniquement des étapes de référence uniquement n’aura aucun fichier de charge utile de mise à jour dans la mise à jour parente.

Créer un manifeste d’importation

Même s’il est possible de créer manuellement du code JSON de manifeste d’importation à l’aide d’un éditeur de texte, l’interface CLI Azure simplifie considérablement ce processus. Lorsque vous serez prêt à tester la création d’un manifeste d’importation, vous pourrez utiliser le guide pratique.

Important

Le nom de fichier JSON du manifeste d’importation doit se terminer par .importmanifest.json s’il est importé par le biais du portail Azure.

Conseil

Utilisez Visual Studio Code pour activer l’autocomplétion et la validation du schéma JSON lors de la création d’un manifeste d’importation.

Limites sur l’importation des mises à jour

Certaines limites sont appliquées pour chaque instance Device Update pour IoT Hub. Si vous ne l’avez pas déjà fait, consultez Limites de Device Update.

Étapes suivantes