Importar atualizações para a Atualização de Dispositivos para Hub IoT

  • Artigo

Para implementar uma atualização em dispositivos a partir da Atualização de Dispositivos para Hub IoT, primeiro tem de importar essa atualização para o serviço Atualização de Dispositivos. A atualização importada será armazenada no serviço Atualização de Dispositivos e poderá ser implementada a partir daí para dispositivos. Este artigo fornece uma descrição geral de alguns conceitos importantes para compreender quando se trata de importar atualizações.

Importar manifesto

Um manifesto de importação é um ficheiro JSON que define informações importantes sobre a atualização que está a importar. Submete o manifesto de importação e os ficheiros ou ficheiros de atualização associados (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 utilizados para ingerir a atualização. Alguns dos metadados também são utilizados no momento da implementação , por exemplo, para validar se uma atualização foi instalada corretamente.

Por exemplo:

{
  "updateId": {
    "provider": "Contoso",
    "name": "Toaster",
    "version": "1.0"
  },
  "isDeployable": false,
  "compatibility": [
    {
      "manufacturer": "Contoso",
      "model": "Toaster"
    }
  ],
  "instructions": {
    "steps": [
      {
        "handler": "microsoft/swupdate:1",
        "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"
}

O manifesto de importação contém vários itens que representam uma Atualização de Dispositivos importante para conceitos de Hub IoT. Estes itens estão descritos nesta secção. Para obter informações sobre o esquema de importação completo, veja Importar o esquema JSON do manifesto.

Atualizar identidade

A identidade de atualização ou updateId é o identificador exclusivo de uma atualização na Atualização de Dispositivos para Hub IoT. É composto por três partes:

  • Fornecedor: entidade que está a criar ou diretamente responsável pela atualização. Muitas vezes, será um nome de empresa.
  • Nome: identificador para uma classe de atualizações. Muitas vezes, será uma classe de dispositivo ou um nome de modelo.
  • Versão: um número de versão que distingue esta atualização de outras pessoas que têm o mesmo fornecedor e nome.

Por exemplo:

{
  "updateId": {
    "provider": "Contoso",
    "name": "Toaster",
    "version": "1.0"
  }
}

Nota

O UpdateId é utilizado apenas pelo serviço Atualização de Dispositivos e pode ser diferente das identidades dos componentes de software reais no dispositivo.

Compatibilidade

A compatibilidade define os critérios de um dispositivo que pode instalar a atualização. Contém propriedades do dispositivo que são um conjunto de pares de valores de chave arbitrária que são comunicados a partir de um dispositivo. Apenas os dispositivos com propriedades correspondentes serão elegíveis para implementação. Uma atualização pode ser compatível com várias classes de dispositivos ao ter mais do que um conjunto de propriedades do dispositivo.

Eis um exemplo de uma atualização que só pode ser implementada num dispositivo que reporte a Contoso e a Toaster como fabricante e modelo do dispositivo.

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

Instruções

A parte Instruções contém as informações ou passos necessários para o agente do dispositivo instalar a atualização. A atualização mais simples contém um único passo inline. Este passo executa o ficheiro de payload incluído através de um processador registado com o agente do dispositivo:

{
  "instructions": {
    "steps": [
      {
        "handler": "microsoft/swupdate:1",
        "files": [
          "contoso.toaster.1.0.swu"
        ]
      }
    ]
  }
}

Dica

handler é equivalente a updateType na versão de manifesto de importação 3.0 ou mais antiga.

Uma atualização pode conter mais do que um passo:

{
  "instructions": {
    "steps": [
      {
        "description": "pre-install script",
        "handler": "microsoft/script:1",
        "handlerProperties": {
          "arguments": "--pre-install"
        },
        "files": [
          "configure.sh"
        ]
      },
      {
        "description": "firmware package",
        "handler": "microsoft/swupdate:1",
        "files": [
          "contoso.toaster.1.0.swu"
        ]
      }
    ]
  }
}

Uma atualização pode conter passos 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 principal e subordinada. Por exemplo, uma atualização para uma torradeira pode conter duas atualizações subordinadas:

{
  "instructions": {
    "steps": [
      {
        "type": "reference",
        "updateId": {
          "provider": "Contoso",
          "name": "Toaster.HeatingElement",
          "version": "1.0"
        }
      },
      {
        "type": "reference",
        "updateId": {
          "provider": "Contoso",
          "name": "Toaster.Sensors",
          "version": "1.0"
        }
      }
    ]
  }
}

Nota

Uma atualização pode conter qualquer combinação de passos inline e de referência.

Ficheiros

A parte Ficheiros contém os metadados dos ficheiros de payload de atualização, como os nomes, tamanhos e hash. A Atualização de Dispositivos para Hub IoT utiliza estes metadados para validação de integridade durante o processo de importação. Em seguida, as mesmas informações são reencaminhadas para o agente do dispositivo para repetir a validação de integridade antes da instalação.

Nota

Uma atualização que contenha apenas passos de referência não terá nenhum ficheiro de payload de atualização na atualização principal.

Criar um manifesto de importação

Embora seja possível criar manualmente um JSON de manifesto de importação com um editor de texto, a Interface de Linha de Comandos (CLI) do Azure simplifica bastante o processo. Quando estiver pronto para experimentar a criação de um manifesto de importação, pode utilizar o Guia de procedimentos.

Importante

Um nome de ficheiro JSON de manifesto de importação tem de terminar quando .importmanifest.json importado através de portal do Azure.

Dica

Utilize o Visual Studio Code para ativar a conclusão automática e a validação do esquema JSON ao criar um manifesto de importação.

Limites de importação de atualizações

São impostos determinados limites para cada Atualização de Dispositivo para Hub IoT instância. Se ainda não os reviu, veja Limites de Atualização de Dispositivos.

Passos seguintes