Compartilhar via


Atualizações delta (Visualização)

As atualizações delta permitem gerar pequenas atualizações que representam apenas as alterações entre duas atualizações completas, uma imagem de origem e uma imagem de destino. Essa abordagem é ideal para reduzir a largura de banda usada para baixar uma atualização para um dispositivo, especialmente se houver apenas algumas alterações entre as atualizações de origem e de destino.

Observação

O recurso de atualização delta na Atualização de Dispositivo do Azure para Hub IoT está atualmente em visualização pública.

Requisitos para usar atualizações delta na Atualização de Dispositivo para Hub IoT

  • Os arquivos de atualização de origem e de destino devem estar no formato SWUpdate (SWU).
  • Em cada arquivo SWUpdate, deve haver uma imagem bruta que use o sistema de arquivos Ext2, Ext3 ou Ext4.

O processo de geração delta recompacta a atualização SWU de destino usando a compactação gzip para produzir um delta ideal. Você importa a atualização SWU de destino recompactada para o serviço de Atualização de Dispositivo, juntamente com o arquivo de atualização delta gerado.

Configuração do agente de Atualização de Dispositivo para o componente do processador delta

Para baixar e instalar atualizações delta do serviço atualização de dispositivo, seu dispositivo precisa do agente de Atualização de Dispositivo com o manipulador de atualização e o componente do processador delta presentes e configurados.

Agente de Atualização de Dispositivo

O agente de Atualização de Dispositivo orquestra o processo de atualização no dispositivo, incluindo ações de download, instalação e reinicialização. Para adicionar o agente de Atualização de Dispositivo a um dispositivo e configurá-lo para uso, consulte provisionamento do agente de Atualização de Dispositivo. Use o agente versão 1.0 ou posterior.

Manipulador de atualização

Um manipulador de atualização se integra ao agente de Atualização de Dispositivo para executar a instalação de atualização real. Para atualizações delta, comece com o microsoft/swupdate:2 manipulador de atualização caso ainda não tinha seu próprio manipulador de atualização SWUpdate que deseja modificar.

Processador delta

O processador delta em Azure/iot-hub-device-update-delta recria o arquivo de imagem SWU original em seu dispositivo após o download do arquivo delta, para que o manipulador de atualização possa instalar o arquivo SWU. Para adicionar o componente do processador delta à imagem do dispositivo e configurá-lo para uso, você pode baixar um pacote Debian para Ubuntu 20.04 e posterior de https://github.com/Azure/iot-hub-device-update-delta/tree/main/preview/2.0.0.

Se você usar outra distribuição, siga as instruções de README.md para usar o CMAKE para criar o processador delta de origem. A partir daí, instale o objeto compartilhado libadudiffapi.so diretamente copiando-o para o diretório /usr/lib, da seguinte maneira:

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

Adicionar um arquivo de imagem SWU de origem ao dispositivo

Depois que o arquivo de atualização delta é baixado em um dispositivo, ele é comparado com um <source_archive> válido armazenado anteriormente em cache no dispositivo. Esse processo permite que a atualização delta recrie a imagem de destino completa.

A maneira mais simples de preencher essa imagem armazenada em cache é importar e implantar uma atualização de imagem completa no dispositivo por meio do serviço de Atualização de Dispositivo. Se o dispositivo estiver configurado com o agente de Atualização de Dispositivo versão 1.0 ou posterior e o processador delta, o agente armazenará em cache o arquivo SWU instalado automaticamente para uso posterior da atualização delta.

Se você quiser pré-preencher diretamente a imagem de origem em seu dispositivo, o caminho em que a imagem é esperada é <BASE_SOURCE_DOWNLOAD_CACHE_PATH>/sha256-<ENCODED HASH>. Por padrão, <BASE_SOURCE_DOWNLOAD_CACHE_PATH> é o caminho /var/lib/adu/sdc/<provedor>. O valor provider é a parte provider da updateId do arquivo SWU de origem.

ENCODED_HASH é a cadeia de caracteres hexadecimais base64 do SHA256 do binário, mas após a codificação para a cadeia de caracteres hexadecimais base64, ela codifica os caracteres da seguinte maneira:

  • + codificado como octets _2B
  • / codificado como octets _2F
  • = codificado como octets _3D

Geração de atualização delta usando a ferramenta DiffGen

Você pode criar atualizações delta usando a ferramenta DiffGen (Geração DiffGen).

Pré-requisitos do ambiente

Antes de criar deltas com DiffGen, você precisa baixar e instalar várias coisas no computador do ambiente. Idealmente, use um ambiente do Ubuntu 20.04 Linux ou o Subsistema do Windows para Linux se você estiver no Windows.

A tabela a seguir mostra o conteúdo necessário, onde obtê-lo e a instalação recomendada, se necessário.

Nome binário Onde adquirir Como instalar o
DiffGen Repositório GitHub Azure/iot-hub-device-update-delta Baixe a versão correspondente ao sistema operacional ou à distribuição no computador a ser usada para gerar atualizações delta.
.NETCore runtime, versão 8.0.0 Por meio de gerenciadores de terminal ou pacotes Instale o .NET no Linux. Somente o runtime é necessário.

