Używanie funkcji powiązanych plików do odwołwania się do wielu plików aktualizacji

  • Artykuł

Użyj funkcji powiązanych plików, jeśli musisz wyrazić relacje między różnymi plikami aktualizacji w jednej aktualizacji.

Podczas importowania aktualizacji do usługi Device Update dla IoT Hub wymagany jest manifest importu zawierający metadane dotyczące ładunku aktualizacji. Metadane na poziomie pliku w manifeście importu mogą być płaską listą plików ładunku aktualizacji w najprostszym przypadku. Jednak w przypadku bardziej zaawansowanych scenariuszy funkcja powiązanych plików umożliwia określenie relacji między wieloma plikami aktualizacji.

Podczas tworzenia manifestu importu przy użyciu funkcji powiązanych plików można dodać kolekcję powiązanych plików do co najmniej jednego podstawowego pliku ładunku. Przykładem tej koncepcji jest funkcja aktualizacji różnicowej aktualizacji urządzenia, która używa powiązanych plików do określenia aktualizacji różnicowej skojarzonej z pełnym plikiem obrazu. W scenariuszu różnicowym funkcja powiązanych plików umożliwia zaimportowanie pełnego obrazu i aktualizacji różnicowej jako akcji pojedynczej aktualizacji, a następnie wdrożenie jednej z nich na urządzeniu. Jednak funkcja powiązanych plików nie jest ograniczona do aktualizacji różnicowych, ponieważ jest przeznaczona do rozszerzania przez naszych klientów w zależności od własnych unikatowych scenariuszy.

Funkcja powiązanych plików jest dostępna dla manifestów importu, które są w wersji 5 lub nowszej.

Podczas dodawania powiązanych plików do manifestu importu dołącz następujące informacje:

  • Szczegóły pliku

    Zdefiniuj powiązane pliki, podając nazwę pliku, rozmiar i skrót.

  • Procedura obsługi pobierania

    Określ sposób przetwarzania tych powiązanych plików w celu utworzenia pliku docelowego. Należy określić podejście przetwarzania, dołączając downloadHandler właściwość w manifeście importu. Uwzględnianie downloadHandler jest wymagane, jeśli określisz niepustą kolekcję relatedFiles elementu file . Można określić downloadHandler przy użyciu prostej id właściwości. Procedura obsługi id pobierania ma limit 64 znaków ASCII.

  • Właściwości powiązanych plików

    Możesz podać dodatkowe metadane programu obsługi aktualizacji na urządzeniu, aby wiedzieć, jak interpretować i prawidłowo używać plików określonych jako powiązane pliki. Te metadane są dodawane jako część properties torby właściwości do file obiektów i relatedFile .

Aby uzyskać więcej informacji na temat schematu importu dla powiązanych plików, zobacz relatedFiles object (Obiekt relatedFiles).

Poniższy przykładowy manifest importu pokazuje, jak funkcja powiązanych plików jest używana do importowania aktualizacji różnicowej. W tym przykładzie files widać, że w sekcji jest określony pełny obraz (full-image-file-name) z elementem properties . Element properties z kolei zawiera skojarzony relatedFiles element. relatedFiles W sekcji można zobaczyć inną properties sekcję pliku aktualizacji różnicowej (delta-from-v1-file-name), a także downloadHandler element z odpowiednią id listy (microsoft/delta:1).

Uwaga

W tym przykładzie użyto aktualizacji różnicowych, aby zademonstrować sposób odwołwania się do powiązanych plików. Jeśli chcesz użyć aktualizacji różnicowych jako funkcji, dowiedz się więcej w dokumentacji aktualizacji różnicowej.

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

Polecenie az iot du init v5 do tworzenia manifestu importu obsługuje opcjonalny --related-file parametr.

Parametr --related-file przyjmuje path klucz i 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>"}'

Przykład:

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

Następne kroki