Jak zrozumieć i używać aktualizacji różnicowych w usłudze Device Update dla usługi IoT Hub (wersja zapoznawcza)

Artykuł
03/08/2024

Aktualizacje różnicowe umożliwiają wygenerowanie małej aktualizacji reprezentującej tylko zmiany między dwoma pełnymi aktualizacjami — obrazem źródłowym i obrazem docelowym. Takie podejście jest idealne do zmniejszenia przepustowości używanej do pobierania aktualizacji do urządzenia, szczególnie w przypadku kilku zmian między aktualizacjami źródłowymi i docelowymi.

Uwaga

Funkcja aktualizacji różnicowej jest obecnie dostępna w publicznej wersji zapoznawczej.

Wymagania dotyczące używania aktualizacji różnicowych w usłudze Device Update dla usługi IoT Hub

Źródłowe i docelowe pliki aktualizacji muszą mieć format SWUpdate (SWU).
W każdym pliku SWUpdate musi istnieć nieprzetworzone obrazy korzystające z systemu plików Ext2, Ext3 lub Ext4. Ten obraz można skompresować za pomocą biblioteki gzip lub zstd.
Proces generowania różnicowego rekompresuje docelową aktualizację SWU przy użyciu kompresji zstd w celu uzyskania optymalnej różnicy. Zaimportuj tę rekompresowaną docelową aktualizację SWU do usługi Device Update wraz z wygenerowanym plikiem aktualizacji różnicowej.
W programie SWUpdate na urządzeniu należy również włączyć dekompresję zstd.
- Ten proces wymaga użycia programu SWUpdate 2019.11 lub nowszego.

Konfigurowanie urządzenia za pomocą agenta usługi Device Update i składnika procesora różnicowego

Aby urządzenie mogło pobierać i instalować aktualizacje różnicowe z usługi Device Update, potrzebne są kilka składników obecnych i skonfigurowanych.

Agent usługi Device Update

Agent usługi Device Update organizuje proces aktualizacji na urządzeniu, w tym akcje pobierania, instalowania i ponownego uruchamiania. Dodaj agenta usługi Device Update do urządzenia i skonfiguruj go do użycia. Użyj agenta w wersji 1.0 lub nowszej. Aby uzyskać instrukcje, zobacz Aprowizowanie agenta usługi Device Update.

Procedura obsługi aktualizacji

Program obsługi aktualizacji integruje się z agentem usługi Device Update w celu przeprowadzenia rzeczywistej instalacji aktualizacji. W przypadku aktualizacji różnicowych zacznij od microsoft/swupdate:2 programu obsługi aktualizacji, jeśli nie masz jeszcze własnej procedury obsługi aktualizacji SWUpdate, którą chcesz zmodyfikować. Jeśli używasz własnej procedury obsługi aktualizacji, pamiętaj, aby włączyć dekompresję zstd w programie SWUpdate.

Procesor różnicowy

Procesor różnicowy ponownie tworzy oryginalny plik obrazu SWU na urządzeniu po pobraniu pliku różnicowego, aby program obsługi aktualizacji mógł zainstalować plik SWU. Kod procesora różnicowego jest dostępny w repozytorium GitHub Azure/iot-hub-device-update-delta .

Aby dodać składnik procesora różnicowego do obrazu urządzenia i skonfigurować go do użycia, postępuj zgodnie z instrukcjami README.md, aby skompilować procesor różnicowy ze źródła za pomocą narzędzia CMAKE. Z tego miejsca zainstaluj obiekt udostępniony (libadudiffapi.so) bezpośrednio, kopiując go do /usr/lib katalogu:

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

Dodawanie źródłowego pliku obrazu SWU do urządzenia

