Delen via

Delta-updates (preview)

  • Artikel

Met Delta-updates kunt u kleine updates genereren die alleen de wijzigingen tussen twee volledige updates, een broninstallatiekopieën en een doelinstallatiekopieën vertegenwoordigen. Deze methode is ideaal voor het verminderen van de bandbreedte die wordt gebruikt om een update naar een apparaat te downloaden, met name als er slechts enkele wijzigingen zijn tussen de bron- en doelupdates.

Notitie

De delta-updatefunctie in Azure Device Update for IoT Hub is momenteel beschikbaar als openbare preview.

Vereisten voor het gebruik van delta-updates in Device Update voor IoT Hub

  • De bron- en doelupdatebestanden moeten de SWU-indeling (SWUpdate) hebben.
  • Binnen elk SWUpdate-bestand moet er een onbewerkte installatiekopie zijn die gebruikmaakt van het bestandssysteem Ext2, Ext3 of Ext4.

Het deltageneratieproces recomprimeert de doel-SWU-update met behulp van gzip-compressie om een optimale delta te produceren. U importeert de opnieuw gecomprimeerde doel-SWU-update naar de Device Update-service, samen met het gegenereerde delta-updatebestand.

Configuratie van de Device Update-agent voor het deltaprocessoronderdeel

Als u delta-updates wilt downloaden en installeren vanuit de Device Update-service, heeft uw apparaat de Device Update-agent nodig met de updatehandler en het deltaprocessoronderdeel dat aanwezig en geconfigureerd is.

Device Update-agent

De Device Update-agent organiseert het updateproces op het apparaat, waaronder acties voor downloaden, installeren en opnieuw opstarten. Zie Device Update-agent inrichten om de Device Update-agent toe te voegen aan een apparaat en deze te configureren voor gebruik. Gebruik agentversie 1.0 of hoger.

Handler bijwerken

Een updatehandler kan worden geïntegreerd met de Device Update-agent om de daadwerkelijke update-installatie uit te voeren. Voor delta-updates begint u met de microsoft/swupdate:2 update-handler als u nog geen eigen SWUpdate-updatehandler hebt die u wilt wijzigen.

Delta-processor

De deltaprocessor op Azure/iot-hub-device-update-delta maakt het oorspronkelijke SWU-installatiekopieënbestand opnieuw op uw apparaat nadat het deltabestand is gedownload, zodat uw updatehandler het SWU-bestand kan installeren. Als u het deltaprocessoronderdeel wilt toevoegen aan uw apparaatinstallatiekopie en deze wilt configureren voor gebruik, kunt u een Debian-pakket voor Ubuntu 20.04 en hoger downloaden van https://github.com/Azure/iot-hub-device-update-delta/tree/main/preview/2.0.0.

Als u een andere distributie gebruikt, volgt u de README.md instructies voor het gebruik van CMAKE om de deltaprocessor te bouwen vanuit de bron. Installeer het gedeelde object rechtstreeks libadudiffapi.so door het als volgt te kopiëren naar de map /usr/lib :

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

Een bron-SWU-afbeeldingsbestand toevoegen aan uw apparaat

Nadat het delta-updatebestand naar een apparaat is gedownload, wordt het vergeleken met een geldige <source_archive> eerder in de cache opgeslagen op het apparaat. Met dit proces kan de delta-update de volledige doelinstallatiekopieën opnieuw maken.

De eenvoudigste manier om deze in de cache geplaatste installatiekopieën te vullen, is door een volledige installatiekopieënupdate te importeren en implementeren op het apparaat via de Device Update-service. Als het apparaat is geconfigureerd met Device Update-agent versie 1.0 of hoger en de deltaprocessor, slaat de agent het geïnstalleerde SWU-bestand automatisch op voor later gebruik van delta-updates.

Als u in plaats daarvan de broninstallatiekopieën rechtstreeks op uw apparaat wilt invullen, is <BASE_SOURCE_DOWNLOAD_CACHE_PATH>/sha256-<ENCODED HASH>het pad waar de afbeelding wordt verwacht. Is standaard <BASE_SOURCE_DOWNLOAD_CACHE_PATH> het pad /var/lib/adu/sdc/<provider>. De provider waarde is het provider deel van de updateId voor het bron-SWU-bestand.

