Importazione di aggiornamenti in Aggiornamento dispositivi per hub IoT

Per distribuire un aggiornamento ai dispositivi da Aggiornamento dispositivi per 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.

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

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": [
    {
      "deviceManufacturer": "Contoso",
      "deviceModel": "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"
        ]
      }
    ]
  }
}

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

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.

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.

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

• Per altre informazioni sul processo di importazione, vedere Preparare un aggiornamento da importare.
• Esaminare lo schema del manifesto di importazione.