Usar o recurso de arquivos relacionados para fazer referência a vários arquivos de atualização

  • Artigo

Use a funcionalidade de arquivos relacionados quando precisar expressar relações entre arquivos de atualização diferentes em uma única atualização.

Ao importar uma atualização para a Atualização de Dispositivo para Hub IoT, é necessário um manifesto de importação que contém metadados sobre o conteúdo da atualização. Os metadados no nível do arquivo no manifesto de importação podem ser uma lista simples de arquivos de conteúdo de atualização no caso mais simples. No entanto, para cenários mais avançados, o recurso de arquivos relacionados fornece uma maneira de especificar relações entre vários arquivos de atualização.

Ao criar um manifesto de importação usando a funcionalidade de arquivos relacionados, você pode adicionar uma coleção de arquivos relacionados a um ou mais de seus arquivos de conteúdo primário. Um exemplo desse conceito é a funcionalidade de atualização delta da Atualização de Dispositivo, que usa arquivos relacionados para especificar uma atualização delta associada a um arquivo de imagem completo. No cenário delta, a funcionalidade de arquivos relacionados permite que a imagem completa e a atualização delta sejam importadas como uma única ação de atualização e, em seguida, qualquer uma delas pode ser implantada em um dispositivo. No entanto, a funcionalidade de arquivos relacionados não está limitada a atualizações delta, pois foi projetada para ser extensível por nossos clientes, dependendo de seus próprios cenários exclusivos.

O recurso de arquivos relacionados está disponível para manifestos de importação da versão 5 ou posterior.

Ao adicionar arquivos relacionados a um manifesto de importação, inclua as seguintes informações:

  • Detalhes do arquivo

    Defina os arquivos relacionados fornecendo o nome do arquivo, o tamanho e o hash.

  • Um manipulador de download

    Especifique como processar os arquivos relacionados para produzir o arquivo de destino. Especifique a abordagem de processamento incluindo uma propriedade downloadHandler no manifesto de importação. A inclusão de downloadHandler será necessária se você especificar uma coleção não vazia de relatedFiles em um elemento file. Você pode especificar um downloadHandler usando uma propriedade id simples. O manipulador de downloads id tem um limite de 64 caracteres ASCII.

  • Propriedades de arquivos relacionados

    Você pode fornecer metadados extras para o manipulador de atualização no dispositivo a fim de saber como interpretar e usar corretamente os arquivos especificados como arquivos relacionados. Esses metadados são adicionados como parte de um recipiente de propriedades properties para os objetos file e relatedFile.

Para obter mais informações sobre o esquema de importação para arquivos relacionados, consulte objeto relatedFiles.

O manifesto de importação de exemplo a seguir demonstra como o recurso de arquivos relacionados é usado para importar uma atualização delta. Neste exemplo, você pode ver que, na seção files, há uma imagem completa especificada (full-image-file-name) com um item properties. O item properties, por sua vez, tem um item relatedFiles associado abaixo dele. Na seção relatedFiles, você pode ver outra seção properties para o arquivo de atualização delta (delta-from-v1-file-name) e também um item downloadHandler com a lista apropriada id (microsoft/delta:1).

Observação

Este exemplo usa atualizações delta para demonstrar como fazer referência a arquivos relacionados. Se você quiser usar atualizações delta como um recurso, saiba mais na documentação da atualização delta.

    {
      "updateId": {
        // provider, name, version
      },
      "compatibility": [
        {
          // manufacturer, model, etc.
        }
      ],
      "instructions": {
        "steps": [
          // Inline steps...
        ]
      },
      "files": [
        {  
          // standard file properties
          "fileName": "full-image-file-name",
          "sizeInBytes": 12345,
          "hashes": {
            "SHA256": "full-image-file-hash"
          },
          "mimeType": "application/octet-stream",
          // new properties
          "properties  ": {},
          "relatedFiles": [
            {
              // delta from version 1.0.0.0
              // standard file properties
              "fileName": "delta-from-v1-file-name",
              "sizeInBytes": 1234,
              "hashes": {
                "SHA256": "delta-from-v1-file-hash"
              },
              "mimeType": "application/octet-stream",
              // new properties
              "properties": {
                "microsoft.sourceFileHash": "delta-source-file-hash",
                "microsoft.sourceFileHashAlgorithm": "sha256"
              }
            }  
          ],
          // handler to download/process our related files
      "downloadHandler": {
        "id": "microsoft/delta:1"
      }
    }
  ],
  "createdDateTime": "2021-12-01T01:12:21Z",
  "manifestVersion": "5.0"
    }

O comando az iot du init v5 para criar um manifesto de importação dá suporte a um parâmetro --related-file opcional.

O parâmetro --related-file usa uma chave path e properties:

--related-file path=<replace with path(s) to your delta file(s), including the full file name> properties='{"microsoft.sourceFileHashAlgorithm": "sha256", "microsoft.sourceFileHash": "<replace with the source SWU image file hash>"}'

Por exemplo:

az iot du update init v5 \
--update-provider Microsoft --update-name myBundled --update-version 2.0 \
--compat manufacturer=Contoso model=SpaceStation \
--step handler=microsoft/script:1 properties='{"arguments": "--pre"}' description="Pre-install script" \
--file path=/my/update/scripts/preinstall.sh downloadHandler=microsoft/delta:1 \
--related-file path=/my/update/scripts/related_preinstall.json properties='{"microsoft.sourceFileHashAlgorithm": "sha256"}' \
--step updateId.provider=Microsoft updateId.name=SwUpdate updateId.version=1.1 \
--step handler=microsoft/script:1 properties='{"arguments": "--post"}' description="Post-install script" \
--file path=/my/update/scripts/postinstall.sh

Próximas etapas