Verwenden des Features „Zugehörige Dateien“ zum Verweisen auf mehrere Updatedateien

Verwenden Sie das Feature „Zugehörige Dateien“, wenn Sie Beziehungen zwischen verschiedenen Updatedateien in einem einzelnen Update ausdrücken müssen.

Beim Importieren eines Updates in Device Update for IoT Hub ist ein Importmanifest erforderlich, das Metadaten zum Aktualisieren von Nutzdaten enthält. Die Metadaten auf Dateiebene im Importmanifest können im einfachsten Fall eine flache Liste von Update-Nutzdaten sein. Bei komplexeren Szenarien bietet Ihnen das Feature „Zugehörige Dateien“ jedoch eine Möglichkeit zur Angabe von Beziehungen zwischen mehreren Updatedateien.

Beim Erstellen eines Importmanifests mit dem Feature „Zugehörige Dateien“ können Sie einer oder mehreren Ihrer primären Nutzdaten eine Sammlung zugehöriger Dateien hinzufügen. Ein Beispiel für dieses Konzept ist das Device Update-Feature Deltaupdate, das zugehörige Dateien verwendet, um ein Deltaupdate anzugeben, das einer vollständigen Imagedatei zugeordnet ist. Im Delta-Szenario ermöglicht das Feature „Zugehörige Dateien“ das Importieren des vollständigen Images und des Deltaupdates als einzelne Updateaktion. Beides kann dann auf einem Gerät bereitgestellt werden. Das Feature „Zugehörige Dateien“ ist jedoch nicht auf Deltaupdates beschränkt, da es von unseren Kunden je nach ihren eigenen eindeutigen Szenarien erweiterbar ist.

Definieren von zugehörigen Dateien

Das Feature „Zugehörige Dateien“ ist für Importmanifeste der Version 5 oder höher verfügbar.

Wenn Sie einem Importmanifest zugehörige Dateien hinzufügen, beziehen Sie die folgenden Informationen mit ein:

• Dateidetails

  Definieren Sie die zugehörigen Dateien, indem Sie den Dateinamen, die Größe und den Hash angeben.

• Ein Downloadhandler

  Geben Sie an, wie diese verwandten Dateien zum Erzeugen der Zieldatei verarbeitet werden sollen. Sie geben den Verarbeitungsansatz an, indem Sie eine downloadHandler-Eigenschaft in Ihr Importmanifest einschließen. Das Einschließen von downloadHandler ist erforderlich, wenn Sie eine nicht leere Auflistung von relatedFiles in einem file-Element angeben. Sie können eine downloadHandler mithilfe einer einfachen id-Eigenschaft angeben. Der Downloadhandler id ist auf 64 ASCII-Zeichen beschränkt.

• Eigenschaften zugehöriger Dateien

  Sie können zusätzliche Metadaten für den Updatehandler auf Ihrem Gerät bereitstellen, um zu wissen, wie die Dateien, die Sie als zugehörige Dateien angegeben haben, interpretiert und ordnungsgemäß verwendet werden. Diese Metadaten werden als Teil einer properties-Eigenschaftensammlung zu den Objekten file und relatedFile hinzugefügt.

Weitere Informationen zum Importschema für zugehörige Dateien finden Sie unter „relatedFiles“-Objekt.

Beispiel für ein Importmanifest mit zugehörigen Dateien

Im folgenden Beispiel für ein Importmanifest wird veranschaulicht, wie das Feature „Zugehörige Dateien“ zum Importieren eines Delta-Updates verwendet wird. In diesem Beispiel sehen Sie, dass im Abschnitt files ein vollständiges Image (full-image-file-name) mit einem properties-Element angegeben ist. Das properties-Element wiederum enthält ein zugeordnetes relatedFiles-Element darunter. Im Abschnitt relatedFiles sehen Sie einen weiteren Abschnitt properties für die Delta-Updatedatei (delta-from-v1-file-name) und ein downloadHandler-Element mit dem entsprechenden aufgelisteten id (microsoft/delta:1).

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

Beispiel für einen „init“-Befehl mit zugehörigen Dateien

Der Befehl az iot du init v5 zum Erstellen eines Importmanifests unterstützt einen optionalen --related-file-Parameter.

Für den Parameter --related-file wird ein path- und ein properties-Schlüssel verwendet:

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

Beispiel:

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ächste Schritte

• Informationen zum Importmanifest-Schema
• Informationen zu Deltaupdates