Freigeben über

Delta-Updates (Vorschau)

  • Artikel

Mit Delta-Updates können Sie kleine Updates generieren, die nur die Änderungen zwischen zwei vollständigen Updates darstellen – ein Quellimage und ein Zielimage. Dieser Ansatz ist ideal, um die Bandbreite für das Herunterladen eines Updates auf ein Gerät zu reduzieren, insbesondere wenn es nur wenige Änderungen zwischen dem Quell- und dem Zielupdate gibt.

Hinweis

Das Feature für Delta-Updates in Azure Device Update for IoT Hub befindet sich derzeit in der öffentlichen Vorschau.

Anforderungen für die Verwendung von Deltaupdates in Device Update for IoT Hub

  • Die Quell- und Zielupdatedateien müssen im SWUpdate-Format (SWU) vorliegen.
  • In jeder SWUpdate-Datei muss ein Rohimage vorhanden sein, das das Ext2-, Ext3- oder Ext4-Dateisystem verwendet.

Beim Prozess der Deltagenerierung wird das SWU-Zielupdate mithilfe der gzip-Komprimierung erneut komprimiert, um ein optimales Delta zu generieren. Sie importieren dieses erneut komprimierte SWU-Zielupdate zusammen mit der generierten Delta-Updatedatei in den Device Update-Dienst.

Konfiguration des Device Update-Agents für die Deltaprozessorkomponente

Um Delta-Updates vom Device Update-Dienst herunterzuladen und zu installieren, muss auf Ihrem Gerät der Device Update-Agent mit dem Updatehandler und der Deltaprozessorkomponente vorhanden und konfiguriert sein.

Device Update-Agent

Der Device Update-Agent orchestriert den Updateprozess auf dem Gerät, einschließlich Download-, Installations- und Neustartaktionen. Informationen zum Hinzufügen und Konfigurieren des Device Update-Agents auf einem Gerät finden Sie unter Bereitstellung des Device Update-Agents. Verwenden Sie Agent Version 1.0 oder höher.

Updatehandler

Ein Updatehandler ist in den Device Update-Agent integriert, um die eigentliche Updateinstallation durchzuführen. Beginnen Sie bei Deltaupdates mit dem microsoft/swupdate:2Updatehandler, wenn Sie noch nicht über einen eigenen SWUpdate-Updatehandler verfügen, den Sie ändern möchten.

Deltaprozessor

Der Deltaprozessor unter Azure/iot-hub-device-update-delta erstellt die ursprüngliche SWU-Imagedatei nach dem Herunterladen der Änderungs- bzw. Deltadatei auf Ihrem Gerät neu, damit Ihr Updatehandler die SWU-Datei installieren kann. Um die Deltaprozessorkomponente zu Ihrem Geräteimage hinzuzufügen und für die Verwendung zu konfigurieren, laden Sie ein Debian-Paket für Ubuntu 20.04 und höher von https://github.com/Azure/iot-hub-device-update-delta/tree/main/preview/2.0.0 herunter.

Wenn Sie eine andere Distribution verwenden, befolgen Sie stattdessen die Anweisungen in der Datei README.md, um den Deltaprozessor mit CMAKE aus der Quelle zu erstellen. Installieren Sie dort direkt das freigegebene Objekt libadudiffapi.so, indem Sie es wie folgt in das Verzeichnis /usr/lib kopieren:

sudo cp <path to libadudiffapi.so> /usr/lib/libadudiffapi.so
sudo ldconfig

Hinzufügen einer SWU-Quellimagedatei zu Ihrem Gerät

Nachdem die Delta-Updatedatei auf ein Gerät heruntergeladen wurde, wird sie mit einem gültigen <source_archive> verglichen, das zuvor auf dem Gerät zwischengespeichert wurde. Dieser Prozess ermöglicht es dem Delta-Update, das vollständige Zielimage neu zu erstellen.

Die einfachste Möglichkeit zum Auffüllen dieses zwischengespeicherten Images besteht darin, über den Device Update-Dienst ein vollständiges Imageupdate auf dem Gerät zu importieren und bereitzustellen. Wenn das Gerät mit Device Update-Agent Version 1.0 oder höher und dem Deltaprozessor konfiguriert ist, speichert der Agent die installierte SWU-Datei automatisch zur späteren Verwendung eines Delta-Updates zwischen.

