Delta-updates begrijpen en gebruiken in Device Update voor IoT Hub (preview)

Artikel
10/16/2024

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

Notitie

De delta-updatefunctie 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. Importeer deze opnieuw gecomprimeerde doel-SWU-update naar de Device Update-service, samen met het gegenereerde delta-updatebestand.

Een apparaat configureren met device update-agent en deltaprocessoronderdeel

Als u wilt dat uw apparaat delta-updates downloadt en installeert vanuit de Device Update-service, hebt u verschillende onderdelen nodig die aanwezig en geconfigureerd zijn.

Device Update-agent

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

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 maakt het oorspronkelijke SWU-installatiekopieënbestand opnieuw op uw apparaat nadat het Delta-bestand is gedownload, zodat uw updatehandler het SWU-bestand kan installeren. De deltaprocessor is beschikbaar in de GitHub-opslagplaats Azure/iot-hub-device-update-delta .

Als u het deltaprocessoronderdeel wilt toevoegen aan uw apparaatinstallatiekopie en deze wilt configureren voor gebruik, kunt u een .deb-pakket downloaden dat wordt ondersteund op Ubuntu 20.04 en hoger. 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 (libadudiffapi.so) rechtstreeks door het naar de /usr/lib map te kopiëren:

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

Een bron-SWU-afbeeldingsbestand toevoegen aan uw apparaat

Nadat een delta-update naar een apparaat is gedownload, moet deze worden vergeleken met een geldig bron-SWU-bestand dat eerder op het apparaat in de cache was opgeslagen. Dit proces is nodig voor de delta-update om de volledige doelinstallatiekopieën opnieuw te maken. De eenvoudigste manier om deze installatiekopieën in de cache te vullen, is door een volledige installatiekopieënupdate op het apparaat te implementeren via de Device Update-service (met behulp van de bestaande import- en implementatieprocessen). Zolang het apparaat is geconfigureerd met de Device Update-agent (versie 1.0 of hoger) en deltaprocessor, slaat de Device Update-agent het geïnstalleerde SWU-bestand automatisch op in de cache voor later gebruik van delta-updates.

Als u in plaats daarvan de broninstallatiekopieën rechtstreeks op uw apparaat wilt invullen, is het pad waar de afbeelding wordt verwacht:

[BASE_SOURCE_DOWNLOAD_CACHE_PATH]/sha256-[ENCODED HASH]

BASE_SOURCE_DOWNLOAD_CACHE_PATH Is standaard het pad/var/lib/adu/sdc/[provider]. De [provider] waarde is het provideronderdeel 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-updates genereren met behulp van het hulpprogramma DiffGen

Omgevingsvereisten

Voordat u delta's met DiffGen maakt, moeten er verschillende dingen worden gedownload en/of geïnstalleerd op de omgevingscomputer. We raden een Linux-omgeving aan en met name Ubuntu 20.04 (of Windows-subsysteem voor Linux als ze systeemeigen zijn op Windows).

De volgende tabel bevat een lijst met de benodigde inhoud, waar ze moeten worden opgehaald en waar nodig de aanbevolen installatie:

Binaire naam	Waar te verkrijgen	Installeren
DiffGen	Azure/iot-hub-device-update-delta GitHub-opslagplaats	Download de versie die overeenkomt met het besturingssysteem/distributie op de computer die wordt gebruikt om delta-updates te genereren.
. NETCore Runtime, versie 8.0.0	Via Terminal/Pakketbeheer s	Instructies voor Linux. Alleen de runtime is vereist.

Een delta-update maken met DiffGen

Het hulpprogramma DiffGen wordt uitgevoerd met verschillende argumenten. Alle argumenten zijn vereist en de algehele syntaxis is als volgt:

DiffGenTool [source_archive] [target_archive] [output_path] [log_folder] [working_folder] [recompressed_target_archive]

Het script recompress_tool.py wordt uitgevoerd om het bestand [recompressed_target_archive] te maken, dat vervolgens wordt gebruikt in plaats van [target_archive] als doelbestand voor het maken van de diff.
De afbeeldingsbestanden in [recompressed_target_archive] worden gecomprimeerd met gzip.

Als uw SWU-bestanden zijn ondertekend (waarschijnlijk), hebt u ook een ander argument nodig:

DiffGenTool [source_archive] [target_archive] [output_path] [log_folder] [working_folder] [recompressed_target_archive] "[signing_command]"