Po pobraniu aktualizacji różnicowej na urządzenie należy ją porównać z prawidłowym źródłowym plikiem SWU, który był wcześniej buforowany na urządzeniu. Ten proces jest wymagany, aby aktualizacja różnicowa ponownie utworzyła pełny obraz docelowy. Najprostszym sposobem wypełnienia tego buforowanego obrazu jest wdrożenie pełnej aktualizacji obrazu na urządzeniu za pośrednictwem usługi Device Update (przy użyciu istniejących procesów importowania i wdrażania ). O ile urządzenie jest skonfigurowane z agentem aktualizacji urządzenia (wersja 1.0 lub nowsza) i procesorem różnicowym, agent aktualizacji urządzenia buforuje zainstalowany plik SWU automatycznie do późniejszego użycia aktualizacji różnicowej.

Jeśli zamiast tego chcesz bezpośrednio wstępnie wypełniać obraz źródłowy na urządzeniu, ścieżka, w której oczekiwano obrazu, to:

[BASE_SOURCE_DOWNLOAD_CACHE_PATH]/sha256-[ENCODED HASH]

Domyślnie BASE_SOURCE_DOWNLOAD_CACHE_PATH jest to ścieżka /var/lib/adu/sdc/[provider]. Wartość [provider] jest częścią updateId dostawcy dla źródłowego pliku SWU.

ENCODED_HASH to ciąg szesnastkowy base64 sha256 pliku binarnego, ale po kodowaniu do ciągu szesnastkowego base64 koduje znaki w następujący sposób:

+ zakodowane jako octets _2B
/ zakodowane jako octets _2F
= zakodowane jako octets _3D

Generowanie aktualizacji różnicowych przy użyciu narzędzia DiffGen

Wymagania wstępne dotyczące środowiska

Przed utworzeniem różnic za pomocą narzędzia DiffGen należy pobrać kilka elementów i/lub zainstalować je na maszynie środowiska. Zalecamy środowisko systemu Linux, a w szczególności Ubuntu 20.04 (lub Podsystem Windows dla systemu Linux, jeśli jest natywnie w systemie Windows).

Poniższa tabela zawiera listę potrzebnych zawartości, gdzie je pobrać, oraz zalecaną instalację w razie potrzeby:

Nazwa binarna	Gdzie uzyskać	Jak zainstalować
DiffGen	Azure/iot-hub-device-update-delta repozytorium GitHub	W folderze głównym wybierz pozycję Microsoft.Azure.DeviceUpdate.Diffs.[ version].nupkg plik. Dowiedz się więcej o pakietach NuGet.
. NETCore Runtime, wersja 6.0.0	Za pośrednictwem terminala/Menedżer pakietów	Instrukcje dotyczące systemu Linux. Wymagane jest tylko środowisko uruchomieniowe.

Zależności

Zstd_compression_tool służy do dekompresowania plików obrazów archiwum i ponownego ich dekompresowania zstd. Ten proces gwarantuje, że wszystkie pliki archiwum używane do generowania różnic mają ten sam algorytm kompresji dla obrazów wewnątrz archiwów.

Polecenia instalowania wymaganych pakietów/bibliotek:

sudo apt update  
sudo apt-get install -y python3 python3-pip  
sudo pip3 install libconf zstandard

Tworzenie aktualizacji różnicowej przy użyciu narzędzia DiffGen

Narzędzie DiffGen jest uruchamiane z kilkoma argumentami. Wszystkie argumenty są wymagane, a ogólna składnia jest następująca:

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

Skrypt recompress_tool.py jest uruchamiany w celu utworzenia pliku [recompressed_target_archive], który następnie jest używany zamiast [target_archive] jako plik docelowy do tworzenia różnic.
Pliki obrazów w obrębie [recompressed_target_archive] są kompresowane za pomocą pliku zstd.

Jeśli pliki SWU są podpisane (prawdopodobnie), potrzebujesz również innego argumentu:

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

