Udostępnij za pośrednictwem

Aktualizacje różnicowe (wersja zapoznawcza)

  • Artykuł

Aktualizacje różnicowe umożliwiają generowanie małych aktualizacji reprezentujących 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 na urządzenie, zwłaszcza jeśli między aktualizacjami źródłowymi i docelowymi istnieje tylko kilka zmian.

Uwaga

Funkcja aktualizacji różnicowej w usłudze Azure Device Update dla usługi IoT Hub 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ą być w formacie SWUpdate (SWU).
  • W każdym pliku SWUpdate musi istnieć nieprzetworzone obrazy korzystające z systemu plików Ext2, Ext3 lub Ext4.

Proces generowania różnicy rekompresuje docelową aktualizację SWU przy użyciu kompresji gzip w celu uzyskania optymalnej różnicy. Zaimportowano rekompresowaną docelową aktualizację SWU do usługi Device Update wraz z wygenerowanym plikiem aktualizacji różnicowej.

Konfiguracja agenta usługi Device Update dla składnika procesora różnicowego

Aby pobrać i zainstalować aktualizacje różnicowe z usługi Device Update, urządzenie wymaga agenta aktualizacji urządzeń z obecnym i skonfigurowanym składnikiem procesora różnicowego i programu obsługi aktualizacji.

Agent usługi Device Update

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

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ć.

Procesor różnicowy

Procesor różnicowy na platformie Azure/iot-hub-device-update-delta ponownie tworzy oryginalny plik obrazu SWU na urządzeniu po pobraniu plików różnicowych, aby program obsługi aktualizacji mógł zainstalować plik SWU. Aby dodać składnik procesora różnicowego do obrazu urządzenia i skonfigurować go do użycia, możesz pobrać pakiet Debian dla systemu Ubuntu 20.04 lub nowszego z witryny https://github.com/Azure/iot-hub-device-update-delta/tree/main/preview/2.0.0.

Jeśli używasz innej dystrybucji, postępuj zgodnie z instrukcjami README.md , aby zamiast tego skompilować procesor różnicowy ze źródła za pomocą narzędzia CMAKE. W tym miejscu zainstaluj obiekt udostępniony libadudiffapi.so bezpośrednio, kopiując go do katalogu /usr/lib w następujący sposób:

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

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

Po pobraniu pliku aktualizacji różnicowej na urządzenie jest porównywany z prawidłowym <source_archive> wcześniej zapisanym w pamięci podręcznej na urządzeniu. Ten proces umożliwia aktualizacji różnicowej ponowne utworzenie pełnego obrazu docelowego.

Najprostszym sposobem wypełnienia tego buforowanego obrazu jest zaimportowanie i wdrożenie pełnej aktualizacji obrazu na urządzeniu za pośrednictwem usługi Device Update. Jeśli urządzenie jest skonfigurowane z agentem usługi Device Update w wersji 1.0 lub nowszej i procesorem różnicowym, agent 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 provider częścią updateId ź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

Aktualizacje różnicowe można tworzyć przy użyciu narzędzia Diff Generation (DiffGen).

Wymagania wstępne dotyczące środowiska

Przed utworzeniem różnic za pomocą narzędzia DiffGen należy pobrać i zainstalować kilka rzeczy na maszynie środowiska. W idealnym przypadku należy użyć środowiska systemu Linux Ubuntu 20.04 lub Podsystem Windows dla systemu Linux, jeśli korzystasz z systemu Windows.

W poniższej tabeli przedstawiono wymaganą zawartość, miejsce jej pobrania i zalecaną instalację w razie potrzeby.

Nazwa binarna Gdzie uzyskać Jak zainstalować
DiffGen Azure/iot-hub-device-update-delta repozytorium GitHub Pobierz wersję zgodną z systemem operacyjnym lub dystrybucją na maszynie, która ma być używana do generowania aktualizacji różnicowych.
. Środowisko uruchomieniowe NETCore w wersji 8.0.0 Za pośrednictwem terminalu lub menedżerów pakietów Zainstaluj platformę .NET w systemie Linux. Wymagane jest tylko środowisko uruchomieniowe.

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

Narzędzie DiffGen jest uruchamiane z następującymi wymaganymi argumentami i składnią:

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

Poprzednie polecenie uruchamia skrypt recompress_tool.py , który tworzy <recompressed_target_file>. Funkcja DiffGen następnie używa wartości <recompressed_target_file>zamiast <target_archive> jako pliku docelowego do tworzenia różnic. Pliki obrazów w pliku <recompressed_target_archive> są kompresowane za pomocą narzędzia gzip.

