Conceitos de atualizações de software (prévia)

Use atualizações de software, uma funcionalidade do Azure Device Registry, para entregar atualizações remotas aos seus dispositivos em larga escala. Importe atualizações para um namespace do Registro de Dispositivo do Azure e, em seguida, use tarefas e grupos nesse namespace para implantá-las nos dispositivos.

Aplicabilidade do serviço

Atualizações de Software e Atualização de Dispositivo para Hub IoT

Atualizações de software trazem capacidades de atualização over-the-air para o Registro de Dispositivos do Azure. Ele usa o mesmo formato de manifesto de importação do Device Update para Hub IoT e permite gerenciar atualizações no nível do namespace usando grupos e jobs do Azure Device Registry.

Use as seguintes orientações para escolher a opção correta:

Tenha em mente as seguintes considerações se você já usa o Device Update para Hub IoT:

• Você não pode usar os dois no mesmo hub IoT. Nesta prévia, você pode usar atualizações de software apenas com hubs IoT que não possuem uma instância existente de Atualização de Dispositivo para Hub IoT. Para tentar atualizações de software, conecte um IoT hub que não use Device Update for Hub IoT ao seu namespace.
• Os dispositivos usam um cliente diferente. Dispositivos que rodam o agente de Atualização de Dispositivos não conseguem receber atualizações a partir de atualizações de software. Para receber atualizações de software, um dispositivo utiliza o cliente de atualizações de software nos SDKs unificados IoT do Azure (prévia).

Como funcionam as atualizações de software

Você habilita atualizações de software em um namespace do Azure Device Registry, seja quando configurar o namespace ou depois. Para saber como, consulte Introdução ao Registro de Dispositivo do Azure (versão preliminar). O recurso introduz os seguintes componentes:

• Atualização de software: Uma atualização que você importa para um namespace. Uma atualização de software consiste em um ou mais arquivos de atualização e um manifesto de importação. Depois que você importa uma atualização de software, ela fica disponível para trabalhos de atualização de software e trabalhos de atualização de integração nesse namespace.
• Trabalho de atualização de software: Aplica uma atualização de software aos dispositivos compatíveis em um grupo-alvo.
• Tarefa de atualização de integração: aplica uma atualização de software a dispositivos compatíveis quando eles verificam se há atualizações durante a integração, antes de se registrarem e começarem a operar.
• Cliente de atualizações de software: A parte dos SDKs unificados IoT do Azure (prévia) que seu aplicativo de dispositivo usa para verificar, baixar e instalar atualizações de software, além de relatar os resultados.

Um fluxo típico de atualizações é o seguinte:

1. Você envia os arquivos de atualização e o manifesto de importação para um contêiner do Armazenamento do Azure.
2. Você importa a atualização de software para o seu namespace.
3. Você cria um job que mira um grupo ou, para integração inicial, o namespace.
4. Cada dispositivo verifica atualizações e reporta suas propriedades de compatibilidade. Se o dispositivo for compatível, ele recebe a atualização.
5. O dispositivo baixa e instala a atualização, e então informa o resultado. Você monitora o progresso e os resultados em nível de dispositivo na execução do trabalho.

Atualizações de software

Uma atualização de software consiste em dois componentes que você envia juntos:

• Arquivos de atualização: o payload que o dispositivo instala. A carga útil pode ser uma imagem de firmware, um pacote de software, um script ou múltiplos arquivos relacionados.
• Manifesto de importação: um arquivo JSON com a extensão .importmanifest.json que descreve a atualização. O manifesto de importação declara:
  • Identidade da atualização: O provedor, nome e versão que identificam de forma única a atualização. O provedor e o nome juntos identificam uma família de atualizações, como todas as versões do firmware para um modelo de dispositivo.
  • Propriedades de compatibilidade: As propriedades do dispositivo que determinam quais dispositivos podem instalar a atualização. Para mais informações, veja Compatibilidade de dispositivos.
  • Instruções de instalação: as etapas de instalação, sua ordem e o manipulador para cada etapa. O manipulador informa ao dispositivo como aplicar essa etapa, como instalar um pacote, executar um script ou gravar uma imagem.
  • Metadados do arquivo: O nome, tamanho e hash de cada arquivo de atualização. O serviço usa os hashes para verificar a integridade dos arquivos na importação, e o dispositivo pode usá-los para verificar cada arquivo antes da instalação.

