Come eseguire automaticamente la migrazione di un hub IoT usando l'interfaccia della riga di comando di Azure

  • Articolo

Usare l'interfaccia della riga di comando di Azure per eseguire la migrazione di un hub IoT a una nuova area, a un nuovo livello o a una nuova configurazione.

I passaggi descritti in questo articolo sono utili se si vuole:

  • Eseguire l'aggiornamento dal livello gratuito a un hub IoT di livello Basic o Standard.
  • Spostare un hub IoT in una nuova area.
  • Esportare le informazioni sullo stato dell'hub IoT per avere come backup.
  • Aumentare il numero di partizioni per un hub IoT.
  • Configurare un hub per uno sviluppo, anziché per l'ambiente di produzione.

Confrontare i passaggi di migrazione automatica e manuale

Il risultato di questo articolo è simile a Come eseguire la migrazione di un hub IoT di Azure usando i modelli di Azure Resource Manager, ma con un processo diverso. Prima di iniziare, decidere quale processo è adatto per lo scenario.

  • Processo dell'interfaccia della riga di comando di Azure (questo articolo):

    • Esegue la migrazione del registro dei dispositivi, delle informazioni sul routing e sull'endpoint e di altri dettagli di configurazione, ad esempio le distribuzioni di IoT Edge o le configurazioni automatiche di gestione dei dispositivi.
    • È più semplice eseguire la migrazione di un numero ridotto di dispositivi(ad esempio, fino a 10.000).
    • Non richiede un account di archiviazione di Azure.
    • Raccoglie le stringhe di connessione per l'endpoint di routing e caricamento di file e le include nell'output del modello di Resource Manager.

  • Il processo manuale:

    • Esegue la migrazione del registro dei dispositivi e delle informazioni sul routing e sull'endpoint. È necessario ricreare manualmente altri dettagli di configurazione nel nuovo hub IoT.
    • È più veloce per la migrazione di un numero elevato di dispositivi (ad esempio, più di 100.000).
    • Usa un account di archiviazione di Azure per trasferire il registro dei dispositivi.
    • Elimina le stringhe di connessione per gli endpoint di routing e caricamento di file dall'output del modello di Resource Manager ed è necessario aggiungerle manualmente.

Prerequisiti

  • Interfaccia della riga di comando di Azure

    Le funzionalità descritte in questo articolo richiedono la versione 0.20.0 o successiva dell'estensione azure-iot . Per controllare la versione dell'estensione, eseguire az --version. Per aggiornare l'estensione, eseguire az extension update --name azure-iot.

    Se è ancora installata l'estensione azure-cli-iot-ext legacy, rimuovere tale estensione prima di aggiungere l'estensione azure-iot .

Stato dell'hub IoT

Quando si parla di migrazione dello stato di un hub IoT, si fa riferimento a una combinazione di tre aspetti:

  • Risorse di Azure Resource Manager (ARM). Questo aspetto è tutto ciò che può essere definito in un modello di risorsa ed è la stessa informazione che si otterrebbe se il modello di risorsa è stato esportato dall'hub IoT nell'portale di Azure. Le informazioni acquisite come parte dell'aspetto di Azure Resource Manager includono:

    • Tempo di conservazione dell'hub eventi predefinito
    • Certificati
    • Proprietà da cloud a dispositivo
    • Disabilitare la firma di accesso condiviso del dispositivo
    • Disabilitare l'autenticazione locale
    • Abilitare le notifiche di caricamento file
    • Endpoint di archiviazione caricamento file
    • Identità
      • Identità assegnate dall'utente
      • Identità assegnate dal sistema (abilitate o disabilitate)
    • Set di regole di rete
    • Routing
      • Endpoint personalizzati
      • Route di fallback
      • Route
    • Tag

  • Configurazioni. Questo aspetto riguarda gli aspetti di un hub IoT che non sono rappresentati in un modello di Resource Manager. In particolare, questo aspetto illustra le configurazioni automatiche di gestione dei dispositivi e le distribuzioni IoT Edge.

  • Dispositivi. Questo aspetto rappresenta le informazioni nel registro dei dispositivi, tra cui:

    • Identità dei dispositivi e gemelli
    • Identità dei moduli e gemelli