ENCODED_HASH is de hextekenreeks base64 van de SHA256 van het binaire bestand, maar na codering van base64 hex-tekenreeks, worden de tekens als volgt gecodeerd:

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

Delta-updategeneratie met behulp van het hulpprogramma DiffGen

U kunt delta-updates maken met behulp van het hulpprogramma Diff Generation (DiffGen).

Omgevingsvereisten

Voordat u delta's met DiffGen maakt, moet u verschillende dingen op de omgevingscomputer downloaden en installeren. Gebruik idealiter een Ubuntu 20.04 Linux-omgeving of Windows-subsysteem voor Linux als u windows gebruikt.

In de volgende tabel ziet u de benodigde inhoud, waar u deze kunt ophalen en waar nodig de installatie wordt aanbevolen.

Binaire naam Waar te verkrijgen Installeren
DiffGen Azure/iot-hub-device-update-delta GitHub-opslagplaats Download de versie die overeenkomt met het besturingssysteem of distributie op de computer die moet worden gebruikt om delta-updates te genereren.
. NETCore Runtime, versie 8.0.0 Via Terminal- of pakketbeheerders Installeer .NET in Linux. Alleen de runtime is vereist.

Delta-update maken met DiffGen

Het hulpprogramma DiffGen wordt uitgevoerd met de volgende vereiste argumenten en syntaxis:

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

Met de voorgaande opdracht wordt het recompress_tool.py script uitgevoerd, waarmee de <recompressed_target_file>. DiffGen gebruikt vervolgens het <recompressed_target_file>in plaats van <target_archive> het doelbestand voor het maken van de diff. Afbeeldingsbestanden in de <recompressed_target_archive> bestanden worden gecomprimeerd met gzip.

Als uw SWU-bestanden zijn ondertekend, hebben ze ook het <signing_command> argument nodig in de opdracht DiffGen:

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

De DiffGenTool met de tekenreeksparameter voor ondertekening voert het recompress_and_sign_tool.py script uit. Met dit script maakt u de <recompressed_target_file>. Daarnaast ondertekent dit script ook het sw-description-bestand in het archief om een sw-description.sig-bestand te maken.

U kunt het voorbeeldscript sign_file.sh van de GitHub-opslagplaats Azure/iot-hub-device-update-delta gebruiken om een verschil te maken tussen het invoerbronbestand en een opnieuw gecomprimeerd en opnieuw ondertekend doelbestand. Open het script, bewerk het om het pad toe te voegen aan uw persoonlijke sleutelbestand en sla het op. Zie de sectie Voorbeelden voor voorbeeldgebruik.

In de volgende tabel worden de argumenten gedetailleerder beschreven:

Argument Beschrijving
<source_archive> De basisinstallatiekopie die DiffGen als uitgangspunt gebruikt om de delta te maken. Belangrijk: deze afbeelding moet identiek zijn aan de installatiekopieën die al aanwezig zijn op het apparaat, bijvoorbeeld in de cache van een vorige update.
<target_archive> De afbeelding waarnaar de delta het apparaat bijwerken.
<output_path> Het pad op de hostcomputer om het deltabestand in te plaatsen na het maken, inclusief de gewenste naam van het gegenereerde deltabestand. Als het pad niet bestaat, wordt het hulpprogramma gemaakt.
<log_folder> Het pad op de hostcomputer om logboeken te maken. U kunt deze locatie het beste definiëren als een submap van het uitvoerpad. Als het pad niet bestaat, wordt het hulpprogramma gemaakt.
<working_folder> Het pad op de machine om onderpand en andere werkbestanden in te plaatsen tijdens de deltageneratie. U kunt deze locatie het beste definiëren als een submap van het uitvoerpad. Als het pad niet bestaat, wordt het hulpprogramma gemaakt.
<recompressed_target_archive> Het pad op de hostcomputer om de <recompressed_target_file> in te maken. De <recompressed_target_file> wordt gebruikt in plaats van het <target_archive> doelbestand voor het genereren van diff. Als dit pad bestaat voordat het hulpprogramma DiffGen wordt aangeroepen, wordt dit overschreven. U kunt dit bestand het beste definiëren in een submap van het uitvoerpad.
"<signing_command>"( optioneel) Een aanpasbare opdracht voor het ondertekenen van het sw-description-bestand in de <recompressed_target_archive>. Het sw-description-bestand in het gecomprimeerde archief wordt gebruikt als invoerparameter voor de opdracht voor ondertekening. DiffGen verwacht dat de ondertekeningsopdracht een nieuw handtekeningbestand maakt met behulp van de naam van de invoer waaraan .sig is toegevoegd.

