Condividi tramite

Importazione di aggiornamenti in Aggiornamento dei dispositivi per IoT Hub

Per distribuire un aggiornamento ai dispositivi dall'aggiornamento del dispositivo per l'hub IoT, è prima necessario importare tale aggiornamento nel servizio Aggiornamento dispositivi. Questo articolo offre una panoramica di alcuni concetti importanti da comprendere quando si tratta di importare gli aggiornamenti.

Manifesto di importazione

Un manifesto di importazione è un file JSON che definisce informazioni importanti sull'aggiornamento che si sta importando. Si inviano sia il manifesto di importazione che i file di aggiornamento associati (ad esempio un pacchetto di aggiornamento del firmware) come parte del processo di importazione. I metadati definiti nel manifesto di importazione vengono usati per inserire l'aggiornamento. Alcuni metadati vengono usati anche in fase di distribuzione, ad esempio per verificare se un aggiornamento è stato installato correttamente.

Per esempio:

{
  "updateId": {
    "provider": "Contoso",
    "name": "Toaster",
    "version": "1.0"
  },
  "isDeployable": false,
  "compatibility": [
    {
      "deviceManufacturer": "Contoso",
      "deviceModel": "Toaster"
    }
  ],
  "instructions": {
    "steps": [
      {
        "handler": "microsoft/swupdate:1",
        "files": [
          "firmware.swu"
        ],
        "handlerProperties": {
          "installedCriteria": "1.0"
        }
      }
    ]
  },
  "files": [
    {
      "filename": "firmware.swu",
      "sizeInBytes": 7558,
      "hashes": {
        "sha256": "/CD7Sn6fiknWa3NgcFjGlJ+ccA81s1QAXX4oo5GHiFA="
      }
    }
  ],
  "createdDateTime": "2022-01-19T06:23:52.6996916Z",
  "manifestVersion": "4.0"
}

Il manifesto di importazione contiene diversi elementi che rappresentano importanti concetti relativi all'aggiornamento dei dispositivi per l'hub IoT. Questi elementi sono descritti in questa sezione. Per informazioni sullo schema di importazione completo, vedere Importare lo schema JSON del manifesto.

Aggiornare l'identità

L'identità di aggiornamento o updateId è l'identificatore univoco per un aggiornamento nell'Aggiornamento dei dispositivi per IoT Hub. È composto da tre parti:

  • Provider: entità che crea o è direttamente responsabile dell'aggiornamento. Spesso sarà un nome della società.
  • Nome: identificatore per una classe di aggiornamenti. Spesso sarà una classe di dispositivo o un nome di modello.
  • Versione: numero di versione che distingue questo aggiornamento da altri che hanno lo stesso provider e nome.

Per esempio:

{
  "updateId": {
    "provider": "Contoso",
    "name": "Toaster",
    "version": "1.0"
  }
}

Annotazioni

UpdateId viene utilizzato solo dal servizio Update del dispositivo e può differire dalle identità effettive dei componenti software sul dispositivo.

Compatibilità

La compatibilità definisce i criteri di un dispositivo in grado di installare l'aggiornamento. Contiene le proprietà del dispositivo che sono un set di coppie di valori di chiave arbitrarie segnalate da un dispositivo. Solo i dispositivi con proprietà corrispondenti saranno idonei per la distribuzione. Un aggiornamento può essere compatibile con più classi di dispositivi con più set di proprietà del dispositivo.

Di seguito è riportato un esempio di aggiornamento che può essere distribuito solo in un dispositivo che segnala Contoso e Tostapane come produttore e modello del dispositivo.

{
  "compatibility": [
    {
      "deviceManufacturer": "Contoso",
      "deviceModel": "Toaster"
    }
  ]
}

Disposizioni

La parte Istruzioni contiene le informazioni o i passaggi necessari per l'installazione dell'aggiornamento da parte dell'agente del dispositivo. L'aggiornamento più semplice contiene un singolo passaggio inline. Questo passaggio esegue il file di payload incluso usando un gestore registrato con l'agente del dispositivo:

{
  "instructions": {
    "steps": [
      {
        "handler": "microsoft/swupdate:1",
        "files": [
          "contoso.toaster.1.0.swu"
        ]
      }
    ]
  }
}

Suggerimento

handler equivale a updateType nell'importazione del manifesto versione 3.0 o precedente.

Un aggiornamento può contenere più di un passaggio:

{
  "instructions": {
    "steps": [
      {
        "description": "pre-install script",
        "handler": "microsoft/script:1",
        "handlerProperties": {
          "arguments": "--pre-install"
        },
        "files": [
          "configure.sh"
        ]
      },
      {
        "description": "firmware package",
        "handler": "microsoft/swupdate:1",
        "files": [
          "contoso.toaster.1.0.swu"
        ]
      }
    ]
  }
}

Un aggiornamento può contenere passaggi di riferimento che istruiscono l'agente del dispositivo a installare un altro aggiornamento con il proprio manifesto di importazione, stabilendo una relazione di aggiornamento padre e figlio. Ad esempio, un aggiornamento per un tostapane può contenere due sotto-aggiornamenti:

{
  "instructions": {
    "steps": [
      {
        "type": "reference",
        "updateId": {
          "provider": "Contoso",
          "name": "Toaster.HeatingElement",
          "version": "1.0"
        }
      },
      {
        "type": "reference",
        "updateId": {
          "provider": "Contoso",
          "name": "Toaster.Sensors",
          "version": "1.0"
        }
      }
    ]
  }
}

Annotazioni

Un aggiornamento può contenere qualsiasi combinazione di passaggi inline e di riferimento.

File

La parte File contiene i metadati dei file di payload di aggiornamento, ad esempio i nomi, le dimensioni e l'hash. Aggiornamento del dispositivo per l'hub IoT usa questi metadati per la convalida dell'integrità durante il processo di importazione. Le stesse informazioni vengono quindi inoltrate all'agente del dispositivo per ripetere la convalida dell'integrità prima dell'installazione.

Annotazioni

Un aggiornamento che contiene solo i passaggi di riferimento non includerà alcun file di payload di aggiornamento nell'aggiornamento padre.

Creare un manifesto di importazione

È possibile usare qualsiasi editor di testo per creare un file JSON manifesto. Sono disponibili anche script di esempio per la creazione di un manifesto di importazione a livello di codice in Azure/iot-hub-device-update in GitHub.

Importante

Un nome file JSON del manifesto di importazione deve terminare con .importmanifest.json quando viene importato tramite il portale di Azure.

Suggerimento

Usare Visual Studio Code per abilitare il completamento automatico e la convalida dello schema JSON durante la creazione di un manifesto di importazione.

Limiti all'importazione degli aggiornamenti

Alcuni limiti vengono applicati per ogni Device Update per istanza di IoT Hub. Se non li hai già esaminati, vedere Limiti di aggiornamento dei dispositivi.

Passaggi successivi

  • Last updated on