Qualsiasi hub IoT proprietà o configurazione non elencata qui potrebbe non essere esportata o importata correttamente.

Esportare lo stato di un hub IoT

Usare il comando az iot hub state export per esportare lo stato di un hub IoT in un file JSON.

Per eseguire i passaggi di esportazione e importazione in un comando, vedere la sezione più avanti in questo articolo per eseguire la migrazione di un hub IoT.

Quando si esporta lo stato di un hub IoT, è possibile scegliere quali aspetti esportare.

Parametro Dettagli
--aspects Aspetti dello stato da esportare. Specificare uno o più valori accettati: arm, configurazioni o dispositivi. Se questo parametro viene lasciato fuori, vengono esportati tutti e tre gli aspetti.
--state-file -f Percorso del file in cui sono scritte le informazioni sullo stato.
--replace -r Se questo parametro è incluso, il comando di esportazione sovrascrive il contenuto del file di stato.
--hub-name -n
or
--login -l		 Nome dell'hub IoT di origine (-n) o della stringa di connessione per l'hub IoT di origine (-l). Se vengono forniti entrambi, la stringa di connessione ha la priorità.
--resource-group -g Nome del gruppo di risorse per l'hub IoT di origine.

L'esempio seguente esporta tutti gli aspetti dello stato di un hub IoT in un file denominato myHub-state:

az iot hub state export --hub-name myHub --state-file ./myHub-state.json

L'esempio seguente esporta solo i dispositivi e Azure Resource Manager aspetti dello stato di un hub IoT e sovrascrive il contenuto del file esistente:

az iot hub state export --hub-name myHub --state-file ./myHub-state.json --aspects arm devices --replace

Esportare gli endpoint

Se si sceglie di esportare l'aspetto di Azure Resource Manager di un hub IoT, il comando di esportazione recupera le stringhe di connessione per tutti gli endpoint con autenticazione basata su chiave e includerli nel modello di Resource Manager di output.

Il comando di esportazione controlla anche tutti gli endpoint per verificare che la risorsa a cui si connette esista ancora. In caso contrario, l'endpoint e le route che usano tale endpoint non vengono esportati.

Importare lo stato di un hub IoT

Usare il comando az iot hub state import per importare informazioni sullo stato da un file esportato in un hub IoT nuovo o esistente.

Per eseguire i passaggi di esportazione e importazione in un comando, vedere la sezione più avanti in questo articolo per eseguire la migrazione di un hub IoT.

Parametro Dettagli
--aspects Aspetti dello stato da importare. Specificare uno o più valori accettati: arm, configurazioni o dispositivi. Se questo parametro viene lasciato fuori, vengono importati tutti e tre gli aspetti.
--state-file -f Percorso del file di stato esportato.
--replace -r Se questo parametro è incluso, il comando import elimina lo stato corrente dell'hub di destinazione.
--hub-name -n
or
--login -l		 Nome dell'hub IoT di destinazione (-n) o stringa di connessione per l'hub IoT di destinazione (-l). Se vengono forniti entrambi, la stringa di connessione ha la priorità.
--resource-group -g Nome del gruppo di risorse per l'hub IoT di destinazione.

L'esempio seguente importa tutti gli aspetti in un nuovo hub IoT, che viene creato se non esiste già:

az iot hub state import --hub-name myNewHub --state-file ./myHub-state.json

L'esempio seguente importa solo i dispositivi e gli aspetti delle configurazioni in un nuovo hub IoT, che deve esistere già e sovrascrive tutti i dispositivi e le configurazioni esistenti:

az iot hub state import --hub-name myNewHub --state-file ./myHub-state.json --aspects devices configurations --replace

Creare un nuovo hub IoT con l'importazione dello stato

È possibile usare il az iot hub state import comando per creare un nuovo hub IoT o per scrivere in un hub IoT esistente.

Se si vuole creare una nuova hub IoT, è necessario includere l'aspetto arm nel comando di importazione. Se arm non è incluso nel comando e l'hub di destinazione non esiste, il comando di importazione ha esito negativo.

Se l'hub di destinazione non esiste, è necessario anche il --resource-group parametro per il comando di importazione.

Aggiornare un hub IoT esistente con l'importazione dello stato

