Conceitos de importação da Atualização de Dispositivo do Azure para Hub IoT
Para implantar uma atualização em dispositivos usando a Atualização de Dispositivo do Azure para Hub IoT, primeiro importe a atualização para o serviço de Atualização de Dispositivo, que armazena a atualização importada e a implanta em dispositivos. Este artigo fornece uma visão geral de alguns conceitos importantes a serem entendidos quando se trata da importação de atualizações.
Importar manifesto
Um manifesto de importação é um arquivo JSON que define informações importantes sobre a atualização que você está importando. Você envia o seu manifesto de importação e arquivos de atualização associados, como pacotes de atualização de firmware, como parte do processo de importação. Os metadados definidos no manifesto de importação são usados para ingerir a atualização. Alguns dos metadados também são usados no momento da implantação, por exemplo, para validar se uma atualização foi instalada corretamente.
O código JSON a seguir mostra um exemplo de arquivo de manifesto de importação:
{
"updateId": {
"provider": "Contoso",
"name": "Toaster",
"version": "1.0"
},
"isDeployable": false,
"compatibility": [
{
"manufacturer": "Contoso",
"model": "Toaster"
}
],
"instructions": {
"steps": [
{
"handler": "microsoft/swupdate:2",
"files": [
"firmware.swu"
],
"handlerProperties": {
"installedCriteria": "1.0"
}
}
]
},
"files": [
{
"filename": "firmware.swu",
"sizeInBytes": 7558,
"hashes": {
"sha256": "/CD7Sn6fiknWa3NgcFjGlJ+ccA81s1QAXX4oo5GHiFA="
}
}
],
"createdDateTime": "2022-01-19T06:23:52.6996916Z",
"manifestVersion": "5.0"
}
As seções do arquivo de manifesto de importação representam conceitos importantes de Atualização de Dispositivo, conforme descrito nas seções a seguir. Para obter informações sobre o esquema de manifesto de importação completo, confira Importar esquema JSON do manifesto.
Atualizar a identidade
A identidade de atualização ou updateId é o identificador exclusivo de uma atualização na Atualização do Dispositivo e contém as seguintes propriedades:
- O Provedor é a entidade que cria ou é responsável pela atualização. O Provedor geralmente é um nome da empresa.
- O Nome é o identificador de uma classe de atualização. O Nome geralmente é um nome de modelo ou classe de dispositivo.
- A Versão é um número que distingue esta atualização de outras pessoas com o mesmo provedor e nome.
Por exemplo:
{
"updateId": {
"provider": "Contoso",
"name": "Toaster",
"version": "1.0"
}
}
Observação
O updateId é usado apenas pelo serviço de Atualização de Dispositivo e é diferente das identidades de componente de software nos dispositivos.
Compatibilidade
A seção Compatibilidade usa um ou mais pares chave-valor arbitrários para definir os dispositivos que podem instalar uma atualização. Somente os dispositivos que relatam propriedades que correspondem aos valores de compatibilidade são qualificados para implantar a atualização. Você pode tornar uma atualização compatível com várias classes de dispositivo, incluindo mais de um conjunto de propriedades de compatibilidade de dispositivos.
O exemplo a seguir mostra uma atualização que só pode ser implantada em dispositivos que relatam Contoso e Toaster como o fabricante e modelo de dispositivo.
{
"compatibility": [
{
"manufacturer": "Contoso",
"model": "Toaster"
}
]
}
Instruções
A seção Instruções contém as informações ou etapas necessárias para o agente do dispositivo instalar a atualização. A atualização mais simples contém uma única etapa embutida que executa o arquivo de conteúdo de atualização usando um manipulador registrado com o agente do dispositivo. O exemplo a seguir mostra uma seção de instruções de etapa única.
{
"instructions": {
"steps": [
{
"handler": "microsoft/swupdate:2",
"files": [
"contoso.toaster.1.0.swu"
]
}
]
}
}
Observação
A propriedade handler é equivalente à propriedade updateType na versão 3.0 ou anterior do manifesto de importação.
Uma atualização pode conter mais de uma etapa, como no exemplo a seguir:
{
"instructions": {
"steps": [
{
"description": "pre-install script",
"handler": "microsoft/script:1",
"handlerProperties": {
"arguments": "--pre-install"
},
"files": [
"configure.sh"
]
},
{
"description": "firmware package",
"handler": "microsoft/swupdate:2",
"files": [
"contoso.toaster.1.0.swu"
]
}
]
}
}
Uma atualização pode conter etapas de referência que instruem o agente do dispositivo a instalar outra atualização com o seu próprio manifesto de importação, estabelecendo uma relação de atualização pai e filho. Uma atualização pode conter qualquer combinação de etapas embutidas e de referência.
Por exemplo, uma atualização para uma torradeira pode conter duas atualizações filho:
{
"instructions": {
"steps": [
{
"type": "reference",
"updateId": {
"provider": "Contoso",
"name": "Toaster.HeatingElement",
"version": "1.0"
}
},
{
"type": "reference",
"updateId": {
"provider": "Contoso",
"name": "Toaster.Sensors",
"version": "1.0"
}
}
]
}
}
Arquivos
A seção Arquivos do manifesto de importação contém metadados de arquivo de conteúdo de atualização, como name, size e hash. A Atualização de Dispositivo usa esses metadados para validação de integridade durante o processo de importação e encaminha as mesmas informações para o agente do dispositivo para validação de integridade antes da instalação.
Observação
Uma atualização pai que contém apenas as etapas de referência não define nenhum arquivo de conteúdo de atualização.
Criar um manifesto de importação
Embora seja possível criar um manifesto de importação JSON manualmente usando um editor de texto, a CLI do Azure simplifica muito o processo. Quando estiver pronto para experimentar a criação de um manifesto de importação, você poderá usar o Guia de instruções.
Importante
Para importar para o serviço de Atualização de Dispositivo por meio do portal do Azure, um nome de arquivo JSON do manifesto de importação deve terminar com .importmanifest.json.
Dica
Você pode usar o Visual Studio Code para habilitar o preenchimento automático e a validação de esquema JSON ao criar um manifesto de importação.
Atualizar limites de importação
Certos limites são impostos para cada instância de Atualização de Dispositivo para Hub IoT. Se você ainda não os revisou, confira Limites da Atualização de Dispositivo.