Oprócz używania [recompressed_target_archive] jako pliku docelowego, podanie parametru ciągu polecenia podpisywania jest uruchamiane recompress_and_sign_tool.py, aby utworzyć plik [recompressed_target_archive] i mieć plik sw-description w podpisie archiwum (co oznacza, że plik sw-description.sig jest obecny). Przykładowy sign_file.sh skrypt można użyć z repozytorium GitHub Azure/iot-hub-device-update-delta . Otwórz skrypt, edytuj go, aby dodać ścieżkę do pliku klucza prywatnego, a następnie zapisz go. Zobacz sekcję przykłady, aby zapoznać się z przykładowym użyciem.

W poniższej tabeli opisano bardziej szczegółowo argumenty:

Argument	opis
[source_archive]	Jest to obraz, na podstawie którego jest oparta delta podczas tworzenia różnicy. Ważne: ten obraz musi być identyczny z obrazem, który jest już obecny na urządzeniu (na przykład buforowany z poprzedniej aktualizacji).
[target_archive]	Jest to obraz, do którego funkcja delta aktualizuje urządzenie.
[output_path]	Ścieżka (w tym żądana nazwa generowanego pliku różnicowego) na maszynie hosta, na której plik różnicowy jest umieszczany po utworzeniu. Jeśli ścieżka nie istnieje, narzędzie go utworzy.
[log_folder]	Ścieżka na maszynie hosta, na której są tworzone dzienniki. Zalecamy zdefiniowanie tej lokalizacji jako folderu podrzędnego ścieżki wyjściowej. Jeśli ścieżka nie istnieje, narzędzie go utworzy.
[working_folder]	Ścieżka na maszynie, na której są umieszczane zabezpieczenia i inne pliki robocze podczas generowania różnicy. Zalecamy zdefiniowanie tej lokalizacji jako podfolderu ścieżki wyjściowej. Jeśli ścieżka nie istnieje, narzędzie go utworzy.
[recompressed_target_archive]	Ścieżka na maszynie hosta, na której jest tworzony rekompresowany plik docelowy. Ten plik jest używany zamiast <target_archive> jako plik docelowy do generowania różnic. Jeśli ta ścieżka istnieje przed wywołaniem narzędzia DiffGenTool, ścieżka zostanie zastąpiona. Zalecamy zdefiniowanie tej ścieżki jako pliku w podfolderze ścieżki wyjściowej.
"[signing_command]" (opcjonalnie)	Dostosowywalne polecenie używane do podpisywania pliku sw-description w rekompresowanym pliku archiwum. Plik sw-description w rekompresowanym archiwum jest używany jako parametr wejściowy dla polecenia podpisywania; Narzędzie DiffGenTool oczekuje, że polecenie podpisywania utworzy nowy plik podpisu przy użyciu nazwy danych wejściowych z dołączonym `.sig` . Wokół parametru w cudzysłowach jest potrzebny, aby całe polecenie było przekazywane jako pojedynczy parametr. Ponadto należy unikać umieszczania znaku "~" w ścieżce klucza używanej do podpisywania i użyć pełnej ścieżki głównej (na przykład użyj /home/USER/keys/priv.pem zamiast ~/keys/priv.pem).

Przykłady narzędzia DiffGen

W tych przykładach korzystamy z katalogu /mnt/o/temp (w programie WSL):

Tworzenie różnic między plikiem źródłowym danych wejściowych i rekompresowanym plikiem docelowym:

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]

Jeśli używasz również parametru podpisywania (wymaganego, jeśli plik SWU jest podpisany), możesz użyć przykładowego sign_file.sh skryptu, do którego odwołujesz się wcześniej. Najpierw otwórz skrypt i edytuj go, aby dodać ścieżkę do pliku klucza prywatnego. Zapisz skrypt, a następnie uruchom narzędzie DiffGen w następujący sposób:

Tworzenie różnic między plikiem źródłowym danych wejściowych i rekompresowanym/ponownie podpisanym plikiem docelowym:

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

Importowanie wygenerowanej aktualizacji różnicowej

Podstawowy proces importowania aktualizacji do usługi Device Update nie zmienia się w przypadku aktualizacji różnicowych, dlatego jeśli jeszcze tego nie zrobiono, zapoznaj się z tą stroną: Jak przygotować aktualizację do zaimportowania do usługi Azure Device Update dla usługi IoT Hub

