Share via

De functie gerelateerde bestanden gebruiken om te verwijzen naar meerdere updatebestanden

  • Artikel

Gebruik de functie gerelateerde bestanden wanneer u relaties tussen verschillende updatebestanden in één update wilt uitdrukken.

Wanneer u een update importeert naar Device Update for IoT Hub, is een importmanifest met metagegevens over de nettolading van de update vereist. De metagegevens op bestandsniveau in het importmanifest kunnen in het eenvoudigste geval een platte lijst met nettoladingbestanden van updates zijn. Voor geavanceerdere scenario's biedt de functie gerelateerde bestanden echter een manier om relaties tussen meerdere updatebestanden op te geven.

Wanneer u een importmanifest maakt met behulp van de functie gerelateerde bestanden, kunt u een verzameling gerelateerde bestanden toevoegen aan een of meer van uw primaire nettoladingbestanden. Een voorbeeld van dit concept is de delta-updatefunctie Device Update, die gerelateerde bestanden gebruikt om een delta-update op te geven die is gekoppeld aan een volledig afbeeldingsbestand. In het delta-scenario kunnen met de functie gerelateerde bestanden de volledige installatiekopie en delta-update worden geïmporteerd als één updateactie, waarna een van beide kan worden geïmplementeerd op een apparaat. De functie gerelateerde bestanden is echter niet beperkt tot delta-updates, omdat deze is ontworpen om door onze klanten te worden uitgebreid, afhankelijk van hun eigen unieke scenario's.

De functie gerelateerde bestanden is beschikbaar voor importmanifesten die versie 5 of hoger zijn.

Wanneer u gerelateerde bestanden toevoegt aan een importmanifest, moet u de volgende informatie opnemen:

  • Details van bestand

    Definieer de gerelateerde bestanden door de bestandsnaam, grootte en hash op te geven.

  • Een downloadhandler

    Geef op hoe deze gerelateerde bestanden moeten worden verwerkt om het doelbestand te produceren. U geeft de verwerkingsbenadering op door een downloadHandler eigenschap op te slaan in uw importmanifest. Opnemen downloadHandler is vereist als u een niet-lege verzameling van relatedFiles in een file element opgeeft. U kunt een downloadHandler opgeven met behulp van een eenvoudige id eigenschap. De downloadhandler id heeft een limiet van 64 ASCII-tekens.

  • Eigenschappen van gerelateerde bestanden

    U kunt extra metagegevens opgeven voor de update-handler op uw apparaat om te weten hoe u de bestanden die u als gerelateerde bestanden hebt opgegeven, moet interpreteren en correct gebruiken. Deze metagegevens worden toegevoegd als onderdeel van een properties eigenschappenverzameling aan de file objecten en relatedFile .

Zie relatedFiles-object voor meer informatie over het importschema voor gerelateerde bestanden.

In het volgende voorbeeld van een importmanifest ziet u hoe de functie gerelateerde bestanden wordt gebruikt voor het importeren van een delta-update. In dit voorbeeld ziet u dat in de files sectie een volledige afbeelding is opgegeven (full-image-file-name) met een properties item. Het properties item heeft op zijn beurt een gekoppeld relatedFiles item eronder. In de relatedFiles sectie ziet u een andere properties sectie voor het delta-updatebestand (delta-from-v1-file-name) en ook een downloadHandler item met de juiste id lijst (microsoft/delta:1).

Notitie

In dit voorbeeld worden delta-updates gebruikt om te laten zien hoe u naar gerelateerde bestanden kunt verwijzen. Als u delta-updates als functie wilt gebruiken, vindt u meer informatie in de documentatie voor delta-updates.

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

De opdracht az iot du init v5 voor het maken van een importmanifest ondersteunt een optionele --related-file parameter.

Voor --related-file de parameter wordt een path en-sleutel properties gebruikt:

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

Bijvoorbeeld:

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

Volgende stappen