Jeśli pliki SWU są podpisane, wymagają również argumentu <signing_command> w poleceniu DiffGen:

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

Narzędzie DiffGenTool z parametrem ciągu polecenia podpisywania uruchamia skrypt recompress_and_sign_tool.py . Ten skrypt tworzy element <recompressed_target_file>. Ponadto ten skrypt podpisuje również plik sw-description w archiwum, aby utworzyć plik sw-description.sig.

Możesz użyć przykładowego skryptu sign_file.sh z repozytorium GitHub Azure/iot-hub-device-update-delta , aby utworzyć różnicę między plikiem źródłowym danych wejściowych a ponownie podpisanym plikiem docelowym. Otwórz skrypt, edytuj go, aby dodać ścieżkę do pliku klucza prywatnego i zapisać 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> Obraz podstawowy używany przez narzędzie DiffGen jako punkt wyjścia do utworzenia różnicy. Ważne: ten obraz musi być identyczny z obrazem, który jest już obecny na urządzeniu, na przykład w pamięci podręcznej z poprzedniej aktualizacji.
<target_archive> Obraz, na który funkcja delta aktualizuje urządzenie.
<output_path> Ścieżka na maszynie hosta do umieszczania pliku różnicowego w pliku różnicowym po utworzeniu, w tym żądana nazwa wygenerowanego pliku różnicowego. Jeśli ścieżka nie istnieje, narzędzie go utworzy.
<log_folder> Ścieżka na maszynie hosta do utworzenia dzienników. Najlepiej jest zdefiniować tę lokalizację jako podfolder ścieżki wyjściowej. Jeśli ścieżka nie istnieje, narzędzie go utworzy.
<working_folder> Ścieżka na maszynie do umieszczania zabezpieczeń i innych plików roboczych w trakcie generowania różnicy. Najlepiej jest zdefiniować tę lokalizację jako podfolder ścieżki wyjściowej. Jeśli ścieżka nie istnieje, narzędzie go utworzy.
<recompressed_target_archive> Ścieżka na maszynie hosta do utworzenia elementu <recompressed_target_file> in. Element <recompressed_target_file> jest używany zamiast <target_archive> jako plik docelowy do generowania różnic. Jeśli ta ścieżka istnieje przed wywołaniem narzędzia DiffGen, zostanie zastąpiona. Najlepiej zdefiniować ten plik w podfolderze ścieżki wyjściowej.
"<signing_command>" (opcjonalnie) Dostosowywalne polecenie podpisywania pliku sw-description w pliku <recompressed_target_archive>. Plik sw-description w rekompresowanym archiwum jest używany jako parametr wejściowy dla polecenia podpisywania. Firma DiffGen oczekuje, że polecenie podpisywania utworzy nowy plik podpisu przy użyciu nazwy danych wejściowych z dołączonym ciągiem .sig .

Należy otoczyć parametr podwójnymi cudzysłowami, aby przekazać całe polecenie jako pojedynczy parametr. Należy również unikać używania ~ znaku w ścieżce klucza używanej do podpisywania i zamiast tego używać 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

Poniższe przykłady działają poza katalog /mnt/o/temp w Podsystem Windows dla systemu Linux.

Poniższy kod tworzy różnicę między plikiem źródłowym danych wejściowych a rekompresowanym plikiem docelowym:

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

Jeśli używasz również parametru podpisywania, który należy, jeśli plik SWU jest podpisany, możesz użyć przykładowego skryptu sign_file.sh wymienionego wcześniej. Otwórz skrypt, edytuj go, aby dodać ścieżkę do pliku klucza prywatnego, zapisać skrypt, a następnie uruchomić narzędzie DiffGen w następujący sposób.

Poniższy kod tworzy różnicę między plikiem źródłowym danych wejściowych a rekompresowanym i ponownie podpisanym plikiem docelowym:

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

Wygenerowany import aktualizacji różnicowej

Podstawowy proces importowania aktualizacji różnicowej do usługi Device Update jest taki sam jak w przypadku każdej innej aktualizacji. Jeśli jeszcze tego nie zrobiono, zapoznaj się z artykułem Jak przygotować aktualizację do zaimportowania do usługi Azure Device Update dla usługi IoT Hub.

Generowanie manifestu importu

Aby zaimportować aktualizację do usługi Device Update, musisz mieć lub utworzyć plik manifestu importu. Aby uzyskać więcej informacji, zobacz Importowanie aktualizacji do usługi Device Update.

