Azure Device Update per hub IoT concetti relativi all'importazione
Per distribuire un aggiornamento ai dispositivi usando Aggiornamento dispositivi di Azure per hub IoT, importare prima l'aggiornamento nel servizio Aggiornamento dispositivi, che archivia l'aggiornamento importato e lo distribuisce nei dispositivi. Questo articolo offre una panoramica di alcuni concetti importanti da comprendere quando si tratta di importare gli aggiornamenti.
Importare il manifesto
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 convalidare se un aggiornamento è installato correttamente.
Il codice JSON seguente mostra un file manifesto di importazione di esempio:
{
"updateId": {
"provider": "Contoso",
"name": "Toaster",
"version": "1.0"
},
"isDeployable": false,
"compatibility": [
{
"manufacturer": "Contoso",
"model": "Toaster"
}
],
"instructions": {
"steps": [
{
"handler": "microsoft/swupdate:2",
"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": "5.0"
}
Le sezioni del file manifesto di importazione rappresentano importanti concetti di Aggiornamento dispositivi, come descritto nelle sezioni seguenti. Per informazioni sullo schema del manifesto 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 in Aggiornamento dispositivi e contiene le proprietà seguenti:
- Provider è l'entità che crea o è responsabile dell'aggiornamento. Il provider è spesso un nome della società.
- Name è l'identificatore di una classe di aggiornamento. Il nome è spesso una classe di dispositivo o un nome di modello.
- Version è un numero che distingue questo aggiornamento da altri con lo stesso provider e nome.
Ad esempio:
{
"updateId": {
"provider": "Contoso",
"name": "Toaster",
"version": "1.0"
}
}
Nota
Viene updateId usato solo dal servizio Aggiornamento dispositivi ed è diverso dalle identità dei componenti software nei dispositivi.
Compatibilità
La sezione Compatibilità usa una o più coppie chiave-valore arbitrarie per definire i dispositivi che possono installare un aggiornamento. Solo i dispositivi che segnalano le proprietà corrispondenti ai valori di compatibilità sono idonei per distribuire l'aggiornamento. È possibile rendere compatibile un aggiornamento con più classi di dispositivi includendo più set di proprietà di compatibilità dei dispositivi.
L'esempio seguente mostra un aggiornamento che può essere distribuito solo ai dispositivi che segnalano Contoso e Tostapane come produttore e modello del dispositivo.
{
"compatibility": [
{
"manufacturer": "Contoso",
"model": "Toaster"
}
]
}
Istruzioni
La sezione 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 che esegue il file payload di aggiornamento usando un gestore registrato con l'agente del dispositivo. Nell'esempio seguente viene illustrata una sezione istruzioni in un unico passaggio.
{
"instructions": {
"steps": [
{
"handler": "microsoft/swupdate:2",
"files": [
"contoso.toaster.1.0.swu"
]
}
]
}
}
Nota
La handler proprietà equivale alla proprietà nell'importazione del updateType manifesto versione 3.0 o precedente.
Un aggiornamento può contenere più di un passaggio, come nell'esempio seguente:
{
"instructions": {
"steps": [
{
"description": "pre-install script",
"handler": "microsoft/script:1",
"handlerProperties": {
"arguments": "--pre-install"
},
"files": [
"configure.sh"
]
},
{
"description": "firmware package",
"handler": "microsoft/swupdate:2",
"files": [
"contoso.toaster.1.0.swu"
]
}
]
}
}
Un aggiornamento può contenere passaggi di riferimento che indicano all'agente del dispositivo di installare un altro aggiornamento con il proprio manifesto di importazione, stabilendo una relazione di aggiornamento padre e figlio. Un aggiornamento può contenere qualsiasi combinazione di passaggi inline e di riferimento.
Ad esempio, un aggiornamento per un tostapane può contenere due aggiornamenti figlio:
{
"instructions": {
"steps": [
{
"type": "reference",
"updateId": {
"provider": "Contoso",
"name": "Toaster.HeatingElement",
"version": "1.0"
}
},
{
"type": "reference",
"updateId": {
"provider": "Contoso",
"name": "Toaster.Sensors",
"version": "1.0"
}
}
]
}
}
File
La sezione File del manifesto di importazione contiene i metadati del file payload di aggiornamento, ad esempio name, sizee hash. Device Update usa questi metadati per la convalida dell'integrità durante il processo di importazione e inoltra le stesse informazioni all'agente del dispositivo per la convalida dell'integrità prima dell'installazione.
Nota
Un aggiornamento padre che contiene solo i passaggi di riferimento non definisce alcun file di payload di aggiornamento.
Creare un manifesto di importazione
Anche se è possibile creare manualmente un file JSON del manifesto di importazione usando un editor di testo, l'interfaccia della riga di comando di Azure semplifica notevolmente il processo. Quando si è pronti per provare la creazione di un manifesto di importazione, è possibile usare la guida pratica.
Importante
Per importare nel servizio Aggiornamento dispositivi tramite il portale di Azure, un nome file JSON del manifesto di importazione deve terminare con .importmanifest.json.
Suggerimento
È possibile usare Visual Studio Code per abilitare il completamento automatico e la convalida dello schema JSON quando si crea un manifesto di importazione.
Aggiornare i limiti di importazione
Alcuni limiti vengono applicati per ogni aggiornamento del dispositivo per hub IoT'istanza. Se non sono già stati esaminati, vedere Limiti di Aggiornamento dispositivi.