Naast het gebruik van [recompressed_target_archive] als doelbestand, wordt het opgeven van een tekenreeksparameter voor ondertekening recompress_and_sign_tool.py om het bestand [recompressed_target_archive] te maken en het sw-description-bestand in het archief ondertekend te hebben (wat betekent dat er een sw-description.sig-bestand aanwezig is). U kunt het voorbeeldscript sign_file.sh gebruiken vanuit de GitHub-opslagplaats Azure/iot-hub-device-update-delta . 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]	Dit is de afbeelding waarop de delta is gebaseerd bij het maken van de delta. 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]	Dit is de afbeelding waarnaar het apparaat wordt bijgewerkt door de delta.
[output_path]	Het pad (inclusief de gewenste naam van het deltabestand dat wordt gegenereerd) op de hostcomputer waar het deltabestand wordt geplaatst na het maken. Als het pad niet bestaat, wordt het hulpprogramma gemaakt.
[log_folder]	Het pad op de hostcomputer waar logboeken worden gemaakt. U wordt aangeraden deze locatie te definiëren als een submap van het uitvoerpad. Als het pad niet bestaat, wordt het hulpprogramma gemaakt.
[working_folder]	Het pad op de machine waar onderpand en andere werkbestanden worden geplaatst tijdens de deltageneratie. U wordt aangeraden deze locatie te 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 waar het opnieuw gecomprimeerde doelbestand wordt gemaakt. Dit bestand wordt gebruikt in plaats van <target_archive> als doelbestand voor het genereren van verschillen. Als dit pad bestaat voordat DiffGenTool wordt aangeroepen, wordt het pad overschreven. U wordt aangeraden dit pad te definiëren als een bestand in de submap van het uitvoerpad.
[signing_command]' (optioneel)	Een aanpasbare opdracht die wordt gebruikt voor het ondertekenen van het sw-description-bestand in het opnieuw gecomprimeerde archiefbestand. Het sw-description-bestand in het opnieuw gecomprimeerde archief wordt gebruikt als invoerparameter voor de ondertekeningsopdracht; DiffGenTool verwacht dat de ondertekeningsopdracht een nieuw handtekeningbestand maakt met behulp van de naam van de invoer waaraan `.sig` is toegevoegd. De parameter tussen dubbele aanhalingstekens is nodig, zodat de hele opdracht wordt doorgegeven als één parameter. Vermijd ook het teken ~in een sleutelpad te plaatsen 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

In deze voorbeelden werken we uit de map /mnt/o/temp (in WSL):

Het maken van een verschil tussen het invoerbronbestand en het opnieuw gecomprimeerde doelbestand:

sudo ./DiffGenTool  
/mnt/o/temp/[source file.swu]  
/mnt/o/temp/[target file.swu]  
/mnt/o/temp/[delta file to be created]  
/mnt/o/temp/logs  
/mnt/o/temp/working  
/mnt/o/temp/[recompressed file to be created.swu]

Als u ook de ondertekeningsparameter gebruikt (nodig als uw SWU-bestand is ondertekend), kunt u het voorbeeldscript sign_file.sh gebruiken waarnaar eerder wordt verwezen. Open eerst het script en bewerk het om het pad toe te voegen aan uw persoonlijke sleutelbestand. Sla het script op en voer DiffGen als volgt uit:

Het maken van een verschil tussen het invoerbronbestand en het opnieuw gecomprimeerde/opnieuw ondertekende doelbestand:

sudo ./DiffGenTool  
/mnt/o/temp/[source file.swu]
/mnt/o/temp/[target file.swu]   
/mnt/o/temp/[delta file to be created]  
/mnt/o/temp/logs  
/mnt/o/temp/working  
/mnt/o/temp/[recompressed file to be created.swu]  
/mnt/o/temp/[path to script]/sign_file.sh

De gegenereerde delta-update importeren

Het basisproces voor het importeren van een update naar de Device Update-service is ongewijzigd voor delta-updates. Als u dit nog niet hebt gedaan, raadpleegt u deze pagina: Een update voorbereiden die moet worden geïmporteerd in Azure Device Update voor IoT Hub

Importmanifest genereren

De eerste stap voor het importeren van een update in de Device Update-service is altijd het maken van een importmanifest als u er nog geen hebt. Zie Updates importeren in Device Update voor meer informatie over het importeren van manifesten. Voor delta-updates moet uw importmanifest verwijzen naar twee bestanden:

De opnieuw gecomprimeerde doel-SWU-installatiekopie die is gemaakt toen u het hulpprogramma DiffGen hebt uitgevoerd.
Het deltabestand dat is gemaakt toen u het hulpprogramma DiffGen hebt uitgevoerd.

De delta-updatefunctie maakt gebruik van een mogelijkheid die gerelateerde bestanden wordt genoemd. Hiervoor is een importmanifest vereist dat versie 5 of hoger is.

