Panoramica degli aggiornamenti software (anteprima)

Usa Aggiornamenti software, una funzionalità del Registro Dispositivi Azure, per fornire aggiornamenti over-the-air ai dispositivi su larga scala. Importare gli aggiornamenti in uno spazio di nomi Azure Device Registry e poi utilizzare job e gruppi in quel namespace per distribuirli sui dispositivi.

Applicabilità del servizio

Aggiornamenti software e aggiornamento del dispositivo per hub IoT

Gli aggiornamenti software portano le funzionalità di aggiornamento via etere nell'Azure Device Registry. Utilizza lo stesso formato di manifesto di importazione di Device Update per hub IoT e ti permette di gestire gli aggiornamenti a livello di namespace utilizzando gruppi e processi di Azure Device Registry.

Usa le seguenti indicazioni per scegliere l'opzione giusta:

Tieni a mente le seguenti considerazioni se già usi Device Update per hub IoT:

• Non puoi usarli entrambi sullo stesso hub IoT. In questa anteprima, puoi utilizzare gli aggiornamenti software solo con hub IoT che non dispongono di un'istanza esistente di Device Update for hub IoT. Per provare gli aggiornamenti software, collega un IoT hub che non utilizza Device Update for hub IoT al tuo namespace.
• I dispositivi usano un client diverso. I dispositivi che eseguono l'agente Device Update non possono ricevere aggiornamenti tramite gli aggiornamenti software. Per ricevere aggiornamenti software, un dispositivo utilizza il client di aggiornamenti software negli SDK Azure IoT unificati (anteprima).

Come funzionano gli aggiornamenti software

Abiliti gli aggiornamenti software su uno spazio dei nomi di Azure Device Registry, sia quando configuri il namespace che in seguito. Per saperne come procedere, consulta Inizia con Azure Device Registry (anteprima). La funzionalità introduce i seguenti componenti:

• Aggiornamento software: Un aggiornamento che si importa in un namespace. Un aggiornamento software consiste in uno o più file di aggiornamento e un manifest di importazione. Dopo aver importato un aggiornamento software, è disponibile per i lavori di aggiornamento software e i lavori di aggiornamento di onboarding in quel namespace.
• Lavoro di aggiornamento software: applica un aggiornamento software ai dispositivi compatibili in un gruppo target.
• Processo di aggiornamento durante l'onboarding: applica un aggiornamento software ai dispositivi compatibili quando verificano la disponibilità di aggiornamenti durante l'onboarding, prima che si registrino e inizino a funzionare.
• Client degli aggiornamenti software: La parte degli SDK unificati Azure IoT (anteprima) che la tua applicazione del dispositivo utilizza per verificare, scaricare e installare aggiornamenti software e per riportare i risultati.

Un tipico flusso di aggiornamento appare così:

1. Carichi i file di aggiornamento e il manifesto di importazione su un container Archiviazione di Azure.
2. Importi l'aggiornamento software nel tuo namespace.
3. Crei un lavoro che mira a un gruppo o, per l'onboarding, al namespace.
4. Ogni dispositivo controlla gli aggiornamenti e riporta le proprie proprietà di compatibilità. Se il dispositivo è compatibile, riceve l'aggiornamento.
5. Il dispositivo scarica e installa l'aggiornamento, poi riporta il risultato. Monitori i progressi e i risultati a livello di dispositivo durante l'esecuzione del lavoro.

Aggiornamenti software

Un aggiornamento software consiste in due componenti che si caricano insieme:

• File di aggiornamento: Il payload che il dispositivo installa. Il payload può essere un'immagine firmware, un pacchetto software, uno script o più file correlati.
• Manifesto di importazione: un file JSON con l'estensione .importmanifest.json che descrive l'aggiornamento. La distinta di importazione dichiara:
  • Identità dell'aggiornamento: il provider, il nome e la versione che identificano in modo univoco l'aggiornamento. Il provider e il nome insieme identificano una famiglia di aggiornamenti, come tutte le versioni del firmware per un modello di dispositivo.
  • Proprietà di compatibilità: Le proprietà del dispositivo che determinano quali dispositivi possono installare l'aggiornamento. Per maggiori informazioni, vedi Compatibilità dei dispositivi.
  • Istruzioni di installazione: i passaggi di installazione, il loro ordine e il gestore per ogni passaggio. Il gestore indica al dispositivo come applicare il passaggio specifico, ad esempio installando un pacchetto, eseguendo uno script o scrivendo un’immagine.
  • Metadati del file: nome, dimensione e hash di ogni file di aggiornamento. Il servizio utilizza gli hash per verificare l'integrità dei file all'importazione, e il dispositivo può usarli per verificare ogni file prima dell'installazione.