Zaimportuj pliki manifestu dla aktualizacji różnicowych muszą odwoływać się do następujących plików utworzonych przez narzędzie DiffGen:

  • <recompressed_target_file> Obraz SWU
  • <delta file>

Funkcja aktualizacji różnicowej używa funkcji nazywanej powiązanymi plikami , która wymaga manifestu importu w wersji 5 lub nowszej. Aby użyć funkcji powiązanych plików, należy uwzględnić powiązane obiektyFiles i downloadHandler w manifeście importu.

Obiekt służy do określania relatedFiles informacji o pliku aktualizacji różnicowej, w tym nazwy pliku, rozmiaru pliku i skrótu sha256. Co najważniejsze, należy również określić następujące dwie właściwości, które są unikatowe dla funkcji aktualizacji różnicowej:

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

Obie właściwości są specyficzne dla <source image file> danych wejściowych narzędzia DiffGen podczas tworzenia aktualizacji różnicowej. Manifest importu wymaga informacji o źródłowym obrazie SWU, 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ć ten obraz na urządzeniu po pobraniu aktualizacji różnicowej.

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 dostosujesz własnej wersji agenta usługi Device Update na potrzeby funkcji różnicowej, użyj następującego polecenia downloadHandler:

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

Możesz użyć polecenia interfejsu wiersza polecenia az iot du update init v5 platformy Azure, aby wygenerować manifest importu dla aktualizacji różnicowej. Aby uzyskać więcej informacji, zobacz Tworzenie podstawowego manifestu importu.

--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 plik JSON manifestu importu przy użyciu rozszerzenia pliku .importmanifest.json.

Importowanie za pomocą witryny Azure Portal

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

  • Plik *importmanifest.json utworzony wcześniej w poprzednich krokach
  • Obraz <recompressed_target_file> SWU utworzony przez narzędzie DiffGen
  • Utworzone <delta file> narzędzie DiffGen

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

Środowisko wdrażania aktualizacji różnicowej w witrynie Azure Portal jest takie samo jak wdrażanie regularnej aktualizacji obrazu. Aby uzyskać więcej informacji, zobacz Wdrażanie aktualizacji przy użyciu usługi Device Update.

Po utworzeniu wdrożenia aktualizacji różnicowej usługa Device Update i klient automatycznie ustal, czy dla każdego wdrażanego urządzenia jest prawidłowa aktualizacja różnicowa. Jeśli znajdą prawidłową różnicę, pobierają i instalują aktualizację różnicową na tym urządzeniu.

Jeśli nie znajdą 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, a urządzenie znajduje się w nowej wersji.
  • Aktualizacja różnicowa była niedostępna lub nie powiodła się, ale instalacja rezerwowa pełnego obrazu zakończyła się pomyślnie, a urządzenie znajduje się w nowej wersji.
  • Instalacja różnicowa i rezerwowa nie powiodła się, a urządzenie jest nadal w starej wersji.

Aby określić, który wynik niepowodzenia wystąpił, możesz wyświetlić wyniki instalacji z kodem błędu i kodem rozszerzonego błędu, wybierając dowolne urządzenie 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 powrót do pełnego obrazu zakończył się pomyślnie, urządzenie wyświetla następujący stan błędu:

    • resultCode: <wartość większa niż 0>
    • extendedResultCode: <wartość niezerowa>

Rozwiązywanie problemów z nieudanymi aktualizacjami

Nieudane aktualizacje wyświetlają stan błędu, który można interpretować, korzystając z poniższych instrukcji. Zacznij od błędów agenta usługi Device Update w pliku result.h.

Błędy agenta usługi Device Update specyficzne dla funkcji obsługi pobierania 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
WTYCZKA 1 0x01 Wskazuje błędy użycia bibliotek udostępnionych wtyczki programu obsługi pobierania. Przykład: 0x901XXXXX
ZASTRZEŻONY 2 - 7 0x02 — 0x07 Zarezerwowane do obsługi pobierania. Przykład: 0x902XXXXX
CZĘSTO 8 0x08 Wskazuje błędy w logice najwyższego poziomu rozszerzenia procedury obsługi pobierania różnicowego. Przykład: 0x908XXXXX
SOURCE_UPDATE_CACHE 9 0x09 Wskazuje błędy w pamięci podręcznej aktualizacji źródłowej rozszerzenia pobierania różnicowego. 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 jest to błąd w składniku procesora różnicowego, niezależnie od agenta usługi Device Update. Jeśli tak, extendedResultCode jest to ujemna wartość dziesiętna w formacie 0x90AXXXXXszesnastkowym .

  • 9 is "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 narzędzia instalacji pól (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.

Powiązana zawartość