Condividi tramite

Importazione di aggiornamenti in Aggiornamento dispositivi per hub IoT

  • Articolo

Per distribuire un aggiornamento ai dispositivi da Aggiornamento dispositivi per hub IoT, è prima necessario importare tale aggiornamento nel servizio Aggiornamento dispositivi. L'aggiornamento importato verrà archiviato nel servizio Aggiornamento dispositivi e può essere distribuito da lì ai dispositivi. Questo articolo offre una panoramica di alcuni concetti importanti da comprendere quando si tratta di importare gli aggiornamenti.

Importa manifesto

Un manifesto di importazione è un file JSON che definisce informazioni importanti sull'aggiornamento che si sta importando. Inviare 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.

Ad esempio:

{
  "updateId": {
    "provider": "Contoso",
    "name": "Toaster",
    "version": "1.0"
  },
  "isDeployable": false,
  "compatibility": [
    {
      "manufacturer": "Contoso",
      "model": "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": "5.0"
}

Il manifesto di importazione contiene diversi elementi che rappresentano importanti aggiornamenti del dispositivo per hub IoT concetti. 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 in Aggiornamento dispositivi per hub IoT. È composto da tre parti:

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

Ad esempio:

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

Nota

UpdateId viene usato solo dal servizio Aggiornamento dispositivi e può essere diverso dalle identità dei componenti software effettivi nel 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.

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

{
  "compatibility": [
    {
      "manufacturer": "Contoso",
      "model": "Toaster"
    }
  ]
}

Istruzioni

La parte Istruzioni contiene le informazioni necessarie 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 indicano all'agente del dispositivo di 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 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"
        }
      }
    ]
  }
}

Nota

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

File

La parte File contiene i metadati dei file payload di aggiornamento, ad esempio i nomi, le dimensioni e l'hash. Aggiornamento del dispositivo per 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.

Nota

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

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

Un nome file JSON del manifesto di importazione deve terminare con .importmanifest.json quando viene importato tramite 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 aggiornamento del dispositivo per hub IoT'istanza. Se non sono già stati esaminati, vedere Limiti di Aggiornamento dispositivi.

Passaggi successivi