Se l'hub IoT di destinazione esiste già, l'aspetto arm non è necessario per il az iot hub state import comando. Se si include l'aspetto arm , tutte le proprietà delle risorse verranno sovrascritte ad eccezione delle proprietà seguenti che non possono essere modificate dopo la creazione dell'hub:

  • Posizione
  • SKU
  • Conteggio delle partizioni di Hub eventi predefinito
  • Residenza dei dati
  • Funzionalità

Se l'oggetto --resource-group viene specificato nel comando di importazione ed è diverso dal gruppo di risorse corrente dell'hub IoT, il comando ha esito negativo perché tenta di creare un nuovo hub con lo stesso nome di quello già esistente.

Se si include il --replace flag nel comando di importazione, gli aspetti seguenti dell'hub IoT vengono rimossi dall'hub di destinazione prima del caricamento dello stato dell'hub:

  • ARM: tutti i certificati caricati nell'hub di destinazione vengono eliminati. Se è presente un certificato, è necessario aggiornare un etag.
  • Dispositivi: tutti i dispositivi e i moduli, perimetrali e non perimetrali, vengono eliminati.
  • Configurazioni: tutte le configurazioni ADM e le distribuzioni IoT Edge vengono eliminate.

Eseguire la migrazione di un hub IoT

Usare il comando az iot hub state migrate per eseguire la migrazione dello stato di un hub IoT a un hub IoT nuovo o esistente.

Questo comando esegue il wrapping dei passaggi di esportazione e importazione in un singolo comando, ma non contiene file di output. Tutte le linee guida e le limitazioni descritte nelle sezioni Esportare lo stato di un hub IoT e Importare lo stato di un hub IoT si applicano anche al state migrate comando.

Se si esegue la migrazione di un registro dei dispositivi con molti dispositivi (ad esempio, poche centinaia o poche migliaia) è possibile che sia più semplice e veloce eseguire separatamente i comandi di esportazione e importazione anziché eseguire il comando di migrazione.

Parametro Dettagli
--aspects Aspetti dello stato di cui eseguire la migrazione. Specificare uno o più valori accettati: arm, configurazioni o dispositivi. Se questo parametro viene lasciato fuori, viene eseguita la migrazione di tutti e tre gli aspetti.
--replace -r Se questo parametro è incluso, il comando migrate elimina lo stato corrente dell'hub di destinazione.
--destination-hub --dh
or
--destination-hub-login --dl		 Nome dell'hub IoT di destinazione (--dh) o stringa di connessione per l'hub IoT di destinazione (--dl). Se vengono forniti entrambi, la stringa di connessione ha la priorità.
--destination-resource-group --dg Nome del gruppo di risorse per l'hub IoT di destinazione. Il gruppo di risorse di destinazione è necessario se l'hub di destinazione non esiste.
--origin-hub --oh
or
--origin-hub-login --ol		 Nome dell'hub IoT di origine (--oh) o della stringa di connessione per l'hub IoT di origine (--ol). Se vengono forniti entrambi, la stringa di connessione ha la priorità. Usare la stringa di connessione per evitare di dover accedere alla sessione dell'interfaccia della riga di comando di Azure.
--origin-resource-group --og Nome del gruppo di risorse per l'hub IoT di origine.

L'esempio seguente esegue la migrazione di tutti gli aspetti dell'hub di origine all'hub di destinazione, che viene creato se non esiste:

az iot hub state migrate --origin-hub myHub --origin-resource-group myGroup  --destination-hub myNewHub --destination-resource-group myNewGroup

Risolvere i problemi relativi a una migrazione

Se non è possibile esportare o importare dispositivi o configurazioni, verificare di avere accesso a tali proprietà. Un modo per verificare l'accesso consiste nell'eseguire i az iot hub device-identity list comandi o az iot hub configuration list .

Se il az iot hub state migrate comando non riesce, provare a eseguire separatamente i comandi di esportazione e importazione. I due comandi generano la stessa funzionalità del solo comando di migrazione, ma eseguendoli separatamente è possibile esaminare i file di stato creati dal comando di esportazione.

Passaggi successivi

Per altre informazioni sull'esecuzione di operazioni bulk sul registro delle identità in un hub IoT, vedere Importare ed esportare hub IoT identità del dispositivo.