Разностные обновления (предварительная версия)

Разностные обновления позволяют создавать небольшие обновления, представляющие только изменения между двумя полными обновлениями, исходным образом и целевым образом. Этот подход идеально подходит для уменьшения пропускной способности, используемой для скачивания обновления на устройство, особенно если между исходным и целевым обновлениями существует лишь несколько изменений.

Примечание.

Функция разностного обновления в обновлении устройств Azure для Центр Интернета вещей сейчас доступна в общедоступной предварительной версии.

Требования к использованию разностных обновлений в обновлении устройств для Центр Интернета вещей

• Исходные и целевые файлы обновления должны находиться в формате SWUpdate (SWU).
• В каждом файле SWUpdate должен быть необработанный образ, использующий файловую систему Ext2, Ext3 или Ext4.

Процесс создания разностного поколения повторно сжимает целевое обновление SWU с помощью сжатия gzip для получения оптимальной разности. Вы импортируете повторное обновление целевого swU в службу обновления устройств вместе с созданным файлом разностного обновления.

Конфигурация агента обновления устройства для компонента разностного процессора

Чтобы скачать и установить разностные обновления из службы обновления устройств, устройство должно иметь агент обновления устройства с обработчиком обновления и компонентом разностного процессора, который присутствует и настроен.

Агент Обновления устройств

Агент обновления устройств управляет процессом обновления на устройстве, включая скачивание, установку и перезапуск действий. Чтобы добавить агент обновления устройств на устройство и настроить его для использования, см. статью о подготовке агента обновления устройств. Используйте агент версии 1.0 или более поздней.

Обработчик обновления

Обработчик обновлений интегрируется с агентом обновления устройства для выполнения фактической установки обновления. Для разностных обновлений начните с обработчика обновлений microsoft/swupdate:2 , если у вас еще нет собственного обработчика обновления SWUpdate, который вы хотите изменить.

Разностный процессор

Разностный процессор в Azure/iot-hub-device-update-delta повторно создает исходный файл образа SWU на устройстве после загрузки разностного файла, чтобы обработчик обновлений смог установить SWU-файл. Чтобы добавить компонент разностного процессора в образ устройства и настроить его для использования, можно скачать пакет Debian для Ubuntu 20.04 и более поздних версий https://github.com/Azure/iot-hub-device-update-delta/tree/main/preview/2.0.0.

Если вы используете другой дистрибутив, следуйте инструкциям README.md , чтобы использовать CMAKE для создания разностного процессора из источника. После этого установите общий объект libadudiffapi.so непосредственно путем копирования его в каталог /usr/lib , как показано ниже.

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

Добавление исходного файла образа SWU на устройство

После скачивания файла разностного обновления на устройство он сравнивается с допустимым <source_archive> ранее кэшированным на устройстве. Этот процесс позволяет обновить разностное обновление для повторного создания полного целевого образа.

Самый простой способ заполнения кэшированного образа — импортировать и развернуть полное обновление образа на устройстве с помощью службы обновления устройств. Если устройство настроено с агентом обновления устройств версии 1.0 или более поздней и разностным процессором, агент кэширует установленный SWU-файл автоматически для последующего использования разностного обновления.

Если вы хотите напрямую предварительно заполнить исходный образ на устройстве, путь, в котором ожидается <BASE_SOURCE_DOWNLOAD_CACHE_PATH>/sha256-<ENCODED HASH>изображение. По умолчанию <BASE_SOURCE_DOWNLOAD_CACHE_PATH> — это путь /var/lib/adu/sdc/<provider>. Это provider значение является provider частью updateId для исходного SWU-файла.

ENCODED_HASH — это строка шестнадцатеричной строки SHA256 двоичного файла, но после кодирования в шестнадцатеричную строку base64 кодирует символы следующим образом:

• + закодированное как octets _2B
• / закодированное как octets _2F
• = закодированное как octets _3D

Создание разностных обновлений с помощью средства DiffGen

Вы можете создавать разностные обновления с помощью средства Diff Generation (DiffGen).

Предварительные требования среды

Прежде чем создавать разностные значения с помощью DiffGen, необходимо скачать и установить несколько элементов на компьютере среды. В идеале используйте среду Linux Ubuntu 20.04 или подсистема Windows для Linux, если вы находитесь в Windows.

В следующей таблице показано необходимое содержимое, где его получить и при необходимости рекомендуется установить.

Двоичное имя	Где получить	Как установить
DiffGen	Репозиторий GitHub azure/iot-hub-device-update-delta GitHub	Скачайте версию, соответствующую ОС или дистрибутиву на компьютере, чтобы создать разностные обновления.
. Среда выполнения NETCore, версия 8.0.0	Через диспетчеры терминалов или пакетов	Установите .NET в Linux. Требуется только среда выполнения.

Создание разностного обновления с помощью DiffGen

