Usare la funzionalità file correlati per fare riferimento a più file di aggiornamento

  • Articolo

Usare la funzionalità dei file correlati quando è necessario esprimere relazioni tra file di aggiornamento diversi in un singolo aggiornamento.

Quando si importa un aggiornamento in Aggiornamento dispositivo per hub IoT, è necessario un manifesto di importazione contenente metadati sul payload dell'aggiornamento. I metadati a livello di file nel manifesto di importazione possono essere un elenco flat di file payload di aggiornamento nel caso più semplice. Tuttavia, per scenari più avanzati, la funzionalità file correlati offre un modo per specificare le relazioni tra più file di aggiornamento.

Quando si crea un manifesto di importazione usando la funzionalità file correlati, è possibile aggiungere una raccolta di file correlati a uno o più file del payload primario . Un esempio di questo concetto è la funzionalità di aggiornamento differenziale dell'aggiornamento del dispositivo, che usa i file correlati per specificare un aggiornamento differenziale associato a un file di immagine completo. Nello scenario delta, la funzionalità file correlati consente l'importazione dell'immagine completa e dell'aggiornamento differenziale come singola azione di aggiornamento e quindi una può essere distribuita in un dispositivo. Tuttavia, la funzionalità dei file correlati non è limitata agli aggiornamenti differenziali, poiché è progettata per essere estendibile dai clienti a seconda dei propri scenari univoci.

La funzionalità dei file correlati è disponibile per i manifesti di importazione che sono la versione 5 o successiva.

Quando si aggiungono file correlati a un manifesto di importazione, includere le informazioni seguenti:

  • File details

    Definire i file correlati specificando il nome file, le dimensioni e l'hash.

  • Gestore di download

    Specificare come elaborare questi file correlati per produrre il file di destinazione. Specificare l'approccio di elaborazione includendo una downloadHandler proprietà nel manifesto di importazione. L'inclusione downloadHandler è necessaria se si specifica una raccolta non vuota di relatedFiles in un file elemento. È possibile specificare un downloadHandler oggetto usando una proprietà semplice id . Il gestore id Download ha un limite di 64 caratteri ASCII.

  • Proprietà dei file correlati

    È possibile fornire metadati aggiuntivi per il gestore degli aggiornamenti nel dispositivo per sapere come interpretare e usare correttamente i file specificati come file correlati. Questi metadati vengono aggiunti come parte di un properties contenitore di proprietà agli file oggetti e relatedFile .

Per altre informazioni sullo schema di importazione per i file correlati, vedere l'oggetto relatedFiles.

Il manifesto di importazione di esempio seguente illustra come viene usata la funzionalità dei file correlati per importare un aggiornamento differenziale. In questo esempio è possibile notare che nella files sezione è presente un'immagine completa specificata (full-image-file-name) con un properties elemento. L'elemento properties a sua volta ha un elemento associato relatedFiles sotto di esso. All'interno della relatedFiles sezione è possibile visualizzare un'altra properties sezione per il file di aggiornamento delta () e anche un downloadHandler elemento con l'elenco appropriato id (delta-from-v1-file-namemicrosoft/delta:1).

Nota

In questo esempio vengono usati gli aggiornamenti differenziali per illustrare come fare riferimento ai file correlati. Per usare gli aggiornamenti differenziali come funzionalità, vedere la documentazione relativa all'aggiornamento differenziale.

    {
      "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"
    }

Il comando az iot du init v5 per la creazione di un manifesto di importazione supporta un parametro facoltativo --related-file .

Il --related-file parametro accetta una path chiave 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>"}'

Ad esempio:

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

Passaggi successivi