Compartilhar via

Importando atualizações na Atualização de Dispositivo para Hub IoT

  • Artigo

Para implantar uma atualização em dispositivos da Atualização de Dispositivo para Hub IoT, primeiro você precisará importar essa atualização para o serviço de Atualização de Dispositivo. A atualização importada será armazenada no serviço de Atualização de Dispositivo e, de lá, poderá ser implantada nos 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 manifesto de importação e o arquivo ou os arquivos 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 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.

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 conceitos importantes da Atualização de Dispositivo para Hub IoT. Esses itens são descritos nesta seção. Para obter informações sobre o esquema de importação completo, consulte Importar esquema JSON de manifesto.

Atualizar a identidade

A identidade da atualização ou updateId é o identificador exclusivo de uma atualização na Atualização de Dispositivo para Hub IoT. Ela é composta por três partes:

  • Provedor: entidade que está criando ou é diretamente responsável pela atualização. Em geral, ela será um nome de empresa.
  • Nome: identificador de uma classe de atualizações. Normalmente, será uma classe de dispositivo ou nome de modelo.
  • Versão: um número de versão que distingue essa atualização de outras que têm o mesmo nome e provedor.

Por exemplo:

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

Observação

A UpdateId é usada pelo serviço de Atualização de Dispositivo e pode ser diferente das identidades dos componentes de software de fato no dispositivo.

Compatibilidade

A Compatibilidade define os critérios de um dispositivo que pode instalar a atualização. Ela contém as propriedades do dispositivo, que são um conjunto de pares de chaves e valor arbitrários que são relatados de um dispositivo. Somente dispositivos com propriedades correspondentes serão aptos para implantação. Uma atualização pode ser compatível com várias classes de dispositivo, ao ter mais de um conjunto de propriedades de dispositivo.

Aqui está um exemplo de uma atualização que só pode ser implantada em um dispositivo que relatar a Contoso e a Torradeira como fabricante e modelo de dispositivo.

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

Instruções

A bloco de instruções contém as informações necessárias ou etapas para que o agente de dispositivo instale a atualização. A atualização mais simples contém uma única etapa embutida. Essa etapa executa o arquivo de conteúdo incluído usando um manipulador registrado 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 anterior.

Uma atualização pode conter mais de uma etapa:

{
  "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 etapas de referência que instruem o agente do dispositivo a instalar outra atualização com o próprio manifesto de importação, estabelecendo uma relação de atualização pai e filho. 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"
        }
      }
    ]
  }
}

Observação

Uma atualização pode conter qualquer combinação das etapas embutidas e de referência.

Arquivos

O bloco arquivos contém os metadados dos arquivos de conteúdo de atualização como seus nomes, tamanhos e hash. A Atualização de Dispositivo para Hub IoT usa esses metadados para validação de integridade durante o processo de importação. As mesmas informações são encaminhadas para o agente de dispositivo para repetir a validação de integridade antes da instalação.

Observação

Uma atualização contendo somente etapas de referência não terá um arquivo de conteúdo de atualização na atualização pai.

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 (Interface de Linha de Comando) 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

O nome de arquivo JSON de um manifesto de importação deve terminar com .importmanifest.json quando importado por meio do portal do Azure.

Dica

Usar o Visual Studio Code para habilitar a validação de esquema de JSON e preenchimento automático ao criar um manifesto de importação.

Limites na importação de atualizações

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.

Próximas etapas