Wenn Sie das Quellimage stattdessen direkt auf Ihrem Gerät vorausfüllen möchten, wird das Image am Pfad <BASE_SOURCE_DOWNLOAD_CACHE_PATH>/sha256-<ENCODED HASH> erwartet. Standardmäßig ist <BASE_SOURCE_DOWNLOAD_CACHE_PATH> der Pfad /var/lib/adu/sdc/<Anbieter>. Der provider-Wert ist der provider-Teil der updateId für die SWU-Quelldatei.

ENCODED_HASH ist die hexadezimale base64-Zeichenfolge des SHA256-Hashwerts der Binärdatei, aber nach der Codierung in einer hexadezimalen base64-Zeichenfolge werden die Zeichen wie folgt codiert:

  • + codiert als octets _2B
  • / codiert als octets _2F
  • = codiert als octets _3D

Generierung von Delta-Updates mit dem DiffGen-Tool

Sie können Delta-Updates mit dem Tool zur Generierung von Deltas (DiffGen) erstellen.

Umgebungsvoraussetzungen

Bevor Sie Deltas mit DiffGen erstellen, müssen Sie mehrere Komponenten auf dem Umgebungscomputer herunterladen und installieren. Idealerweise verwenden Sie eine Ubuntu 20.04-Linux-Umgebung oder das Windows-Subsystem für Linux, wenn Sie mit Windows arbeiten.

Die folgende Tabelle zeigt, welche Inhalte benötigt werden, wo Sie diese erhalten und welche Installation ggf. empfohlen wird.

Name der Binärdatei Abrufort So führen Sie die Installation durch
DiffGen GitHub-Repository Azure/iot-hub-device-update-delta Laden Sie die Version herunter, die dem Betriebssystem oder der Distribution auf dem Computer entspricht, der zum Generieren von Delta-Updates verwendet werden soll.
.NET Core-Runtime, Version 8.0.0 Über das Terminal oder Paket-Manager Installieren Sie .NET unter Linux. Nur die Runtime ist erforderlich.

Erstellen eines Delta-Updates mit DiffGen

Das DiffGen-Tool wird mit den folgenden erforderlichen Argumenten und dieser Syntax ausgeführt:

DiffGenTool <source_archive> <target_archive> <output_path> <log_folder> <working_folder> <recompressed_target_archive>

Der obige Befehl führt das Skript recompress_tool.py aus, das die <recompressed_target_file> erstellt. DiffGen verwendet dann die <recompressed_target_file> anstelle von <target_archive> als Zieldatei zum Erstellen des Deltas. Imagedateien im <recompressed_target_archive> werden mit gzip komprimiert.

Wenn Ihre SWU-Dateien signiert sind, benötigen sie auch das Argument <signing_command> im DiffGen-Befehl:

DiffGenTool <source_archive> <target_archive> <output_path> <log_folder> <working_folder> <recompressed_target_archive> "<signing_command>"

Das DiffGenTool mit Signaturbefehl-Zeichenfolgenparameter führt das Skript recompress_and_sign_tool.py aus. Dieses Skript erstellt die <recompressed_target_file>. Darüber hinaus signiert dieses Skript auch die sw-description-Datei im Archiv, um eine Datei sw-description.sig zu erstellen.

Sie können das Beispielskript sign_file.sh aus dem GitHub-Repository Azure/iot-hub-device-update-delta verwenden, um ein Delta zwischen der Eingabequelldatei und einer erneut komprimierten und erneut signierten Zieldatei zu erstellen. Öffnen Sie das Skript, bearbeiten Sie es, um den Pfad zu Ihrer Datei mit dem privaten Schlüssel hinzuzufügen, und speichern Sie es. Beispiele für die Verwendung finden Sie im Abschnitt Beispiele.

In der folgenden Tabelle werden die Argumente ausführlicher beschrieben.