Toda atualização de software requer um manifesto de importação. Se você tentar importar arquivos de atualização sem um manifesto de importação, a importação falha. Quando você importa, pode opcionalmente escanear os arquivos de atualização em busca de malware. A varredura de malware está disponível em regiões selecionadas. Para obter instruções passo a passo, consulte Importar uma atualização de software.

O exemplo a seguir mostra um manifesto de importação para uma atualização baseada em imagem:

{
  "updateId": {
    "provider": "Contoso",
    "name": "IrrigationControllerV2-Image",
    "version": "1.3.0"
  },
  "isDeployable": true,
  "compatibility": [
    {
      "manufacturer": "Contoso",
      "model": "IrrigationControllerV2"
    }
  ],
  "instructions": {
    "steps": [
      {
        "type": "inline",
        "description": "Update the device image to version 1.3.0",
        "handler": "microsoft/swupdate:1",
        "files": [
          "contoso-irrigation-controller-v2-1.3.0.swu"
        ],
        "handlerProperties": {
          "installedCriteria": "1.3.0"
        }
      }
    ]
  },
  "files": [
    {
      "filename": "contoso-irrigation-controller-v2-1.3.0.swu",
      "sizeInBytes": 112738816,
      "hashes": {
        "sha256": "wPdNKUSmWTZkR6Pum9oR/EIzdn5AvON4dsXME+/gHVw="
      }
    }
  ],
  "createdDateTime": "2026-10-01T06:56:51.2002204Z",
  "manifestVersion": "5.0"
}

As atualizações de software usam o mesmo formato de manifesto de importação do Device Update for Hub IoT. Para aprender como criar um manifesto de importação, veja:

• Esquema de manifesto de importação
• Execução ordenada em múltiplas etapas

Compatibilidade do dispositivo

As propriedades de compatibilidade em um manifesto de importação determinam quais dispositivos podem instalar uma atualização de software. Quando um dispositivo verifica atualizações, ele reporta suas próprias propriedades de compatibilidade. O Azure Device Registry compara essas propriedades com as propriedades de compatibilidade declaradas na atualização de software.

Você define propriedades de compatibilidade como pares nome-valor. Cada atualização de software deve declarar pelo menos uma propriedade de compatibilidade. manufacturer e model são escolhas comuns, mas não são obrigatórias. Use quaisquer propriedades que se adequem à sua frota, como region ou environment.

A seção compatibility do manifesto de importação é um array de conjuntos de propriedades. Por exemplo:

"compatibility": [
  {
    "manufacturer": "Contoso",
    "model": "IrrigationControllerV2"
  }
]

A correspondência funciona da seguinte forma:

• Um dispositivo deve corresponder a todas as propriedades de um conjunto. A atualização anterior se aplica apenas a dispositivos que informam tanto manufacturer como Contoso quanto model como IrrigationControllerV2. Isso não se aplica a um dispositivo Contoso SoilSensorV1 , nem a um IrrigationControllerV2 dispositivo que reporta um fabricante diferente.
• Um dispositivo precisa combinar apenas com um conjunto. Se você declarar mais de um conjunto de propriedades, uma única atualização de software pode se aplicar a vários tipos de dispositivos.
• Cada conjunto de propriedades pertence a uma família de atualizações. Você não pode usar exatamente o mesmo conjunto de propriedades de compatibilidade com mais de uma combinação de provedor e nome. Planeje suas famílias de atualização e propriedades de compatibilidade em conjunto. Para mais informações, veja Conceitos de importação.

Um grupo pode conter dispositivos com diferentes propriedades de compatibilidade. Um trabalho de atualização de software aplica a atualização apenas aos dispositivos compatíveis no grupo-alvo. Por exemplo, se um grupo contém 18 IrrigationControllerV2 dispositivos e seis SoilSensorV1 dispositivos, uma atualização para IrrigationControllerV2 dispositivos é aplicada aos 18 dispositivos compatíveis. Os seis SoilSensorV1 dispositivos não são afetados.

Jobs, grupos e comportamento de implantação

Você implanta uma atualização de software criando um job no namespace. Atualizações de software suportam dois tipos de tarefas:

