Använd funktionen relaterade filer för att referera till flera uppdateringsfiler

  • Artikel

Använd funktionen relaterade filer när du behöver uttrycka relationer mellan olika uppdateringsfiler i en enda uppdatering.

När du importerar en uppdatering till Enhetsuppdatering för IoT Hub krävs ett importmanifest som innehåller metadata om uppdateringsnyttolasten. Metadata på filnivå i importmanifestet kan vara en platt lista över uppdateringsnyttolastfiler i det enklaste fallet. För mer avancerade scenarier är dock funktionen relaterade filer ett sätt för dig att ange relationer mellan flera uppdateringsfiler.

När du skapar ett importmanifest med hjälp av funktionen relaterade filer kan du lägga till en samling relaterade filer till en eller flera av dina primära nyttolastfiler. Ett exempel på det här konceptet är deltauppdateringsfunktionen enhetsuppdatering, som använder relaterade filer för att ange en deltauppdatering som är associerad med en fullständig bildfil. I deltascenariot gör funktionen relaterade filer att den fullständiga avbildningen och deltauppdateringen kan importeras som en enda uppdateringsåtgärd, och sedan kan någon av dem distribueras till en enhet. Funktionen relaterade filer är dock inte begränsad till deltauppdateringar, eftersom den är utformad för att vara utökningsbar för våra kunder beroende på deras egna unika scenarier.

Funktionen relaterade filer är tillgänglig för importmanifest som är version 5 eller senare.

När du lägger till relaterade filer i ett importmanifest ska du inkludera följande information:

  • Filinformation

    Definiera relaterade filer genom att ange filnamn, storlek och hash.

  • En nedladdningshanterare

    Ange hur dessa relaterade filer ska bearbetas för att skapa målfilen. Du anger bearbetningsmetod genom att inkludera en downloadHandler egenskap i importmanifestet. Du måste inkludera downloadHandler om du anger en icke-tom samling i relatedFiles ett file element. Du kan ange en downloadHandler med hjälp av en enkel id egenskap. Nedladdningshanteraren id har en gräns på 64 ASCII-tecken.

  • Egenskaper för relaterade filer

    Du kan ange extra metadata för uppdateringshanteraren på enheten för att veta hur du tolkar och korrekt använder de filer som du har angett som relaterade filer. Dessa metadata läggs till som en del av en properties egenskapsuppsättning till objekten file och relatedFile .

Mer information om importschemat för relaterade filer finns i relatedFiles-objekt.

Följande exempelimportmanifest visar hur funktionen relaterade filer används för att importera en deltauppdatering. I det här exemplet kan du se att det i files avsnittet finns en fullständig bild angiven (full-image-file-name) med ett properties objekt. Objektet properties har i sin tur ett associerat relatedFiles objekt under sig. I avsnittet relatedFiles kan du se ett annat properties avsnitt för deltauppdateringsfilen (delta-from-v1-file-name), och även ett downloadHandler objekt med lämplig id lista (microsoft/delta:1).

Anteckning

I det här exemplet används deltauppdateringar för att visa hur du refererar till relaterade filer. Om du vill använda deltauppdateringar som en funktion kan du läsa mer i deltauppdateringsdokumentationen.

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

Kommandot az iot du init v5 för att skapa ett importmanifest stöder en valfri --related-file parameter.

Parametern --related-file tar en path och-nyckel 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>"}'

Exempel:

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

Nästa steg