Argument Beschreibung
<source_archive> Das Basisimage, das DiffGen als Ausgangspunkt zum Erstellen des Deltas verwendet. Wichtig: Dieses Image muss mit dem Image identisch sein, das bereits auf dem Gerät vorhanden ist (z. B. zwischengespeichert aus einem vorherigen Update).
<target_archive> Das Image, auf das das Delta-Update das Gerät aktualisiert.
<output_path> Der Pfad auf dem Hostcomputer, an dem die Deltadatei nach der Erstellung gespeichert wird, einschließlich des gewünschten Namens der generierten Deltadatei. Wenn der Pfad nicht vorhanden ist, erstellt es das Tool.
<log_folder> Der Pfad auf dem Hostcomputer, an dem Protokolle erstellt werden sollen. Es empfiehlt sich, diesen Speicherort als Unterordner des Ausgabepfads zu definieren. Wenn der Pfad nicht vorhanden ist, erstellt es das Tool.
<working_folder> Der Pfad auf dem Computer, an dem Neben- und andere Arbeitsdateien während der Deltagenerierung gespeichert werden. Es empfiehlt sich, diesen Speicherort als Unterordner des Ausgabepfads zu definieren. Wenn der Pfad nicht vorhanden ist, erstellt es das Tool.
<recompressed_target_archive> Der Pfad auf dem Hostcomputer, an dem die <recompressed_target_file> erstellt werden soll. Die <recompressed_target_file> wird anstelle des <target_archive> als Zieldatei für die Deltagenerierung verwendet. Wenn dieser Pfad vor dem Aufrufen des DiffGen-Tools vorhanden ist, wird er überschrieben. Es empfiehlt sich, diese Datei in einem Unterordner des Ausgabepfads zu definieren.
"<signing_command>" (optional) Ein anpassbarer Befehl zum Signieren der sw-description-Datei im <recompressed_target_archive>. Die sw-description-Datei im erneut komprimierten Archiv wird als Eingabeparameter für den Signaturbefehl verwendet. DiffGen erwartet, dass der Signaturbefehl eine neue Signaturdatei erstellt, wobei der Name der Eingabe mit angefügter Endung .sig verwendet wird.

Sie müssen den Parameter in doppelte Anführungszeichen setzen, um den gesamten Befehl als einzelnen Parameter zu übergeben. Vermeiden Sie außerdem die Verwendung des Zeichens ~ in einem zum Signieren verwendeten Schlüsselpfad, und verwenden Sie stattdessen den vollständigen Basispfad. Verwenden Sie beispielsweise /home/USER/keys/priv.pem anstelle von ~/keys/priv.pem.

DiffGen-Beispiele

Die folgenden Beispiele werden aus dem Verzeichnis /mnt/o/temp im Windows-Subsystem für Linux ausgeführt.

Der folgende Code erstellt ein Delta zwischen der Eingabequelldatei und einer erneut komprimierten Zieldatei:

sudo ./DiffGenTool  
/mnt/o/temp/<source file>.swu
/mnt/o/temp/<target file>.swu
/mnt/o/temp/<delta file to create>
/mnt/o/temp/logs
/mnt/o/temp/working
/mnt/o/temp/<recompressed target file to create>.swu

Wenn Sie auch den Signaturparameter verwenden (dies ist erforderlich, wenn Ihre SWU-Datei signiert ist), können Sie das zuvor erwähnte Beispielskript sign_file.sh verwenden. Öffnen Sie das Skript, bearbeiten Sie es, um den Pfad zu Ihrer Datei mit dem privaten Schlüssel hinzuzufügen, speichern Sie das Skript, und führen Sie DiffGen dann wie folgt aus.

Der folgende Code erstellt ein Delta zwischen der Eingabequelldatei und einer erneut komprimierten und erneut signierten Zieldatei:

sudo ./DiffGenTool  
/mnt/o/temp/<source file>.swu
/mnt/o/temp/<target file>.swu   
/mnt/o/temp/<delta file to create>  
/mnt/o/temp/logs  
/mnt/o/temp/working  
/mnt/o/temp/<recompressed target file to create>.swu  
/mnt/o/temp/<path to script>/<sign_file>.sh

Importieren des generierten Delta-Updates

Der grundlegende Prozess zum Importieren eines Delta-Updates in den Device Update-Dienst ist identisch mit der Vorgehensweise bei allen anderen Updates. Falls noch nicht geschehen, lesen Sie unbedingt Vorbereiten eines Updates für den Import in Azure Device Update for IoT Hub.