Als u een importmanifest voor uw Delta-update wilt maken met behulp van de functie gerelateerde bestanden, moet u relatedFiles en downloadHandler-objecten toevoegen aan uw importmanifest.

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

"properties": {
      "microsoft.sourceFileHashAlgorithm": "sha256",
      "microsoft.sourceFileHash": "[insert the source SWU image file hash]"
}

Beide eigenschappen zijn specifiek voor uw bron-SWU-afbeeldingsbestand dat u hebt gebruikt als invoer voor het DiffGen-hulpprogramma bij het maken van uw delta-update. De informatie over de bron-SWU-installatiekopieën is nodig in uw importmanifest, ook al importeert u de broninstallatiekopieën niet daadwerkelijk. De deltaonderdelen op het apparaat gebruiken deze metagegevens over de broninstallatiekopieën om de installatiekopieën op het apparaat te vinden zodra de delta is gedownload.

Gebruik het downloadHandler object om op te geven hoe de Device Update-agent de delta-update organiseert met behulp van de gerelateerde bestandsfunctie. Tenzij u uw eigen versie van de Device Update-agent voor deltafunctionaliteit wilt aanpassen, moet u deze downloadHandler alleen gebruiken:

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

U kunt de Azure-opdrachtregelinterface (CLI) gebruiken om een importmanifest te genereren voor uw delta-update. Zie Een eenvoudig importmanifest maken als u de Azure CLI nog niet eerder hebt gebruikt om een importmanifest te maken.

az iot du update init v5
--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 in een bestand met de extensie .importmanifest.json

Importeren met behulp van Azure Portal

Zodra u het importmanifest hebt gemaakt, kunt u de delta-update importeren. Als u wilt importeren, volgt u de instructies in Een update toevoegen aan Device Update voor IoT Hub. U moet deze items opnemen bij het importeren:

Het importmanifest .json bestand dat u in de vorige stap hebt gemaakt.
De opnieuw gecomprimeerde doel-SWU-installatiekopie die is gemaakt toen u het hulpprogramma DiffGen hebt uitgevoerd.
Het deltabestand dat is gemaakt toen u het hulpprogramma DiffGen hebt uitgevoerd.

De delta-update implementeren op uw apparaten

Wanneer u een delta-update implementeert, ziet de ervaring in Azure Portal er hetzelfde uit als het implementeren van een normale installatiekopieënupdate. Zie Een update implementeren met behulp van Device Update voor Azure IoT Hub voor meer informatie over het implementeren van updates.

Zodra u de implementatie voor uw delta-update hebt gemaakt, identificeren de Device Update-service en -client automatisch of er een geldige delta-update is voor elk apparaat waarop u implementeert. Als er een geldige delta wordt gevonden, wordt de delta-update gedownload en geïnstalleerd op dat apparaat. Als er geen geldige delta-update is gevonden, 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:

Delta-update is geïnstalleerd. Het apparaat heeft een nieuwe versie.
Delta-update is niet beschikbaar of kan niet worden geïnstalleerd, maar er is een geslaagde terugvalinstallatie van de volledige installatiekopieën opgetreden. Het apparaat heeft een nieuwe versie.
Zowel delta als terugval naar volledige installatiekopieën is mislukt. Het apparaat is nog steeds op oude versie.

Als u wilt bepalen welke van de bovenstaande resultaten zijn 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 de delta-update is geslaagd, wordt op het apparaat de status Geslaagd weergegeven.

Als de delta-update is mislukt, maar een geslaagde terugval naar de volledige afbeelding heeft uitgevoerd, wordt de volgende foutstatus weergegeven:

resultCode: [waarde groter dan 0]
extendedResultCode: [niet-nul]

Als de update mislukt, wordt een foutstatus weergegeven die kan worden geïnterpreteerd met behulp van deze 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 die wordt gebruikt 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 Download Handler-extensie op het hoogste niveau. Voorbeeld: 0x908XXXXX
SOURCE_UPDATE_CACHE	9	0x09	Geeft fouten aan in de bron-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 (los van de Device Update-agent). Als dit het geval is, is de extendedResultCode een negatieve decimale waarde van de volgende hexadecimale notatie: 0x90AXXXXXXX
- 9 is "Delta Facility"
- 0A is 'Delta Processor Component' (ADUC_COMPONENT_DELTA_DOWNLOAD_HANDLER_DELTA_PROCESSOR)
- XXXXX is de 20-bits foutcode van fit deltaprocessor

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

Volgende stappen

Algemene problemen oplossen

Delen via