Средство DiffGen выполняется со следующими обязательными аргументами и синтаксисом:

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

Предыдущая команда запускает скрипт recompress_tool.py , который создает <recompressed_target_file>. Затем DiffGen использует <recompressed_target_file>вместо <target_archive> целевого файла для создания диффа. Файлы изображений в ней <recompressed_target_archive> сжимаются с помощью gzip.

Если файлы SWU подписаны, они также требуют <signing_command> аргумента в команде DiffGen:

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

DiffGenTool с параметром командной строки подписывания запускает скрипт recompress_and_sign_tool.py . Этот скрипт создает <recompressed_target_file>. Кроме того, этот скрипт также подписывает файл sw-description в архиве для создания sw-description.sig-файла.

Пример скрипта sign_file.sh можно использовать из репозитория GitHub Azure/iot-hub-device-update-delta GitHub, чтобы создать дифф между входным исходным файлом и повторно подписанным целевым файлом. Откройте скрипт, измените его, чтобы добавить путь к файлу закрытого ключа и сохранить его. См. раздел "Примеры" для примера использования.

В следующей таблице подробно описаны аргументы:

Аргумент	Description
<source_archive>	Базовый образ, который DiffGen использует в качестве отправной точки для создания разностной области. Важно. Это изображение должно быть идентично изображению, которое уже присутствует на устройстве, например кэшированное из предыдущего обновления.
<target_archive>	Изображение, на которое обновляется разностное устройство.
<output_path>	Путь на хост-компьютере для размещения разностного файла после создания, включая требуемое имя созданного разностного файла. Если путь не существует, средство создает его.
<log_folder>	Путь на хост-компьютере для создания журналов. Лучше всего определить это расположение как вложенную папку выходного пути. Если путь не существует, средство создает его.
<working_folder>	Путь к компьютеру для размещения залога и других рабочих файлов во время разностного создания. Лучше всего определить это расположение как вложенную папку выходного пути. Если путь не существует, средство создает его.
<recompressed_target_archive>	Путь на хост-компьютере для создания <recompressed_target_file> в. Он <recompressed_target_file> используется вместо целевого <target_archive> файла для создания диффа. Если этот путь существует перед вызовом средства DiffGen, он перезаписан. Лучше всего определить этот файл в подпапке выходного пути.
"<signing_command>" (необязательно)	Настраиваемая команда для подписывания файла sw-description внутри <recompressed_target_archive>. Файл sw-description в повторном архиве используется в качестве входного параметра для команды подписывания. DiffGen ожидает, что команда подписи создаст новый файл подписи, используя имя входных данных с добавленным SIG . Необходимо окружить параметр двойными кавычками, чтобы передать всю команду в виде одного параметра. Кроме того, избегайте использования символа ~ в пути ключа, используемого для подписывания, и используйте полный путь дома. Например, используйте /home/USER/keys/priv.pem вместо ~/keys/priv.pem.

Примеры DiffGen

В следующих примерах используется каталог /mnt/o/temp в подсистема Windows для Linux.

Следующий код создает дифф между входным исходным файлом и повторно сжатым целевым файлом:

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

Если вы также используете параметр подписывания, который должен быть подписан в файле SWU, можно использовать пример скрипта sign_file.sh , упоминаемого ранее. Откройте скрипт, измените его, чтобы добавить путь к файлу закрытого ключа, сохранить скрипт, а затем запустить DiffGen следующим образом.

Следующий код создает дифф между входным исходным файлом и повторно подписанным целевым файлом:

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

Импорт сгенерированного разностного обновления

Базовый процесс импорта разностного обновления в службу обновления устройств совпадает с любым другим обновлением. Если вы еще не сделали этого, ознакомьтесь с тем, как подготовить обновление для импорта в обновление устройств Azure для Центр Интернета вещей.

Создание манифеста импорта

Чтобы импортировать обновление в службу обновления устройств, необходимо создать или создать файл манифеста импорта. Дополнительные сведения см. в разделе "Импорт обновлений в обновление устройства".

Импорт файлов манифеста для разностных обновлений должен ссылаться на следующие файлы, созданные средством DiffGen:

• Образ <recompressed_target_file> SWU
• <delta file>

Функция разностного обновления использует функцию, называемую связанными файлами , которые требуют манифеста импорта версии 5 или более поздней версии. Чтобы использовать функцию связанных файлов, необходимо включить связанные файлы и объекты downloadHandler в манифест импорта.

Объект используется relatedFiles для указания сведений о разностном файле обновления, включая имя файла, размер файла и хэш sha256. Важно также указать следующие два свойства, уникальные для функции разностного обновления:

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

Оба свойства относятся к <source image file> входным данным средства DiffGen при создании разностного обновления. Манифест импорта должен иметь сведения об исходном образе SWU, даже если вы фактически не импортируете исходный образ. Разностные компоненты на устройстве используют эти метаданные о исходном изображении, чтобы найти это изображение на устройстве после скачивания разностного обновления.

