Utbildning
Utbildningsväg
Use advance techniques in canvas apps to perform custom updates and optimization - Training
Use advance techniques in canvas apps to perform custom updates and optimization
Deltauppdateringar (förhandsversion)
Med deltauppdateringar kan du generera små uppdateringar som endast representerar ändringarna mellan två fullständiga uppdateringar, en källbild och en målbild. Den här metoden är perfekt för att minska den bandbredd som används för att ladda ned en uppdatering till en enhet, särskilt om det bara finns några få ändringar mellan käll- och måluppdateringarna.
Anteckning
Deltauppdateringsfunktionen i Azure Device Update för IoT Hub är för närvarande i offentlig förhandsversion.
- Käll- och måluppdateringsfilerna måste vara i SWUpdate-format (SWU).
- I varje SWUpdate-fil måste det finnas en råbild som använder filsystemet Ext2, Ext3 eller Ext4.
Deltagenereringsprocessen komprimerar mål-SWU-uppdateringen med hjälp av gzip-komprimering för att skapa ett optimalt delta. Du importerar den återkomprimerade SWU-måluppdateringen till enhetsuppdateringstjänsten tillsammans med den genererade deltauppdateringsfilen.
För att ladda ned och installera deltauppdateringar från enhetsuppdateringstjänsten behöver enheten enhetsuppdateringsagenten med uppdateringshanteraren och deltaprocessorkomponenten närvarande och konfigurerad.
Enhetsuppdateringsagenten samordnar uppdateringsprocessen på enheten, inklusive åtgärder för att ladda ned, installera och starta om. Information om hur du lägger till enhetsuppdateringsagenten till en enhet och konfigurerar den för användning finns i Enhetsuppdateringsagentetablering. Använd agentversion 1.0 eller senare.
En uppdateringshanterare integreras med enhetsuppdateringsagenten för att utföra den faktiska uppdateringsinstallationen. För deltauppdateringar börjar du med microsoft/swupdate:2 uppdateringshanteraren om du inte redan har en egen SWUpdate-uppdateringshanterare som du vill ändra.
Deltaprocessorn på Azure/iot-hub-device-update-delta återskapar den ursprungliga SWU-avbildningsfilen på enheten efter att deltafilen har laddats ned, så att uppdateringshanteraren kan installera SWU-filen. Om du vill lägga till deltaprocessorkomponenten i din enhetsbild och konfigurera den för användning kan du ladda ned ett Debian-paket för Ubuntu 20.04 och senare från https://github.com/Azure/iot-hub-device-update-delta/tree/main/preview/2.0.0.
Om du använder en annan distribution följer du README.md instruktioner för att använda CMAKE för att skapa deltaprocessorn från källan i stället. Därifrån installerar du det delade objektet libadudiffapi.so direkt genom att kopiera det till katalogen /usr/lib enligt följande:
Bash
sudo cp <path to libadudiffapi.so> /usr/lib/libadudiffapi.so
sudo ldconfig
När deltauppdateringsfilen har laddats ned till en enhet jämförs den med en giltig <source_archive> tidigare cachelagrad på enheten. Den här processen gör att deltauppdateringen kan återskapa den fullständiga målbilden.
Det enklaste sättet att fylla i den här cachelagrade avbildningen är att importera och distribuera en fullständig avbildningsuppdatering till enheten via enhetsuppdateringstjänsten. Om enheten har konfigurerats med Enhetsuppdateringsagent version 1.0 eller senare och deltaprocessorn cachelagrar agenten den installerade SWU-filen automatiskt för senare användning av deltauppdatering.
Om du vill fylla i källbilden direkt på enheten i stället är <BASE_SOURCE_DOWNLOAD_CACHE_PATH>/sha256-<ENCODED HASH>sökvägen där avbildningen förväntas . Som standard <BASE_SOURCE_DOWNLOAD_CACHE_PATH> är sökvägen /var/lib/adu/sdc/<provider>. Värdet provider är en provider del av updateId för käll-SWU-filen.
ENCODED_HASH är base64-hexsträngen i SHA256 för binärfilen, men efter kodning till base64 hexsträng kodas tecknen enligt följande:
-
+kodad somoctets _2B -
/kodad somoctets _2F -
=kodad somoctets _3D
Du kan skapa deltauppdateringar med verktyget Diff Generation (DiffGen).
Innan du skapar delta med DiffGen måste du ladda ned och installera flera saker på miljödatorn. Använd helst en Ubuntu 20.04 Linux-miljö eller Windows-undersystem för Linux om du använder Windows.
I följande tabell visas det innehåll som behövs, var du kan hämta det och rekommenderad installation om det behövs.
| Binärt namn | Var du ska förvärva | Så här installerar du |
|---|---|---|
| DiffGen | GitHub-lagringsplats för Azure/iot-hub-device-update-delta | Ladda ned den version som matchar operativsystemet eller distributionen på datorn som ska användas för att generera deltauppdateringar. |
| . NETCore-körning, version 8.0.0 | Via terminal- eller pakethanterare | Installera .NET på Linux. Endast körningen krävs. |
Verktyget DiffGen körs med följande obligatoriska argument och syntax:
DiffGenTool <source_archive> <target_archive> <output_path> <log_folder> <working_folder> <recompressed_target_archive>
Föregående kommando kör skriptet recompress_tool.py , som skapar <recompressed_target_file>. DiffGen använder <recompressed_target_file>sedan i stället för <target_archive> som målfil för att skapa diffet. Bildfilerna i <recompressed_target_archive> komprimeras med gzip.
Om dina SWU-filer är signerade behöver <signing_command> de också argumentet i kommandot DiffGen:
DiffGenTool <source_archive> <target_archive> <output_path> <log_folder> <working_folder> <recompressed_target_archive> "<signing_command>"
Parametern DiffGenTool med signeringskommandosträng kör recompress_and_sign_tool.py skriptet. Det här skriptet <recompressed_target_file>skapar . Dessutom signerar det här skriptet även sw-description-filen i arkivet för att skapa en sw-description.sig-fil .
Du kan använda exempelskriptet sign_file.sh från GitHub-lagringsplatsen Azure/iot-hub-device-update-delta för att skapa ett diff mellan indatakällfilen och en komprimerad och återsignerad målfil. Öppna skriptet, redigera det för att lägga till sökvägen till din privata nyckelfil och spara den. Se avsnittet Exempel för exempelanvändning.
I följande tabell beskrivs argumenten mer detaljerat:
| Argument | beskrivning |
|---|---|
<source_archive> |
Basavbildningen som DiffGen använder som utgångspunkt för att skapa deltat. Viktigt: Den här avbildningen måste vara identisk med den avbildning som redan finns på enheten, till exempel cachelagrad från en tidigare uppdatering. |
<target_archive> |
Avbildningen som deltat uppdaterar enheten till. |
<output_path> |
Sökvägen på värddatorn för att placera deltafilen i när den har skapats, inklusive önskat namn på den genererade deltafilen. Om sökvägen inte finns skapar verktyget den. |
<log_folder> |
Sökvägen på värddatorn för att skapa loggar. Det är bäst att definiera den här platsen som en undermapp för utdatasökvägen. Om sökvägen inte finns skapar verktyget den. |
<working_folder> |
Sökvägen på datorn för att placera säkerheter och andra arbetsfiler i under deltagenereringen. Det är bäst att definiera den här platsen som en undermapp för utdatasökvägen. Om sökvägen inte finns skapar verktyget den. |
<recompressed_target_archive> |
Sökvägen på värddatorn för att skapa <recompressed_target_file> in.
<recompressed_target_file> Används i stället för <target_archive> som målfil för diffgenerering. Om den här sökvägen finns innan du anropar verktyget DiffGen skrivs den över. Det är bäst att definiera den här filen i en undermapp i utdatasökvägen. |
"<signing_command>" (valfritt) |
Ett anpassningsbart kommando för att signera sw-description-filen i <recompressed_target_archive>. Sw-description-filen i det komprimerade arkivet används som indataparameter för signeringskommandot. DiffGen förväntar sig att signeringskommandot skapar en ny signaturfil med namnet på indata med .sig bifogad.Du måste omge parametern med dubbla citattecken för att skicka hela kommandot som en enda parameter. Undvik också att använda ~ tecknet i en nyckelsökväg som används för signering och använd den fullständiga hemsökvägen i stället. Använd till exempel /home/USER/keys/priv.pem i stället för ~/keys/priv.pem. |
Följande exempel fungerar i katalogen /mnt/o/temp i Windows-undersystem för Linux.
Följande kod skapar ett diff mellan indatakällans fil och en komprimerad målfil:
Bash
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
Om du också använder signeringsparametern, som du måste använda om din SWU-fil är signerad, kan du använda exemplet sign_file.sh skript som nämndes tidigare. Öppna skriptet, redigera det för att lägga till sökvägen till din privata nyckelfil, spara skriptet och kör sedan DiffGen på följande sätt.
Följande kod skapar ett diff mellan indatakällans fil och en komprimerad och återsignerad målfil:
Bash
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
Den grundläggande processen för att importera en deltauppdatering till enhetsuppdateringstjänsten är densamma som för andra uppdateringar. Om du inte redan har gjort det bör du läsa Så här förbereder du en uppdatering som ska importeras till Azure Device Update för IoT Hub.
Om du vill importera en uppdatering till enhetsuppdateringstjänsten måste du ha eller skapa en importmanifestfil. Mer information finns i Importera uppdateringar till Enhetsuppdatering.
Importera manifestfiler för deltauppdateringar måste referera till följande filer som DiffGen-verktyget skapade:
- SWU-avbildningen
<recompressed_target_file> -
<delta file>
Funktionen deltauppdatering använder en funktion som kallas relaterade filer som kräver ett importmanifest version 5 eller senare. Om du vill använda funktionen relaterade filer måste du inkludera objekten relatedFiles och downloadHandler i importmanifestet.
Du använder relatedFiles objektet för att ange information om deltauppdateringsfilen, inklusive filnamnet, filstorleken och sha256-hashen. Viktigast av allt är att du också måste ange följande två egenskaper som är unika för deltauppdateringsfunktionen:
JSON
"properties": {
"microsoft.sourceFileHashAlgorithm": "sha256",
"microsoft.sourceFileHash": "<source SWU image file hash>"
}
Båda egenskaperna är specifika för de <source image file> du använde som indata till verktyget DiffGen när du skapade deltauppdateringen. Importmanifestet behöver information om käll-SWU-avbildningen även om du inte importerar källbilden. Deltakomponenterna på enheten använder dessa metadata om källbilden för att hitta avbildningen på enheten när de har laddat ned deltauppdateringen.
Använd - downloadHandler objektet för att ange hur enhetsuppdateringsagenten samordnar deltauppdateringen med hjälp av funktionen relaterade filer. Om du inte anpassar din egen version av enhetsuppdateringsagenten för deltafunktioner använder du följande downloadHandler:
JSON
"downloadHandler": {
"id": "microsoft/delta:1"
}
Du kan använda Azure CLI-kommandot az iot du update init v5 för att generera ett importmanifest för din deltauppdatering. Mer information finns i Skapa ett grundläggande importmanifest.
Azure CLI
--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>"}'
Spara det genererade importmanifestet JSON med filnamnstillägget .importmanifest.json.
När du har skapat importmanifestet importerar du deltauppdateringen genom att följa anvisningarna i Lägg till en uppdatering i Enhetsuppdatering för IoT Hub. Du måste inkludera följande objekt i importen:
- Filen *importmanifest.json som du skapade tidigare i de tidigare stegen
- SWU-avbildningen
<recompressed_target_file>som verktyget DiffGen skapade - Verktyget
<delta file>DiffGen skapades
Distributionsupplevelsen för deltauppdatering i Azure Portal är densamma som när du distribuerar en vanlig avbildningsuppdatering. Mer information finns i Distribuera en uppdatering med hjälp av Enhetsuppdatering.
När du har skapat distributionen för deltauppdateringen avgör enhetsuppdateringstjänsten och klienten automatiskt om det finns en giltig deltauppdatering för varje enhet som du distribuerar till. Om de hittar ett giltigt delta laddar de ned och installerar deltauppdateringen på den enheten.
Om de inte hittar en giltig deltauppdatering laddas den fullständiga avbildningsuppdateringen (den återkomprimerade SWU-målbilden) ned i stället som en reserv. Den här metoden säkerställer att alla enheter som du distribuerar uppdateringen för att komma till rätt version.
Det finns tre möjliga resultat för en deltauppdateringsdistribution:
- Delta-uppdateringen har installerats och enheten är på den nya versionen.
- Delta-uppdateringen var inte tillgänglig eller kunde inte installeras, men en återställningsinstallation av den fullständiga avbildningen lyckades och enheten finns i den nya versionen.
- Både delta- och reservinstallationerna misslyckades och enheten finns fortfarande i den gamla versionen.
För att avgöra vilket fel som inträffade kan du visa installationsresultatet med felkod och utökad felkod genom att välja alla enheter som är i ett feltillstånd. Du kan också samla in loggar från flera misslyckade enheter om det behövs.
Om en deltauppdatering lyckades visar enheten statusen Lyckades .
Om en deltauppdatering misslyckades men återställningen till den fullständiga avbildningen lyckades visar enheten följande felstatus:
-
resultCode: <värde större än 0> -
extendedResultCode: <värde som inte är noll>
-
Misslyckade uppdateringar visar en felstatus som du kan tolka med hjälp av följande instruktioner. Börja med enhetsuppdateringsagentens fel i result.h.
Fel från enhetsuppdateringsagenten som är specifika för deltauppdateringarnas nedladdningshanterare börjar med 0x9:
| Komponent | Decimal | Hex | Kommentar |
|---|---|---|---|
| EXTENSION_MANAGER | 0 | 0x00 | Anger fel från tilläggshanterarens nedladdningshanterarlogik. Exempel: 0x900XXXXX |
| PLUGIN-program | 1 | 0x01 | Anger fel med användning av delade bibliotek för nedladdningshanterarens plugin-program. Exempel: 0x901XXXXX |
| RESERVERAD | 2 - 7 | 0x02 - 0x07 | Reserverad för nedladdningshanteraren. Exempel: 0x902XXXXX |
| GEMENSAM | 8 | 0x08 | Anger fel i logiken för deltahämtningshanterarens tillägg på den översta nivån. Exempel: 0x908XXXXX |
| SOURCE_UPDATE_CACHE | 9 | 0x09 | Anger fel i källuppdateringscachen för deltahämtningshanterarens tillägg. Exempel: 0x909XXXXX |
| DELTA_PROCESSOR | 10 | 0x0A | Felkod för fel från DELTA-processor-API:et. Exempel: 0x90AXXXXX |
Om felkoden inte finns i result.h är det förmodligen ett fel i deltaprocessorkomponenten, separat från enhetsuppdateringsagenten. I så fall extendedResultCode är ett negativt decimalvärde i hexadecimalt format 0x90AXXXXX.
-
9är "Delta Facility" -
0Aär "Delta Processor Component" (ADUC_COMPONENT_DELTA_DOWNLOAD_HANDLER_DELTA_PROCESSOR) -
XXXXXär 20-bitars felkoden från DELTA-processorn (Field Installation Tool)
Om du inte kan lösa problemet baserat på felkodsinformationen kan du ange ett GitHub-problem för att få ytterligare hjälp.