Criação de atualização delta usando DiffGen

A ferramenta DiffGen é executada com os seguintes argumentos e sintaxe necessários:

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

O comando anterior executa o script recompress_tool.py, que cria o <recompressed_target_file>. DiffGen, em seguida, usa o <recompressed_target_file> em vez de <target_archive> como o arquivo de destino para criar a diferença. Os arquivos de imagem dentro do <recompressed_target_archive> são compactados com gzip.

Se os arquivos SWU estiverem assinados, eles também exigirão o argumento <signing_command> no comando DiffGen:

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

O DiffGenTool com o parâmetro de cadeia de caracteres de comando de assinatura executa o script recompress_and_sign_tool.py. Esse script cria o <recompressed_target_file>. Além disso, esse script também assina o arquivo sw-description no arquivo morto para criar um arquivo sw-description.sig.

Você pode usar o script sign_file.sh de exemplo do repositório GitHub Azure/iot-hub-device-update-delta para criar uma diferença entre o arquivo de origem de entrada e um arquivo de destino recompactado e reassinado. Abra o script, edite-o para adicionar o caminho ao arquivo de chave privada e salve-o. Consulte a seção Exemplos para uso de exemplo.

A tabela a seguir descreve os argumentos com mais detalhes:

Argumento Descrição
<source_archive> A imagem base que DiffGen usa como ponto de partida para criar o delta. Importante: essa imagem deve ser idêntica à imagem já presente no dispositivo, por exemplo, armazenada em cache de uma atualização anterior.
<target_archive> A imagem para a qual o delta atualiza o dispositivo.
<output_path> O caminho no computador host para colocar o arquivo delta após a criação, incluindo o nome desejado do arquivo delta gerado. Se o caminho não existir, a ferramenta o cria.
<log_folder> O caminho no computador host para criar logs. É melhor definir esse local como uma subpasta do caminho de saída. Se o caminho não existir, a ferramenta o cria.
<working_folder> O caminho no computador para colocar garantias e outros arquivos de trabalho durante a geração delta. É melhor definir esse local como uma subpasta do caminho de saída. Se o caminho não existir, a ferramenta o cria.
<recompressed_target_archive> O caminho no computador host no qual criar o <recompressed_target_file>. O <recompressed_target_file> é usado em vez de <target_archive> como arquivo de destino para gerar a comparação. Se esse caminho existir antes de chamar a ferramenta DiffGen, ele será substituído. É melhor definir esse arquivo em uma subpasta do caminho de saída.
"<signing_command>" (opcional) Um comando personalizável para assinar o arquivo sw-description no <recompressed_target_archive>. O arquivo sw-description no arquivo recompactado é usado como um parâmetro de entrada para o comando de assinatura. DiffGen espera que o comando de assinatura crie um novo arquivo de assinatura, usando o nome da entrada com .sig acrescentado.

Você deve cercar o parâmetro com aspas duplas para passar o comando inteiro como um único parâmetro. Evite também usar o caractere ~ em um caminho de chave usado para assinatura e use o caminho de casa completo. Por exemplo, use /home/USER/keys/priv.pem em vez de ~/keys/priv.pem.

Exemplos de DiffGen

Os exemplos a seguir operam fora do diretório /mnt/o/temp no Subsistema do Windows para Linux.

O código a seguir cria uma diferença entre o arquivo de origem de entrada e um arquivo de destino recompactado:

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

Se você também usar o parâmetro de assinatura, que deverá ser assinado se o arquivo SWU estiver assinado, você poderá usar o script sign_file.sh de exemplo mencionado anteriormente. Abra o script, edite-o para adicionar o caminho ao arquivo de chave privada, salve o script e execute DiffGen da seguinte maneira.

O código a seguir cria uma diferença entre o arquivo de origem de entrada e um arquivo de destino recompactado e reassinado:

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

Importação de atualização delta gerada

O processo básico de importação de uma atualização delta para o serviço de Atualização de Dispositivo é o mesmo de qualquer outra atualização. Caso ainda não tenha feito isso, examine Como preparar uma atualização a ser importada para a Atualização de Dispositivo do Azure para Hub IoT.

Gerar o manifesto de importação

Para importar uma atualização para o serviço de Atualização de Dispositivo, você deve ter ou criar um arquivo de manifesto de importação. Para obter mais informações, consulte Importar atualizações para a Atualização de Dispositivo.

Importar arquivos de manifesto para atualizações delta deve referenciar os seguintes arquivos que a ferramenta DiffGen criou:

  • A imagem SWU do <recompressed_target_file>
  • O <delta file>

O recurso de atualização delta usa uma funcionalidade chamada arquivos relacionados que requer um manifesto de importação versão 5 ou posterior. Para usar o recurso de arquivos relacionados, você deve incluir os objetos relatedFiles e downloadHandler no manifesto de importação.

Use o objeto relatedFiles para especificar informações sobre o arquivo de atualização delta, incluindo o nome do arquivo, o tamanho do arquivo e o hash sha256. O mais importante é que você também deve especificar as duas propriedades a seguir exclusivas para o recurso de atualização delta:

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