Um trabalho de atualização de software não para depois que chega aos dispositivos compatíveis no momento em que ele é iniciado. Enquanto a execução do trabalho está ativa, ela continua aplicando a atualização a:

• Dispositivos que estavam offline quando a tarefa foi iniciada, após se reconectarem e verificarem se há atualizações.
• Dispositivos que ingressam no grupo de destino. A associação a grupos não é atualizada automaticamente: novos dispositivos entram no grupo na próxima vez que você atualizar a associação. Para obter mais informações, consulte Associação em cache e atualização.
• Dispositivos que se tornam elegíveis para a atualização, por exemplo, porque suas propriedades de compatibilidade reportadas mudam.

Um trabalho de atualização de onboarding permanece ativo até você encerrá-lo, então os dispositivos compatíveis continuam recebendo a atualização conforme são integrados.

Para estados de trabalho, agendamento e monitoramento, veja Conceitos de Jobs (prévia).

Considerações sobre o SDK do dispositivo

Os dispositivos recebem atualizações de software por meio do cliente de atualizações de software presente nos SDKs unificados do IoT do Azure (prévia). Tenha em mente as seguintes considerações ao planejar o software do seu dispositivo:

• Dispositivos suportados: Nesta prévia, o cliente de atualizações de software é destinado principalmente a dispositivos baseados em Linux com mais de 32 MB de memória disponível.
• Integração: O SDK é uma biblioteca, não um agente pronto para rodar. Você integra o cliente de atualizações de software ao aplicativo do seu dispositivo e fornece a lógica que baixa, instala e aplica atualizações no seu hardware. A Microsoft oferece exemplos para ajudar você a começar.
• Duas maneiras de verificar atualizações: Um dispositivo que está sendo integrado verifica se há atualizações de integração antes de se registrar. Um dispositivo registrado verifica se há atualizações de software a partir de uma tarefa de atualização de software. O aplicativo do seu dispositivo decide quando verificar se há atualizações.
• Conectividade: O dispositivo verifica atualizações e reporta resultados através de sua conexão com o Serviço de Provisionamento de Dispositivos. Não precisa de um endpoint ou credencial separado para receber atualizações.
• Segurança: Antes de baixar qualquer arquivo de atualização, o cliente de atualizações de software verifica a assinatura das informações de atualização que recebe do serviço. Os dispositivos baixam arquivos de atualização apenas via HTTPS, então o conteúdo da atualização está sempre criptografado durante o trânsito. Garanta que seus dispositivos possam fazer conexões HTTPS de saída para baixar arquivos de atualização.
• Relatórios de status: Após uma tentativa de instalação, o dispositivo informa o resultado, incluindo códigos de erro caso a instalação tenha falhado. O resultado aparece nos resultados em nível de dispositivo da execução do trabalho.
• Sua responsabilidade: Você é responsável por validar a integração no seu próprio ambiente, incluindo o comportamento de recuperação caso uma instalação falhe ou o dispositivo reinicie durante uma atualização.

Limitações de pré-visualização

A versão prévia atual tem as seguintes limitações:

• As atualizações de software são compatíveis com dispositivos conectados ao Hub IoT. Dispositivos e ativos do Operações do Azure IoT não são suportados nesta prévia.
• Você não pode usar atualizações de software com um IoT hub que já tenha uma instância de Atualização de Dispositivo para Hub IoT.
• Toda atualização de software requer um manifesto de importação. Você não pode criar um manifesto de importação no portal do Azure.
• O cliente de atualizações de software atualmente não oferece suporte a atualizações por proxy nem a atualizações que usam etapas de referência (atualizações pai e filho).

Para limites que se aplicam a atualizações importadas, como o tamanho máximo da atualização, veja Limites de Atualização de Dispositivo para Hub IoT. Para obter informações sobre os limites que se aplicam a grupos e tarefas, consulte Conceitos de grupos (versão preliminar) e Conceitos de tarefas (versão preliminar).

Conteúdo relacionado

• Importar uma atualização de software
• Implantar uma atualização de software em um grupo
• Implantar uma atualização de onboarding em um namespace
• Conceitos de grupos (prévia)
• Conceitos de tarefas (versão preliminar)
• SDKs unificados do IoT do Azure (versão prévia)