Ogni aggiornamento software richiede un manifest di importazione. Se provi a importare file di aggiornamento senza un manifest di importazione, l'importazione fallisce. Quando importi, puoi opzionalmente scansionare i file di aggiornamento per malware. La scansione malware è disponibile in alcune regioni. Per istruzioni passo dopo passo, vedi Importa un aggiornamento software.

Il seguente esempio mostra un manifest di importazione per un aggiornamento basato su immagini:

{
  "updateId": {
    "provider": "Contoso",
    "name": "IrrigationControllerV2-Image",
    "version": "1.3.0"
  },
  "isDeployable": true,
  "compatibility": [
    {
      "manufacturer": "Contoso",
      "model": "IrrigationControllerV2"
    }
  ],
  "instructions": {
    "steps": [
      {
        "type": "inline",
        "description": "Update the device image to version 1.3.0",
        "handler": "microsoft/swupdate:1",
        "files": [
          "contoso-irrigation-controller-v2-1.3.0.swu"
        ],
        "handlerProperties": {
          "installedCriteria": "1.3.0"
        }
      }
    ]
  },
  "files": [
    {
      "filename": "contoso-irrigation-controller-v2-1.3.0.swu",
      "sizeInBytes": 112738816,
      "hashes": {
        "sha256": "wPdNKUSmWTZkR6Pum9oR/EIzdn5AvON4dsXME+/gHVw="
      }
    }
  ],
  "createdDateTime": "2026-10-01T06:56:51.2002204Z",
  "manifestVersion": "5.0"
}

Gli aggiornamenti software utilizzano lo stesso formato di manifesto di importazione di Device Update for hub IoT. Per imparare come redigere un manifesto di importazione, vedi:

• Schema del manifest di importazione
• Esecuzione ordinata a più passi

Compatibilità dei dispositivi

Le proprietà di compatibilità in un manifesto di importazione determinano quali dispositivi possono installare un aggiornamento software. Quando un dispositivo verifica gli aggiornamenti, riporta le proprie proprietà di compatibilità. Azure Device Registry confronta queste proprietà con quelle di compatibilità dichiarate nell'aggiornamento software.

Definisci le proprietà di compatibilità come coppie nome-valore. Ogni aggiornamento software deve dichiarare almeno una proprietà di compatibilità. manufacturer e model sono scelte comuni, ma non sono obbligatorie. Usa qualsiasi proprietà che si adatti alla tua flotta, come region o environment.

La compatibility sezione del manifesto di importazione è un array di insiemi di proprietà. Ad esempio:

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

L'abbinamento funziona come segue:

• Un dispositivo deve corrispondere a ogni proprietà di un insieme. L'aggiornamento precedente si applica solo ai dispositivi che segnalano sia manufacturer come Contoso che model come IrrigationControllerV2. Non si applica a un dispositivo Contoso SoilSensorV1 , né a un IrrigationControllerV2 dispositivo che segnala un produttore diverso.
• Un dispositivo deve corrispondere a un solo set. Se dichiari più di un set di proprietà, un singolo aggiornamento software può applicarsi a più tipi di dispositivi.
• Ogni set di proprietà appartiene a una famiglia di aggiornamenti. Non puoi usare esattamente lo stesso insieme di proprietà di compatibilità con più di una combinazione di provider e nome. Pianificare insieme i gruppi di aggiornamento e le proprietà di compatibilità. Per ulteriori informazioni, vedi Concetti di importazione.

Un gruppo può contenere dispositivi con proprietà di compatibilità diverse. Un lavoro di aggiornamento software applica l'aggiornamento solo ai dispositivi compatibili nel gruppo target. Ad esempio, se un gruppo contiene 18 IrrigationControllerV2 dispositivi e sei SoilSensorV1 dispositivi, un aggiornamento per i dispositivi IrrigationControllerV2 viene applicato ai 18 dispositivi compatibili. I sei SoilSensorV1 dispositivi non sono interessati.

Processi, gruppi e comportamento di implementazione

Distribuisci un aggiornamento software creando un job nel namespace. Gli aggiornamenti software supportano due tipi di lavoro:

Un lavoro di aggiornamento software non si ferma dopo aver raggiunto i dispositivi compatibili quando viene avviato. Mentre l'esecuzione del lavoro è attiva, continua ad applicare l'aggiornamento a:

