Utiliser la fonctionnalité de fichiers associés pour référencer plusieurs fichiers de mise à jour

  • Article

Utilisez la fonctionnalité de fichiers associés lorsque vous devez définir les relations entre différents fichiers de mise à jour dans une seule mise à jour.

Lors de l’importation d’une mise à jour vers Device Update pour IoT Hub, un manifeste d’importation contenant les métadonnées de la charge utile de mise à jour est utilisé. Dans le manifeste d’importation, les métadonnées au niveau des fichiers peuvent consister en une liste plate des fichiers de la charge utile de mise à jour, dans le cas le plus simple. Toutefois, pour les scénarios plus avancés, la fonctionnalité de fichiers associés vous permet de spécifier des relations entre plusieurs fichiers de mise à jour.

Quand vous créez un manifeste d’importation à l’aide de la fonctionnalité de fichiers associés, vous pouvez ajouter une collection de fichiers associés à un ou plusieurs de vos fichiers de charge utile principaux. La fonctionnalité de mise à jour delta dans Device Update est un exemple de ce concept. Elle utilise des fichiers associés pour spécifier une mise à jour delta qui est associée à un fichier image complet. Dans le scénario delta, la fonctionnalité de fichiers associés permet d’importer l’image complète et la mise à jour delta en tant qu’action de mise à jour unique, puis de déployer l’une ou l’autre sur un appareil. La fonctionnalité de fichiers associés ne se limite toutefois pas aux mises à jour delta, car elle est conçue pour être adaptée par nos clients en fonction de leurs propres scénarios uniques.

La fonctionnalité de fichiers associés est disponible pour les manifestes d’importation de version 5 ou ultérieure.

Quand vous ajoutez des fichiers associés à un manifeste d’importation, incluez les informations suivantes :

  • Détails du fichier

    Définissez les fichiers associés en fournissant le nom de fichier, la taille et le hachage.

  • Un gestionnaire de téléchargement

    Spécifiez comment traiter ces fichiers associés pour produire le fichier cible. Vous spécifiez l’approche de traitement en incluant une propriété downloadHandler dans votre manifeste d’importation. Vous devez obligatoirement inclure downloadHandler si vous spécifiez une collection non vide de relatedFiles dans un élément file. Vous pouvez spécifier un downloadHandler avec une simple propriété id. Le gestionnaire de téléchargement id a une limite de 64 caractères ASCII.

  • Propriétés de fichiers associés

    Vous pouvez fournir des métadonnées supplémentaires pour que le gestionnaire de mise à jour sur votre appareil sache comment interpréter et utiliser correctement les fichiers que vous avez spécifiés en tant que fichiers associés. Ces métadonnées sont ajoutées sous la forme d’un conteneur de propriétés properties dans les objets file et relatedFile.

Pour plus d’informations sur le schéma d’importation des fichiers associés, consultez Objet relatedFiles.

L’exemple de manifeste d’importation suivant montre comment la fonctionnalité de fichiers associés est utilisée pour importer une mise à jour delta. Dans cet exemple, vous voyez que dans la section files, une image complète est spécifiée (full-image-file-name) avec un élément properties. L’élément properties a également un élément relatedFiles associé en dessous de lui. Dans la section relatedFiles, vous voyez une autre section properties pour le fichier de mise à jour delta (delta-from-v1-file-name), ainsi qu’un élément downloadHandler avec l’élément id approprié listé (microsoft/delta:1).

Notes

Cet exemple utilise des mises à jour delta pour montrer comment référencer des fichiers associés. Si vous souhaitez utiliser les mises à jour delta comme fonctionnalité, consultez la documentation sur les mises à jour delta.

    {
      "updateId": {
        // provider, name, version
      },
      "compatibility": [
        {
          // manufacturer, model, etc.
        }
      ],
      "instructions": {
        "steps": [
          // Inline steps...
        ]
      },
      "files": [
        {  
          // standard file properties
          "fileName": "full-image-file-name",
          "sizeInBytes": 12345,
          "hashes": {
            "SHA256": "full-image-file-hash"
          },
          "mimeType": "application/octet-stream",
          // new properties
          "properties  ": {},
          "relatedFiles": [
            {
              // delta from version 1.0.0.0
              // standard file properties
              "fileName": "delta-from-v1-file-name",
              "sizeInBytes": 1234,
              "hashes": {
                "SHA256": "delta-from-v1-file-hash"
              },
              "mimeType": "application/octet-stream",
              // new properties
              "properties": {
                "microsoft.sourceFileHash": "delta-source-file-hash",
                "microsoft.sourceFileHashAlgorithm": "sha256"
              }
            }  
          ],
          // handler to download/process our related files
      "downloadHandler": {
        "id": "microsoft/delta:1"
      }
    }
  ],
  "createdDateTime": "2021-12-01T01:12:21Z",
  "manifestVersion": "5.0"
    }

La commande az iot du init v5 pour la création d’un manifeste d’importation prend en charge un paramètre facultatif --related-file.

Le paramètre --related-file prend un path et une clé properties :

--related-file path=<replace with path(s) to your delta file(s), including the full file name> properties='{"microsoft.sourceFileHashAlgorithm": "sha256", "microsoft.sourceFileHash": "<replace with the source SWU image file hash>"}'

Par exemple :

az iot du update init v5 \
--update-provider Microsoft --update-name myBundled --update-version 2.0 \
--compat manufacturer=Contoso model=SpaceStation \
--step handler=microsoft/script:1 properties='{"arguments": "--pre"}' description="Pre-install script" \
--file path=/my/update/scripts/preinstall.sh downloadHandler=microsoft/delta:1 \
--related-file path=/my/update/scripts/related_preinstall.json properties='{"microsoft.sourceFileHashAlgorithm": "sha256"}' \
--step updateId.provider=Microsoft updateId.name=SwUpdate updateId.version=1.1 \
--step handler=microsoft/script:1 properties='{"arguments": "--post"}' description="Post-install script" \
--file path=/my/update/scripts/postinstall.sh

Étapes suivantes