Partilhar via

Utilizar a funcionalidade de ficheiros relacionados para referenciar vários ficheiros de atualização

  • Artigo

Utilize a funcionalidade de ficheiros relacionados quando precisar de expressar relações entre ficheiros de atualização diferentes numa única atualização.

Ao importar uma atualização para a Atualização de Dispositivos para Hub IoT, é necessário um manifesto de importação que contenha metadados sobre o payload de atualização. Os metadados ao nível do ficheiro no manifesto de importação podem ser uma lista simples de ficheiros de payload de atualização no caso mais simples. No entanto, para cenários mais avançados, a funcionalidade de ficheiros relacionados fornece uma forma de especificar relações entre vários ficheiros de atualização.

Ao criar um manifesto de importação com a funcionalidade de ficheiros relacionados, pode adicionar uma coleção de ficheiros relacionados a um ou mais dos seus ficheiros de payload principais . Um exemplo deste conceito é a funcionalidade atualização delta da Atualização de Dispositivos, que utiliza ficheiros relacionados para especificar uma atualização delta associada a um ficheiro de imagem completo. No cenário delta, a funcionalidade de ficheiros relacionados permite que a imagem completa e a atualização delta sejam importadas como uma única ação de atualização e, em seguida, podem ser implementados num dispositivo. No entanto, a funcionalidade de ficheiros relacionados não está limitada a atualizações delta, uma vez que foi concebida para ser extensível pelos nossos clientes consoante os seus próprios cenários exclusivos.

A funcionalidade de ficheiros relacionados está disponível para manifestos de importação da versão 5 ou posterior.

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

  • Detalhes do ficheiro

    Defina os ficheiros relacionados ao fornecer o nome de ficheiro, o tamanho e o hash.

  • Um processador de transferências

    Especifique como processar estes ficheiros relacionados para produzir o ficheiro de destino. Especifique a abordagem de processamento ao incluir uma downloadHandler propriedade no manifesto de importação. A inclusão downloadHandler é necessária se especificar uma coleção não vazia de relatedFiles num file elemento. Pode especificar uma downloadHandler com uma propriedade simples id . O Processador id de transferências tem um limite de 64 carateres ASCII.

  • Propriedades de ficheiros relacionados

    Pode fornecer metadados adicionais para o processador de atualizações no seu dispositivo para saber como interpretar e utilizar corretamente os ficheiros que especificou como ficheiros relacionados. Estes metadados são adicionados como parte de um properties conjunto de propriedades aos file objetos e relatedFile .

Para obter mais informações sobre o esquema de importação para ficheiros relacionados, veja relatedFiles object (Objeto relatedFiles).

O seguinte manifesto de importação de exemplo demonstra como a funcionalidade de ficheiros relacionados é utilizada para importar uma atualização delta. Neste exemplo, pode ver que, na files secção, existe uma imagem completa especificada (full-image-file-name) com um properties item. Por properties sua vez, o item tem um item associado relatedFiles abaixo do mesmo. relatedFiles Na secção, pode ver outra properties secção para o ficheiro de atualização delta (delta-from-v1-file-name) e também um downloadHandler item com a lista adequada id (microsoft/delta:1).

Nota

Este exemplo utiliza atualizações delta para demonstrar como referenciar ficheiros relacionados. Se quiser utilizar as atualizações delta como uma funcionalidade, 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 suporta um parâmetro opcional --related-file .

O --related-file parâmetro utiliza uma path chave 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

Passos seguintes