• Dispositivi che erano offline quando è iniziato il processo, dopo essersi riconnessi e aver controllato eventuali aggiornamenti.
• Dispositivi che appartengono al gruppo target. L'appartenenza al gruppo non viene aggiornata automaticamente: nuovi dispositivi si uniscono al gruppo la prossima volta che aggiorni la sua appartenenza. Per maggiori informazioni, consulta Appartenenza memorizzata nella cache e aggiornamento.
• I dispositivi che diventano idonei all'aggiornamento, ad esempio, perché le loro proprietà di compatibilità segnalate cambiano.

Un lavoro di aggiornamento di onboarding rimane attivo finché non lo termini, così i dispositivi compatibili continuano a ricevere l'aggiornamento man mano che completano l'onboarding.

Per gli stati, la pianificazione e il monitoraggio dei processi, vedere Concetti relativi ai processi (anteprima).

Considerazioni sull’SDK del dispositivo

I dispositivi ricevono aggiornamenti software tramite il client di aggiornamenti software negli SDK unificati Azure IoT (anteprima). Tieni a mente le seguenti considerazioni quando pianifichi il software del tuo dispositivo:

• Dispositivi supportati: In questa anteprima, il client di aggiornamenti software è principalmente destinato a dispositivi basati su Linux con più di 32 MB di memoria disponibile.
• Integrazione: L'SDK è una libreria, non un agente pronto all'uso. Integri il client degli aggiornamenti software nell'applicazione del dispositivo e fornisci la logica che scarica, installa e applica gli aggiornamenti sull'hardware. Microsoft fornisce esempi per aiutarti a iniziare.
• Due modi per controllare gli aggiornamenti: un dispositivo che è in fase di onboarding controlla gli aggiornamenti di onboarding prima di registrarsi. Un dispositivo registrato controlla gli aggiornamenti software da un processo di aggiornamento software. L'applicazione del tuo dispositivo decide quando controllare gli aggiornamenti.
• Connettività: Il dispositivo verifica gli aggiornamenti e riporta i risultati tramite la sua connessione al Device Provisioning Service. Non ha bisogno di un endpoint o di una credenziale separata per ricevere aggiornamenti.
• Sicurezza: Prima di scaricare qualsiasi file di aggiornamento, il client di aggiornamenti software verifica la firma delle informazioni di aggiornamento ricevute dal servizio. I dispositivi scaricano i file di aggiornamento solo tramite HTTPS, quindi il contenuto degli aggiornamenti è sempre criptato durante il transito. Assicurati che i tuoi dispositivi possano effettuare connessioni HTTPS in uscita per scaricare i file di aggiornamento.
• Segnalazione dello stato: Dopo un tentativo di installazione, il dispositivo riporta il risultato, inclusi i codici di errore in caso di fallimento dell'installazione. Il risultato appare nei risultati a livello di dispositivo dell'esecuzione del lavoro.
• Tua responsabilità: sei responsabile di validare l'integrazione nel tuo ambiente, incluso il comportamento di recupero se un'installazione fallisce o il dispositivo si riavvia durante un aggiornamento.

Limitazioni dell'anteprima

L'anteprima corrente presenta le limitazioni seguenti:

• Gli aggiornamenti software supportano i dispositivi connessi all'hub IoT. I dispositivi e gli asset di Operazioni di Azure IoT non sono supportati in questa anteprima.
• Non puoi utilizzare aggiornamenti software con un IoT hub che ha un'istanza esistente di Device Update for hub IoT.
• Ogni aggiornamento software richiede un manifest di importazione. Non puoi creare un manifest di importazione nel portale di Azure.
• Il client degli aggiornamenti software attualmente non supporta aggiornamenti proxy o aggiornamenti che utilizzano i passaggi di riferimento (aggiornamenti genitori e figli).

Per informazioni sui limiti applicabili agli aggiornamenti importati, come la dimensione massima dell'aggiornamento, vedere Device Update for hub IoT limits. Per i limiti che si applicano a gruppi e processi, vedere Concetti relativi ai gruppi (anteprima) e Concetti relativi ai processi (anteprima).

Contenuti correlati

• Importa un aggiornamento software
• Distribuisci un aggiornamento software a un gruppo
• Distribuire un aggiornamento di onboarding in uno spazio dei nomi
• Concetti relativi ai gruppi (anteprima)
• Concetti relativi ai lavori (anteprima)
• Unified Azure IoT SDKs (anteprima)