Generowanie manifestu importu

Pierwszym krokiem importowania aktualizacji do usługi Device Update jest zawsze utworzenie manifestu importu, jeśli jeszcze go nie masz. Aby uzyskać więcej informacji na temat manifestów importu, zobacz Importowanie aktualizacji do usługi Device Update. W przypadku aktualizacji różnicowych manifest importu musi odwoływać się do dwóch plików:

Rekompresowany docelowy obraz SWU utworzony podczas uruchamiania narzędzia DiffGen.
Plik różnicowy utworzony podczas uruchamiania narzędzia DiffGen.

Funkcja aktualizacji różnicowej używa funkcji nazywanej powiązanymi plikami, która wymaga manifestu importu w wersji 5 lub nowszej.

Aby utworzyć manifest importu dla aktualizacji różnicowej przy użyciu funkcji powiązanych plików, należy dodać powiązane pliki i pobrać Obiekty programuHandler do manifestu importu.

relatedFiles Użyj obiektu , aby określić informacje o pliku aktualizacji różnicowej, w tym nazwę pliku, rozmiar pliku i skrót sha256. Co ważne, należy również określić dwie właściwości, które są unikatowe dla funkcji aktualizacji różnicowej:

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

Obie te właściwości są specyficzne dla źródłowego pliku obrazu SWU użytego jako dane wejściowe narzędzia DiffGen podczas tworzenia aktualizacji różnicowej. Informacje o źródłowym obrazie SWU są potrzebne w manifeście importu, mimo że w rzeczywistości nie importujesz obrazu źródłowego. Składniki różnicowe na urządzeniu używają tych metadanych dotyczących obrazu źródłowego, aby zlokalizować obraz na urządzeniu po pobraniu różnicy.

downloadHandler Użyj obiektu , aby określić sposób organizowania aktualizacji różnicowej przez agenta usługi Device Update przy użyciu funkcji powiązanych plików. Jeśli nie dostosowujesz własnej wersji agenta usługi Device Update na potrzeby funkcji różnicowej, należy użyć tylko tej procedury pobierania:

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

Interfejs wiersza polecenia platformy Azure umożliwia wygenerowanie manifestu importu dla aktualizacji różnicowej. Jeśli wcześniej nie użyto interfejsu wiersza polecenia platformy Azure do utworzenia manifestu importu, zobacz Tworzenie podstawowego manifestu importu.

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

Zapisz wygenerowany kod JSON manifestu importu do pliku z rozszerzeniem .importmanifest.json

Importowanie za pomocą witryny Azure Portal

Po utworzeniu manifestu importu możesz zaimportować aktualizację różnicową. Aby zaimportować, postępuj zgodnie z instrukcjami w temacie Dodawanie aktualizacji do usługi Device Update dla usługi IoT Hub. Podczas importowania należy uwzględnić następujące elementy:

Plik manifestu importu .json utworzony w poprzednim kroku.
Rekompresowany docelowy obraz SWU utworzony podczas uruchamiania narzędzia DiffGen.
Plik różnicowy utworzony podczas uruchamiania narzędzia DiffGen.

Wdrażanie aktualizacji różnicowej na urządzeniach

Podczas wdrażania aktualizacji różnicowej środowisko w witrynie Azure Portal wygląda identycznie, jak w przypadku wdrażania regularnej aktualizacji obrazu. Aby uzyskać więcej informacji na temat wdrażania aktualizacji, zobacz Wdrażanie aktualizacji przy użyciu usługi Device Update dla usługi Azure IoT Hub.