U moet de parameter tussen dubbele aanhalingstekens plaatsen om de hele opdracht als één parameter door te geven. Vermijd ook het gebruik van het ~ teken in een sleutelpad dat wordt gebruikt voor ondertekening en gebruik in plaats daarvan het volledige basispad. Gebruik bijvoorbeeld /home/USER/keys/priv.pem in plaats van ~/keys/priv.pem.

Voorbeelden van DiffGen

De volgende voorbeelden werken uit de map /mnt/o/temp in Windows-subsysteem voor Linux.

Met de volgende code wordt een verschil gemaakt tussen het invoerbronbestand en een opnieuw gecomprimeerd doelbestand:

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

Als u ook de ondertekeningsparameter gebruikt, die u moet gebruiken als uw SWU-bestand is ondertekend, kunt u het voorbeeld sign_file.sh script gebruiken dat eerder is genoemd. Open het script, bewerk het om het pad toe te voegen aan uw persoonlijke-sleutelbestand, sla het script op en voer DiffGen als volgt uit.

Met de volgende code wordt een verschil gemaakt tussen het invoerbronbestand en een opnieuw gecomprimeerd en opnieuw ondertekend doelbestand:

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

Gegenereerde delta-updateimport

Het basisproces voor het importeren van een delta-update naar de Device Update-service is hetzelfde als voor elke andere update. Als u dat nog niet hebt gedaan, controleert u hoe u een update voorbereidt die moet worden geïmporteerd in Azure Device Update voor IoT Hub.

Het importmanifest genereren

Als u een update wilt importeren in de Device Update-service, moet u een manifestbestand voor importeren hebben of maken. Zie Updates importeren in Device Update voor meer informatie.

Manifestbestanden voor delta-updates importeren moet verwijzen naar de volgende bestanden die door het diffGen-hulpprogramma zijn gemaakt:

  • De <recompressed_target_file> SWU-afbeelding
  • De <delta file>

De delta-updatefunctie maakt gebruik van een mogelijkheid die gerelateerde bestanden wordt genoemd waarvoor een importmanifest van versie 5 of hoger is vereist. Als u de functie gerelateerde bestanden wilt gebruiken, moet u de relatedFiles en downloadHandler-objecten opnemen in uw importmanifest.

U gebruikt het relatedFiles object om informatie op te geven over het delta-updatebestand, inclusief de bestandsnaam, de bestandsgrootte en sha256-hash. Het belangrijkste is dat u ook de volgende twee eigenschappen moet opgeven die uniek zijn voor de delta-updatefunctie:

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

Beide eigenschappen zijn specifiek voor de eigenschappen die <source image file> u hebt gebruikt als invoer voor het hulpprogramma DiffGen bij het maken van uw delta-update. Het importmanifest heeft de informatie over de bron-SWU-installatiekopieën nodig, ook al importeert u de broninstallatiekopieën niet daadwerkelijk. De deltaonderdelen op het apparaat gebruiken deze metagegevens over de broninstallatiekopieën om die installatiekopieën op het apparaat te vinden nadat ze de delta-update hebben gedownload.

Gebruik het downloadHandler object om op te geven hoe de Device Update-agent de delta-update organiseert met behulp van de gerelateerde bestandsfunctie. Gebruik het volgende downloadHandler, tenzij u uw eigen versie van de Device Update-agent voor deltafunctionaliteit aanpast:

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

U kunt de Azure CLI-opdracht az iot du update init v5 gebruiken om een importmanifest voor uw delta-update te genereren. Zie Een eenvoudig importmanifest maken voor meer informatie.

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

Sla de gegenereerde JSON van het importmanifest op met de bestandsextensie .importmanifest.json.

Importeren met behulp van Azure Portal

Nadat u het importmanifest hebt gemaakt, importeert u de delta-update door de instructies in Een update toevoegen aan Device Update voor IoT Hub te volgen. U moet de volgende items in de import opnemen:

  • Het *importmanifest.json-bestand dat u eerder in de vorige stappen hebt gemaakt
  • De <recompressed_target_file> SWU-installatiekopie die het hulpprogramma DiffGen heeft gemaakt
  • Het <delta file> hulpprogramma DiffGen dat is gemaakt