Generieren des Importmanifests

Um ein Update in den Device Update-Dienst zu importieren, müssen Sie über eine Importmanifestdatei verfügen oder diese erstellen. Weitere Informationen finden Sie unter Importieren von Updates in Device Update.

Importmanifestdateien für Delta-Updates müssen auf die folgenden Dateien verweisen, die vom DiffGen-Tool erstellt wurden:

  • Das <recompressed_target_file>-SWU-Image
  • Der <delta file>

Das Feature für Delta-Updates verwendet eine Funktion namens Zugehörige Dateien, die ein Importmanifest mit Version 5 oder höher erfordert. Um das Feature „Zugehörige Dateien“ zu verwenden, müssen Sie die Objekte relatedFiles und downloadHandler in Ihr Importmanifest einschließen.

Sie verwenden das relatedFiles-Objekt, um Informationen zur Delta-Updatedatei anzugeben, darunter Dateiname, Dateigröße und SHA256-Hash. Vor allem müssen Sie auch die folgenden zwei speziellen Eigenschaften des Features für Delta-Updates angeben:

"properties": {
      "microsoft.sourceFileHashAlgorithm": "sha256",
      "microsoft.sourceFileHash": "<source SWU image file hash>"
}

Beide Eigenschaften sind spezifisch für die <source image file>, die Sie beim Erstellen des Delta-Updates als Eingabe für das DiffGen-Tool verwendet haben. Das Importmanifest muss die Informationen zum SWU-Quellimage enthalten, auch wenn Sie das Quellimage nicht tatsächlich importieren. Die Deltakomponenten auf dem Gerät verwenden diese Metadaten zum Quellimage, um das Image auf dem Gerät zu finden, nachdem sie das Delta-Update heruntergeladen haben.

Verwenden Sie das downloadHandler-Objekt, um anzugeben, wie der Device Update-Agent das Delta-Update mithilfe des Features „Zugehörige Dateien“ orchestriert. Sofern Sie nicht Ihre eigene Version des Device Update-Agents für Deltafunktionen anpassen, verwenden Sie den folgenden downloadHandler:

"downloadHandler": {
  "id": "microsoft/delta:1"
}

Sie können den Befehl az iot du update init v5 der Azure-Befehlszeilenschnittstelle (Command Line Interface, CLI) verwenden, um ein Importmanifest für Ihr Delta-Update zu generieren. Weitere Informationen finden Sie unter Erstellen eines grundlegenden Device Update-Importmanifests.

--update-provider <replace with your Provider> --update-name <replace with your update Name> --update-version <replace with your update Version> --compat manufacturer=<replace with the value your device will report> model=<replace with the value your device will report> --step handler=microsoft/swupdate:2 properties=<replace with any desired handler properties (JSON-formatted), such as '{"installedCriteria": "1.0"}'> --file path=<replace with path(s) to your update file(s), including the full file name> downloadHandler=microsoft/delta:1 --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>"}'

Speichern Sie das generierte JSON-Importmanifest mit der Dateierweiterung .importmanifest.json.

Importieren über das Azure-Portal

Nachdem Sie Ihr Importmanifest erstellt haben, importieren Sie das Delta-Update, indem Sie den Anweisungen unter Hinzufügen eines Updates zu Device Update for IoT Hub folgen. Sie müssen die folgenden Elemente in den Import einschließen:

  • Die Datei *importmanifest.json, die Sie in den vorherigen Schritten erstellt haben
  • Das <recompressed_target_file>-SWU-Image, das vom DiffGen-Tool erstellt wurde
  • Die <delta file>, die vom DiffGen-Tool erstellt wurde

Bereitstellung von Delta-Updates auf Geräten

Die Bereitstellung von Delta-Updates im Azure-Portal unterscheidet sich nicht von der Vorgehensweise zum Bereitstellen eines regulären Imageupdates. Weitere Informationen finden Sie unter Bereitstellen eines Updates mithilfe von Azure Device Update for IoT Hub.

Sobald Sie die Bereitstellung für Ihr Delta-Update erstellt haben, ermitteln der Device Update-Dienst und -Client automatisch, ob ein gültiges Delta-Update für jedes Gerät vorliegt, auf dem Sie die Bereitstellung vornehmen. Wenn sie ein gültiges Delta-Update finden, laden sie es auf diesem Gerät herunter und installieren es.

