Conceitos de importação do Azure Device Update for IoT Hub
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 para entender quando se trata de importar 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 manifesto de importação e o(s) arquivo(s) de atualização associado(s), como um pacote 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, consulte Esquema JSON de manifesto de importação.
Atualizar identidade
A identidade da atualização ou updateId é o identificador exclusivo de uma atualização na Atualização de Dispositivo e contém as seguintes propriedades:
- Provedor é a entidade que cria ou é responsável pela atualização. Provedor é muitas vezes um nome de empresa.
- Name é o identificador de uma classe de atualização. Nome geralmente é uma classe de dispositivo ou nome de modelo.
- Versão é um número que distingue esta atualização de outras com o mesmo provedor e nome.
Por exemplo:
{
"updateId": {
"provider": "Contoso",
"name": "Toaster",
"version": "1.0"
}
}
Nota
O updateId é usado apenas pelo serviço de Atualização de Dispositivo e é diferente das identidades de componentes de software nos dispositivos.
Compatibilidade
A seção Compatibilidade usa um ou mais pares arbitrários chave-valor para definir os dispositivos que podem instalar uma atualização. Apenas os dispositivos que relatam propriedades correspondentes aos valores de compatibilidade são elegíveis 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 dispositivo.
O exemplo a seguir mostra uma atualização que só pode ser implantada em dispositivos que relatam Contoso e Toaster como seu 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 que o agente do dispositivo instale a atualização. A atualização mais simples contém uma única etapa embutida que executa o arquivo de carga útil de atualização usando um manipulador registrado com o agente de 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"
]
}
]
}
}
Nota
A handler propriedade é equivalente à propriedade no manifesto updateType de importação versão 3.0 ou anterior.
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 de dispositivo a instalar outra atualização com 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 filhas:
{
"instructions": {
"steps": [
{
"type": "reference",
"updateId": {
"provider": "Contoso",
"name": "Toaster.HeatingElement",
"version": "1.0"
}
},
{
"type": "reference",
"updateId": {
"provider": "Contoso",
"name": "Toaster.Sensors",
"version": "1.0"
}
}
]
}
}
Ficheiros
A seção Arquivos do manifesto de importação contém metadados do arquivo de carga útil de atualização, como name, sizee 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 de dispositivo para validação de integridade antes da instalação.
Nota
Uma atualização pai que contém apenas etapas de referência não define nenhum arquivo de carga útil de atualização.
Criar um manifesto de importação
Embora seja possível criar um JSON de manifesto de importação 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 de manifesto de importação deve terminar com .importmanifest.json.
Gorjeta
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 da Atualização de Dispositivo para o Hub IoT. Se ainda não os tiver revisto, consulte Limites da Atualização de Dispositivos.