Implementatie van Delta-updates op apparaten

De implementatie-ervaring voor delta-updates in Azure Portal is hetzelfde als het implementeren van een normale installatiekopieënupdate. Zie Een update implementeren met device update voor meer informatie.

Zodra u de implementatie voor uw delta-update hebt gemaakt, bepalen de Device Update-service en -client automatisch of er een geldige delta-update is voor elk apparaat waarop u implementeert. Als ze een geldige delta vinden, downloaden en installeren ze de delta-update op dat apparaat.

Als ze geen geldige delta-update vinden, wordt de volledige update van de installatiekopieën (de opnieuw gecomprimeerde doel-SWU-installatiekopieën) gedownload als een terugval. Deze aanpak zorgt ervoor dat alle apparaten die u de update implementeert, naar de juiste versie gaan.

Er zijn drie mogelijke resultaten voor een delta-update-implementatie:

  • De delta-update is geïnstalleerd en het apparaat bevindt zich in de nieuwe versie.
  • De delta-update is niet beschikbaar of kan niet worden geïnstalleerd, maar er is een terugvalinstallatie van de volledige installatiekopieën geslaagd en het apparaat is op de nieuwe versie geïnstalleerd.
  • De delta- en terugval-installaties zijn mislukt en het apparaat is nog steeds op de oude versie geïnstalleerd.

Als u wilt bepalen welk foutresultaat is opgetreden, kunt u de installatieresultaten weergeven met foutcode en uitgebreide foutcode door elk apparaat te selecteren dat de status Mislukt heeft. U kunt ook logboeken verzamelen van meerdere mislukte apparaten, indien nodig.

  • Als een delta-update is geslaagd, wordt op het apparaat de status Geslaagd weergegeven.

  • Als een delta-update is mislukt, maar de terugval naar de volledige installatiekopieën is geslaagd, wordt op het apparaat de volgende foutstatus weergegeven:

    • resultCode: <waarde groter dan 0>
    • extendedResultCode: <niet-nulwaarde>

Problemen met mislukte updates oplossen

Mislukte updates geven een foutstatus weer die u kunt interpreteren met behulp van de volgende instructies. Begin met de fouten van de Device Update-agent in result.h.

Fouten van de Device Update-agent die specifiek zijn voor de downloadhandlerfunctionaliteit voor delta-updates, beginnen met 0x9:

Onderdeel Decimal Hex Notitie
EXTENSION_MANAGER 0 0x00 Geeft fouten aan van de downloadhandlerlogica van Extension Manager. Voorbeeld: 0x900XXXXX
INVOEGTOEPASSING 1 0x01 Geeft fouten aan met het gebruik van gedeelde bibliotheken van de downloadhandler-invoegtoepassing. Voorbeeld: 0x901XXXXX
GERESERVEERD 2 - 7 0x02 - 0x07 Gereserveerd voor downloadhandler. Voorbeeld: 0x902XXXXX
VAAK 8 0x08 Geeft fouten aan in de logica van de delta-downloadhandler-extensie op het hoogste niveau. Voorbeeld: 0x908XXXXX
SOURCE_UPDATE_CACHE 9 0x09 Geeft fouten aan in de updatecache van de delta-download-handler-extensie. Voorbeeld: 0x909XXXXX
DELTA_PROCESSOR 10 0x0A Foutcode voor fouten van deltaprocessor-API. Voorbeeld: 0x90AXXXXX

Als de foutcode niet aanwezig is in result.h, is dit waarschijnlijk een fout in het deltaprocessoronderdeel, gescheiden van de Device Update-agent. Zo ja, dan is het extendedResultCode een negatieve decimale waarde in de hexadecimale notatie 0x90AXXXXX.

  • 9 is "Delta Facility"
  • 0A is 'Delta Processor Component' (ADUC_COMPONENT_DELTA_DOWNLOAD_HANDLER_DELTA_PROCESSOR)
  • XXXXX is de 20-bits foutcode van de DELTA-processor (Field Installation Tool)

Als u het probleem niet kunt oplossen op basis van de foutcodegegevens, dient u een GitHub-probleem in om meer hulp te krijgen.

Gerelateerde inhoud