Wenn sie kein gültiges Delta-Update finden, wird als Fallback stattdessen das vollständige Imageupdate (das erneut komprimierte SWU-Zielimage) heruntergeladen. Auf diese Weise stellen Sie sicher, dass alle Geräte, auf denen Sie das Update verteilen, die richtige Version erhalten.

Es gibt drei mögliche Ergebnisse für eine Deltaupdatebereitstellung:

  • Das Delta-Update wurde erfolgreich installiert, und das Gerät verwendet die neue Version.
  • Das Delta-Update war nicht verfügbar oder konnte nicht installiert werden, die Fallbackinstallation des vollständigen Images war jedoch erfolgreich, und das Gerät verwendet die neue Version.
  • Sowohl die Installation des Delta-Updates als auch die Fallbackinstallation sind fehlgeschlagen, und das Gerät verwendet weiterhin die alte Version.

Um festzustellen, welcher Fehler bzw. welches Ergebnis aufgetreten ist, können Sie die Installationsergebnisse mit dem Fehlercode und dem erweiterten Fehlercode anzeigen, indem Sie ein Gerät mit dem Status „Fehler“ auswählen. Sie können bei Bedarf auch von mehreren fehlerhaften Geräten Protokolle sammeln.

  • Wenn ein Delta-Update erfolgreich war, wird für das Gerät der Status Erfolgreich angezeigt.

  • Wenn beim Delta-Update ein Fehler aufgetreten ist, das Fallback auf das vollständige Image aber erfolgreich war, wird der folgende Fehlerstatus angezeigt:

    • resultCode: <Wert größer als 0>
    • extendedResultCode: <Wert ungleich Null>

Problembehandlung bei fehlgeschlagenen Updates

Bei nicht erfolgreichen Updates wird ein Fehlerstatus angezeigt, den Sie anhand der folgenden Anweisungen interpretieren können. Beginnen Sie mit den Fehlern des Device Update-Agents in result.h.

Fehler des Device Update-Agents, die sich auf die Downloadhandlerfunktion für Delta-Updates beziehen, beginnen mit 0x9:

Komponente Decimal Hex Hinweis
EXTENSION_MANAGER 0 0x00 Gibt Fehler aus der Downloadhandlerlogik des Erweiterungs-Managers an. Beispiel: 0x900XXXXX
PLUGIN 1 0x01 Gibt Fehler bei der Verwendung freigegebener Bibliotheken des Downloadhandler-Plug-Ins an. Beispiel: 0x901XXXXX
RESERVIERT 2–7 0x02 bis 0x07 Reserviert für den Downloadhandler. Beispiel: 0x902XXXXX
ALLGEMEIN 8 0x08 Gibt Fehler in der Logik der Deltadownloadhandler-Erweiterung auf oberster Ebene an. Beispiel: 0x908XXXXX
SOURCE_UPDATE_CACHE 9 0x09 Gibt Fehler im Quellupdatecache der Deltadownloadhandler-Erweiterung an. Beispiel: 0x909XXXXX
DELTA_PROCESSOR 10 0x0A Fehlercode für Fehler der Deltaprozessor-API. Beispiel: 0x90AXXXXX

Wenn der Fehlercode in result.h nicht vorhanden ist, handelt es sich wahrscheinlich um einen Fehler in der Deltaprozessorkomponente, die vom Device Update-Agent getrennt ist. Wenn dies der Fall ist, ist der extendedResultCode ein negativer Dezimalwert im Hexadezimalformat 0x90AXXXXX.

  • 9 ist „Deltafunktion“.
  • 0A ist „Deltaprozessorkomponente“ (ADUC_COMPONENT_DELTA_DOWNLOAD_HANDLER_DELTA_PROCESSOR).
  • XXXXX ist der 20-Bit-Fehlercode des Deltaprozessors des Field Installation Tool (FIT).

Wenn Sie das Problem nicht anhand der Fehlercodeinformationen lösen können, melden Sie ein GitHub-Problem, um weitere Unterstützung zu erhalten.

Zugehöriger Inhalt