Po utworzeniu wdrożenia aktualizacji różnicowej usługa Device Update i klient automatycznie określi, czy istnieje prawidłowa aktualizacja różnicowa dla każdego wdrażanego urządzenia. Jeśli znaleziono prawidłową różnicę, aktualizacja różnicowa zostanie pobrana i zainstalowana na tym urządzeniu. Jeśli nie znaleziono prawidłowej aktualizacji różnicowej, zamiast tego zostanie pobrana pełna aktualizacja obrazu (rekompresowany docelowy obraz SWU). Takie podejście zapewnia, że wszystkie urządzenia, na których wdrażasz aktualizację, aby uzyskać dostęp do odpowiedniej wersji.

Istnieją trzy możliwe wyniki wdrożenia aktualizacji różnicowej:

Aktualizacja różnicowa została pomyślnie zainstalowana. Urządzenie jest w nowej wersji.
Aktualizacja różnicowa była niedostępna lub nie powiodła się, ale zamiast tego wystąpiła pomyślna instalacja rezerwowa pełnego obrazu. Urządzenie jest w nowej wersji.
Zarówno delta, jak i powrót do pełnego obrazu nie powiodły się. Urządzenie jest nadal w starej wersji.

Aby określić, które z powyższych wyników wystąpiły, możesz wyświetlić wyniki instalacji z kodem błędu i rozszerzonym kodem błędu, wybierając dowolne urządzenie, które jest w stanie niepowodzenia. W razie potrzeby można również zbierać dzienniki z wielu nieudanych urządzeń.

Jeśli aktualizacja różnicowa zakończyła się pomyślnie, na urządzeniu jest wyświetlany stan "Powodzenie".

Jeśli aktualizacja różnicowa nie powiodła się, ale nie powiodła się powrót do pełnego obrazu, zostanie wyświetlony następujący stan błędu:

resultCode: [wartość większa niż 0]
extendedResultCode: [non-zero]

Jeśli aktualizacja zakończyła się niepowodzeniem, zostanie wyświetlony stan błędu, który można interpretować przy użyciu następujących instrukcji:

Zacznij od błędów agenta aktualizacji urządzeń w pliku result.h.

Błędy agenta aktualizacji urządzeń specyficzne dla funkcji obsługi pobierania używanej do aktualizacji różnicowych zaczynają się od 0x9:

Składnik	Dziesiętne	Hex	Uwaga
EXTENSION_MANAGER	0	0x00	Wskazuje błędy logiki procedury obsługi pobierania menedżera rozszerzeń. Przykład: 0x900XXXXX
PLUGIN	1	0x01	Wskazuje błędy użycia bibliotek udostępnionych wtyczki programu obsługi pobierania. Przykład: 0x901XXXXX
ZASTRZEŻONE	2 - 7	0x02 — 0x07	Zarezerwowane dla programu obsługi pobierania. Przykład: 0x902XXXXX
CZĘSTO	8	0x08	Wskazuje błędy w logice najwyższego poziomu rozszerzenia programu obsługi pobierania delty. Przykład: 0x908XXXXX
SOURCE_UPDATE_CACHE	9	0x09	Wskazuje błędy w pamięci podręcznej aktualizacji źródłowej rozszerzenia programu obsługi pobierania delta. Przykład: 0x909XXXXX
DELTA_PROCESSOR	10	0x0A	Kod błędu dotyczący błędów z interfejsu API procesora różnicowego. Przykład: 0x90AXXXXX

Jeśli kod błędu nie jest obecny w pliku result.h, prawdopodobnie wystąpi błąd w składniku procesora różnicowego (niezależnie od agenta usługi Device Update). Jeśli tak, extendedResultCode jest ujemną wartością dziesiętną następującego formatu szesnastkowego: 0x90AXXXXX
- 9 to "Delta Facility"
- 0A to "Składnik procesora różnicowego" (ADUC_COMPONENT_DELTA_DOWNLOAD_HANDLER_DELTA_PROCESSOR)
- XXXXX to kod błędu 20-bitowego z procesora różnicowego FIT

Jeśli nie możesz rozwiązać problemu na podstawie informacji o kodzie błędu, zgłoś problem z usługą GitHub, aby uzyskać dalszą pomoc.

Następne kroki

Rozwiązywanie typowych problemów