Importando atualizações para atualização de dispositivos do Hub IoT

Para implantar uma atualização em dispositivos a partir da Atualização de Dispositivo para Hub IoT, primeiro você precisa importar essa atualização para o serviço de Atualização de Dispositivo. Este artigo fornece uma visão geral de alguns conceitos importantes para entender quando se trata de importar atualizações.

Manifesto de importação

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 (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": [
    {
      "deviceManufacturer": "Contoso",
      "deviceModel": "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": "4.0"
}

O manifesto de importação contém vários itens que representam conceitos importantes de Atualização de Dispositivo para o Hub IoT. Esses itens são descritos nesta seção. Para obter informações sobre o esquema completo de importação, consulte Esquema JSON de manifesto de importação.

Atualizar identidade

A identidade de atualização ou updateId é o identificador exclusivo de uma atualização no Device Update for IoT Hub. É composto por três partes:

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

Por exemplo:

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

Compatibilidade

A compatibilidade define os critérios de um dispositivo que pode instalar a atualização. Ele contém propriedades de dispositivo que são um conjunto de pares de valores de chave arbitrários que são relatados a partir de um dispositivo. Apenas dispositivos com propriedades correspondentes serão elegíveis para implantação. Uma atualização pode ser compatível com várias classes de dispositivo por 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 relata Contoso e Toaster como seu fabricante e modelo de dispositivo.

{
  "compatibility": [
    {
      "deviceManufacturer": "Contoso",
      "deviceModel": "Toaster"
    }
  ]
}

Instruções

A parte 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. Essa etapa executa o arquivo de carga incluído usando um manipulador registrado com o agente de dispositivo:

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

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 seu próprio manifesto de importação, estabelecendo uma relação hierárquica de atualização entre pai e filho. Por exemplo, uma atualização para uma torradeira pode conter duas subatualizações:

{
  "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 parte Arquivos contém os metadados dos arquivos de carga útil de atualização, como seus nomes, tamanhos e hash. A Atualização de Dispositivo para o Hub IoT usa esses metadados para validação de integridade durante o processo de importação. As mesmas informações são então encaminhadas para o agente do dispositivo para repetir a validação de integridade antes da instalação.

Criar um manifesto de importação

Você pode usar qualquer editor de texto para criar um arquivo JSON de manifesto de importação. Há também scripts de exemplo para criar manifesto de importação programaticamente no Azure/iot-hub-device-update no GitHub.

Limites na importação de atualizações

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.

Próximos passos

• Para saber mais sobre o processo de importação, consulte Preparar uma atualização para importar.
• Analise o esquema de manifesto de importações.