Compartilhar via

Manifesto APT da Atualização de Dispositivo do Azure para Hub IoT

  • Artigo

Este artigo descreve o manifesto APT, um arquivo JSON que descreve os detalhes da atualização exigidos pelo manipulador de atualizações APT. Você pode importar esse arquivo para a Atualização do Dispositivo da mesma forma que qualquer outra atualização. Para obter mais informações, confira Importar uma atualização para a Atualização de Dispositivo.

Quando um manifesto APT é entregue a um agente de Atualização de Dispositivo como uma atualização, o agente processa o manifesto e realiza as operações necessárias. Essas operações incluem baixar e instalar os pacotes especificados no arquivo de manifesto de APT e suas dependências a partir de um repositório designado.

A Atualização de Dispositivo dá suporte ao tipo de atualização APT e ao manipuladorde atualização. Esse suporte permite que o agente de Atualização de Dispositivo avalie os pacotes Debian instalados e atualize os pacotes necessários.

Você pode usar um manifesto APT para atualizar o próprio agente de Atualização de Dispositivo e suas dependências. Liste o nome do agente de atualização do dispositivo e a versão desejada no manifesto APT como faria com qualquer outro pacote. Em seguida, você pode importar esse manifesto APT e implantá-lo por meio do pipeline de Atualização de Dispositivo.

Esquema

Um arquivo de manifesto de APT é um arquivo JSON com um esquema com versão.

{
    "name": "<name>",
    "version": "<version>",
    "packages": [
        {
            "name": "<package name>",
            "version": "<version specifier>"
        }
    ]
}

Por exemplo:

{
    "name": "contoso-iot-edge",
    "version": "1.0.0.0",
    "packages": [
        {
            "name" : "thermocontrol",
            "version" : "1.0.1"
        },
        {
            "name" : "tempreport",
            "version" : "2.0.0"
        }
    ]
}

Cada manifesto de APT inclui as seguintes propriedades:

  • Nome: um nome para este manifesto APT, que pode ser qualquer nome ou ID significativo que se ajuste ao seu cenário. Por exemplo, contoso-iot-edge.
  • Versão: um número de versão para este manifesto APT, por exemplo, 1.0.0.0.
  • Pacotes: uma lista de objetos que contêm propriedades específicas do pacote.
    • Nome: o nome ou a ID do pacote, por exemplo iotedge.
    • Versão: os critérios de versão do pacote desejado, por exemplo, 1.0.8-2.

Controle de versão

O manifesto APT dá suporte apenas a números de versão exatos. O número de versão é a versão desejada do pacote Debian no formato <epoch>:<upstream_version>-<debian_revision>, onde epoch é um int sem sinal e upstream_version começa com um dígito e pode incluir alfanuméricos e caracteres como ., ,, +, - e ~. O valor da versão não deve conter um sinal igual.

Por exemplo, "name":"iotedge" e "version":"1.0.8-2" é equivalente a instalar um pacote usando o comando apt-get install iotedge=1.0.8-2. A versão 1.0.8 é igual a 1.0.8-0.

Se a versão for omitida, a Atualização de Dispositivo instalará a versão mais recente disponível do pacote especificado. Para obter mais informações sobre como os pacotes Debian são versionados, consulte o manual de política de Debian.

Observação

O gerenciador de pacotes de APT ignora os requisitos de versão determinados por um pacote quando os pacotes dependentes a serem instalados estão sendo resolvidos automaticamente. A menos que versões explícitas de pacotes dependentes sejam fornecidas, a versão mais recente é usada, mesmo que o próprio pacote possa especificar um requisito estrito (=) em uma determinada versão. Essa resolução automática pode levar a erros relacionados a uma dependência não atendida.

Portanto, quando você instala uma versão específica de um pacote, é melhor incluir também as versões explícitas dos pacotes dependentes a serem instalados. Para obter mais informações, consulte apt-get não resolvendo corretamente uma dependência em uma versão fixa em um pacote Debian/Ubuntu.

Se você atualizar uma versão específica do daemon de segurança Azure IoT Edge, inclua a versão desejada do pacote aziot-edge e seu pacote aziot-identity-service dependente no manifesto APT. Para obter mais informações, consulte Como atualizar o IoT Edge.

Critérios instalados

O valor de critérios instalados recomendado para um manifesto APT é <name>-<version>, onde <name> é o nome do manifesto APT e <version> é sua versão. Por exemplo, contoso-iot-edge-1.0.0.0.

Remoção de pacote

Você também pode usar um manifesto APT para remover pacotes instalados dos dispositivos. Você pode usar único manifesto APT pode ser usado para remover, adicionar e atualizar vários pacotes.

Para remover um pacote, adicione um sinal de subtração - após o nome do pacote. Não inclua um número de versão para os pacotes que está removendo. Remover um pacotes por meio de um manifesto de APT não remove suas dependências e configurações.

Por exemplo, o manifesto APT a seguir remove o pacote contoso1 de todos os dispositivos para os quais ele foi implantado.

{
    "name": "contoso-video",
    "version": "2.0.0.1",
    "packages": [
        {
            "name" : "contoso1-"
        }
    ]
}

Diretrizes de criação de manifesto APT

Tenha em mente as seguintes diretrizes ao criar um manifesto APT:

  • Verifique se o manifesto APT é um arquivo JSON bem formado.

  • Dê a cada manifesto APT uma versão exclusiva. Tente criar uma metodologia padronizada para incrementar a versão do manifesto APT, de modo que faça sentido para seus cenários e possa ser seguido facilmente.

  • Para o estado desejado de cada pacote individual, especifique o nome exato e a versão do pacote que você deseja instalar em seu dispositivo. Sempre valide os valores em relação ao conteúdo do repositório do pacote de origem.

  • Liste os pacotes no manifesto APT na ordem em que eles devem ser instalados ou removidos.

  • Sempre valide a instalação de pacotes em um dispositivo de teste para garantir o resultado desejado.

  • Quando você instala uma versão específica de um pacote, por exemplo iotedge 1.0.9-1, também inclui as versões explícitas dos pacotes dependentes a serem instalados, por exemplo libiothsm 1.0.9-1.

  • Embora não seja necessário, sempre tornar seu manifesto APT cumulativo evita colocar dispositivos em um estado desconhecido. Uma atualização cumulativa garante que seus dispositivos tenham a versão desejada de cada pacote relevante, mesmo que o dispositivo tenha ignorado uma atualização devido a uma falha de instalação ou estar offline.

    Por exemplo, considere o seguinte manifesto APT de base:

    {
    "name": "contoso-iot-edge",
    "version": "1.0",
    "packages": [
        {
            "name": "contoso1",
            "version": "1.0.1"
        }
    ]
}

    A atualização da versão 2.0 a seguir inclui o pacote contoso2, mas não o pacote contoso1. Todos os dispositivos que recebem a atualização 2.0 podem não ter o pacote contoso1.

    {
    "name": "contoso-iot-edge",
    "version": "2.0",
    "packages": [
       {
            "name": "contoso2",
            "version": "3.0.2"
        }
    ]
}

    A seguinte atualização cumulativa da versão 2.0 inclui os pacotes contoso1 e contoso2:

    {
    "name": "contoso-iot-edge",
    "version": "2.0",
    "packages": [
        {
            "name": "contoso1",
            "version": "1.0.1"
        },
        {
            "name": "contoso2",
            "version": "3.0.2"
        }
    ]
}

Conteúdo relacionado