downloadHandler Используйте объект, чтобы указать, как агент обновления устройств оркеструет разностное обновление с помощью функции связанных файлов. Если вы не настраиваете собственную версию агента обновления устройств для разностной функциональности, используйте следующее downloadHandler:

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

Для создания манифеста импорта для разностного обновления можно использовать команду Azure CLI 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>"}' 

Сохраните созданный манифест импорта в формате JSON с помощью расширения файла .importmanifest.json.

Импорт с помощью портала Azure

После создания манифеста импорта импортируйте разностное обновление, следуя инструкциям в разделе "Добавление обновления в обновление устройства для Центр Интернета вещей". В импорт необходимо включить следующие элементы:

• Файл *importmanifest.json , созданный ранее на предыдущих шагах
• Изображение <recompressed_target_file> SWU созданного средства DiffGen
• Созданное <delta file> средство DiffGen

Развертывание разностного обновления на устройствах

Развертывание разностного обновления в портал Azure совпадает с развертыванием регулярного обновления образа. Дополнительные сведения см. в статье "Развертывание обновления с помощью обновления устройства".

После создания развертывания для разностного обновления служба обновления устройств и клиент автоматически определяют наличие допустимого разностного обновления для каждого развернутого устройства. Если они находят допустимую разностную информацию, они загружают и устанавливают разностное обновление на этом устройстве.

Если они не находят допустимое разностное обновление, то полное обновление образа (повторножатый целевой образ SWU) загружается вместо этого в качестве резервной версии. Этот подход гарантирует, что все устройства, которые вы развертываете обновление, чтобы получить соответствующую версию.

Существует три возможных результата развертывания разностного обновления:

• Разностное обновление установлено успешно, и устройство находится в новой версии.
• Разностное обновление было недоступно или не удалось установить, но резервная установка полного образа была успешной, и устройство находится на новой версии.
• Не удалось установить разностную и резервную установку, и устройство по-прежнему находится в старой версии.

Чтобы определить, какой результат сбоя произошел, можно просмотреть результаты установки с кодом ошибки и расширенным кодом ошибки, выбрав любое устройство, которое находится в состоянии сбоя. Вы также можете собирать журналы с нескольких неудачных устройств при необходимости.

• Если разностное обновление выполнено успешно, устройство отображает состояние "Успешно".

• Если разностное обновление завершилось сбоем, но резервный переход к полному изображению выполнен успешно, устройство отображает следующее состояние ошибки:

  • resultCode: <значение больше 0>
  • extendedResultCode: <ненулевое значение>

Устранение неполадок с неудачными обновлениями

Неудачные обновления отображают состояние ошибки, которое можно интерпретировать с помощью следующих инструкций. Начните с ошибок агента обновления устройства в result.h.

Ошибки агента обновления устройства, относящиеся к функциям обработчика загрузки разностных обновлений, начинаются с 0x9:

Компонент	Десятичное число	Hex	Примечание.
EXTENSION_MANAGER	0	0x00	Указывает ошибки из логики обработчика загрузки диспетчера расширений. Пример: 0x900XXXXX
ПОДКЛЮЧАЕМЫЙ МОДУЛЬ	1	0x01	Указывает ошибки при использовании общих библиотек подключаемых модулей обработчика загрузки. Пример: 0x901XXXXX
RESERVED	2–7	0x02 — 0x07	Зарезервировано для обработчика загрузки. Пример: 0x902XXXXX
СТАНДАРТНЫЕ	8	0x08	Указывает ошибки в логике расширения верхнего уровня обработчика разностного скачивания. Пример: 0x908XXXXX
SOURCE_UPDATE_CACHE	9	0x09	Указывает ошибки в кэше исходного обновления расширения расширения разностного обработчика загрузки. Пример: 0x909XXXXX
DELTA_PROCESSOR	10	0x0A	Код ошибки из API разностного процессора. Пример: 0x90AXXXXX

Если код ошибки не присутствует в result.h, это, вероятно, ошибка в компоненте разностного процессора отдельно от агента обновления устройства. Если да, extendedResultCode это отрицательное десятичное значение в шестнадцатеричном формате 0x90AXXXXX.

• 9 — Delta Facility( Delta Facility)
• 0A — "Компонент разностного процессора" (ADUC_COMPONENT_DELTA_DOWNLOAD_HANDLER_DELTA_PROCESSOR)
• XXXXX — это 20-разрядный код ошибки из разностного процессора средства установки полей (FIT)

Если вы не можете решить проблему на основе сведений об коде ошибки, отправьте проблему GitHub, чтобы получить дополнительную помощь.

Связанный контент

• Обновление устройств Azure для схемы манифеста импорта Центр Интернета вещей
• Устранение общих проблем