Ambas as propriedades são específicas para o <source image file> que você usou como entrada para a ferramenta DiffGen quando criou a atualização delta. O manifesto de importação precisa das informações sobre a imagem SWU de origem, mesmo que você não importe a imagem de origem. Os componentes delta no dispositivo usam esses metadados sobre a imagem de origem para localizar essa imagem no dispositivo depois que eles baixam a atualização delta.

Use o objeto downloadHandler para especificar como o agente de Atualização de Dispositivo orquestra a atualização delta usando o recurso de arquivos relacionados. A menos que você personalize sua própria versão do agente de Atualização de Dispositivo para funcionalidade delta, use o seguinte downloadHandler:

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

Você pode usar o comando az iot du update init v5 da CLI do Azure para gerar um manifesto de importação para sua atualização delta. Para obter mais informações, consulte Criar um manifesto de importação básico.

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

Salve o JSON do manifesto de importação gerado com a extensão de arquivo .importmanifest.json.

Importar usando o portal do Azure

Depois de criar o manifesto de importação, importe a atualização delta seguindo as instruções em Adicionar uma atualização à Atualização do Dispositivo para o Hub IoT. Você deve incluir os seguintes itens na importação:

  • O arquivo *importmanifest.json criado anteriormente nas etapas anteriores
  • A imagem SWU <recompressed_target_file> criada pela ferramenta DiffGen
  • O <delta file> criado pela ferramenta DiffGen

Implantação de atualização delta para dispositivos

A experiência de implantação de atualização delta no portal do Azure é a mesma que implantar uma atualização de imagem regular. Para obter mais informações, consulte Implantar uma atualização usando a Atualização de Dispositivo.

Depois de criar a implantação para a atualização delta, o serviço de Atualização de Dispositivo e o cliente determinam automaticamente se há uma atualização delta válida para cada dispositivo em que você está implantando. Se encontrarem um delta válido, eles baixarão e instalarão a atualização delta nesse dispositivo.

Se eles não encontrarem uma atualização delta válida, a atualização de imagem completa (a imagem SWU de destino recompactada) será baixada como um fallback. Essa abordagem garante que todos os dispositivos nos quais você está implantando a atualização cheguem à versão apropriada.

Há três resultados possíveis para uma implantação de atualização delta:

  • A atualização delta foi instalada com êxito e o dispositivo está na nova versão.
  • A atualização delta não estava disponível ou não foi instalada, mas uma instalação de fallback da imagem completa foi bem-sucedida e o dispositivo está na nova versão.
  • As instalações delta e fallback falharam e o dispositivo ainda está na versão antiga.

Para determinar qual resultado de falha ocorreu, você pode exibir os resultados da instalação com código de erro e código de erro estendido selecionando qualquer dispositivo que esteja em um estado de falha. Você também pode coletar logs de vários dispositivos com falha, se necessário.

  • Se uma atualização delta tiver sido bem-sucedida, o dispositivo mostrará o status Bem-sucedido.

  • Se uma atualização delta falhou, mas o fallback para a imagem completa foi bem-sucedido, o dispositivo mostra o seguinte status de erro:

    • resultCode: <valor maior que 0>
    • extendedResultCode: <valor diferente de zero>

Solucionar problemas de atualizações com falha

Atualizações malsucedidas exibem um status de erro que você pode interpretar usando as instruções a seguir. Comece com os erros do agente de Atualização de Dispositivo em result.h.

Os erros do agente de Atualização de Dispositivo específicos para a funcionalidade do manipulador de download de atualizações delta começam com 0x9:

Componente Decimal Hex Observação
EXTENSION_MANAGER 0 0x00 Indica erros da lógica do manipulador de download do gerenciador de extensões. Exemplo: 0x900XXXXX
PLUGIN 1 0x01 Indica erros com o uso de bibliotecas compartilhadas de plug-in do manipulador de download. Exemplo: 0x901XXXXX
RESERVADO 2 - 7 0x02 – 0x07 Reservado para o manipulador de download. Exemplo: 0x902XXXXX
COMMON 8 0x08 Indica erros na lógica de nível superior da extensão do manipulador de download delta. Exemplo: 0x908XXXXX
SOURCE_UPDATE_CACHE 9 0x09 Indica erros no cache de atualização da origem da extensão do manipulador de download delta. Exemplo: 0x909XXXXX
DELTA_PROCESSOR 10 0x0A Código de erro para erros da API do processador delta. Exemplo: 0x90AXXXXX

Se o código de erro não estiver presente em result.h, provavelmente será um erro no componente do processador delta, separado do agente de Atualização de Dispositivo. Nesse caso, o extendedResultCode é um valor decimal é negativo no formato hexadecimal 0x90AXXXXX.

  • 9 é "Delta Facility"
  • 0A é "Componente do Processador Delta" (ADUC_COMPONENT_DELTA_DOWNLOAD_HANDLER_DELTA_PROCESSOR)
  • XXXXX é o código de erro de 20 bits do processador delta da Ferramenta de Instalação de Campo (FIT)

Se você não conseguir resolver o problema com base nas informações de código de erro, registre um problema no GitHub para obter mais assistência.