Manifesto de APT de Atualização de Dispositivo

  • Artigo

O manifesto de APT é um arquivo JSON que descreve os detalhes de atualização exigidos pelo manipulador de atualização apt. Esse arquivo pode ser importado para a Atualização de Dispositivo para Hub IoT, assim como qualquer outra atualização.

Para obter mais informações, confira Importar uma atualização para a Atualização de Dispositivo para Hub IoT.

Visão geral

Quando um manifesto de 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 manipulador de atualização do APT e ao Gerenciador de atualizações da apt. Esse suporte permite que o agente de Atualização de Dispositivo avalie os pacotes Debian instalados e atualize os pacotes necessários.

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: o nome deste manifesto de APT. Pode ser qualquer nome ou ID significativo para seus cenários. Por exemplo, contoso-iot-edge.
  • Versão: um número de versão para este manifesto de 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 desejados para o pacote. Por exemplo, 1.0.8-2. O valor da versão não deve conter um sinal igual. Se a versão for omitida, a versão mais recente disponível do pacote especificado será instalada.

Atualmente, apenas o número de versão exato é suportado. O número da versão é a versão desejada do pacote Debian no formato [época:]upstream_version[-debian_revision], onde a época é um int sem sinal e upstream_version pode incluir alfanuméricos e caracteres como ".","+","-" e "~". Ele deve começar com um dígito.

Observação

'1.0.8' é igual a '1.0.8-0'

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

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, elas usarão a versão mais recente, 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. Saiba mais

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

Um manifesto APT pode ser usado para atualizar o 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. Esse manifesto APT pode ser importado e implantado por meio do pipeline de Atualização de Dispositivo para Hub IoT.

Removendo pacotes

Você também pode usar um manifesto APT para remover pacotes instalados do dispositivo. Um único manifesto de 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. Você não deve incluir 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:

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

Esse manifesto de APT removerá o pacote "foo" dos dispositivos em que ele está implantado.

Os critérios instalados para um manifesto de APT são <name>-<version> onde <name> é o nome do manifesto de APT e <version> é a versão do manifesto apt. Por exemplo, contoso-iot-edge-1.0.0.0.

Diretrizes sobre como criar um manifesto de APT

Ao criar o manifesto de APT, há algumas diretrizes para ter em mente:

  • Sempre verifique se o manifesto de APT é um arquivo JSON bem formado.
  • Cada manifesto de APT deve ter uma versão exclusiva. Tente criar uma metodologia padronizada para incrementar a versão do manifesto de APT, de modo que faça sentido para seus cenários e possa ser facilmente seguido.
  • Quando se trata do 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 repositório de pacotes que você pretende usar como a origem do pacote.
  • Verifique se os pacotes no manifesto de APT estão listados na ordem em que eles devem ser instalados/removidos.
  • Sempre valide a instalação de pacotes em um dispositivo de teste para garantir que o resultado seja desejado.
  • Ao instalar uma versão específica de um pacote (por exemplo, iotedge 1.0.9-1), é recomendável também ter no manifesto de APT as versões explícitas dos pacotes dependentes a serem instalados (por exemplo, libiothsm 1.0.9-1)
  • Embora não seja obrigatório, sempre garanta que seu manifesto de APT seja cumulativo para evitar que seu dispositivo fique em um estado desconhecido. Uma atualização cumulativa garantirá que seus dispositivos tenham a versão desejada de cada pacote que você se importa mesmo se o dispositivo tiver ignorado uma implantação de atualização de APT devido a uma falha na instalação ou ficar offline

Por exemplo:

Manifesto base de APT 

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

Atualização inadequada

Essa atualização inclui o pacote de barras, mas não o pacote foo.

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

Atualização adequada

Essa atualização inclui o pacote foo e também inclui o pacote de barras.

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

Próximas etapas

Importar uma atualização para Atualização de Dispositivo