Gestione automatica di dispositivi IoT e moduli con l'interfaccia della riga di comando di Azure

  • Articolo

La gestione automatica dei dispositivi nell'hub IoT di Azure consente di automatizzare molte attività ripetitive e complesse di gestione di un numero elevato di dispositivi. La gestione automatica dei dispositivi consente di gestire un insieme di dispositivi in base alle proprietà, definire la configurazione desiderata e quindi permette all'hub IoT di aggiornare i dispositivi quando rientrano nell'ambito. Questo aggiornamento viene eseguito utilizzando una configurazione automatica del dispositivo o una configurazione automatica del modulo, che consente di riepilogare il completamento e la conformità, gestire l'unione e i conflitti, nonché implementare le configurazioni con un approccio graduale.

Nota

Le funzionalità descritte in questo articolo sono disponibili solo nel livello Standard dell'hub IoT. Per altre informazioni sui livelli di hub IoT di base e standard/gratuiti, vedere Scegliere il livello di hub IoT appropriato per la soluzione.

La gestione automatica dei dispositivi funziona aggiornando una serie di dispositivi gemelli o moduli gemelli con le proprietà desiderate e creando un riepilogo basato su proprietà gemellate riportate. Introduce una nuova classe e un documento JSON denominato configurazione con tre parti:

  • La condizione di destinazione definisce l'ambito dei dispositivi o dei moduli gemelli da aggiornare. La condizione di destinazione viene specificata come query sui tag e/o le proprietà segnalate dei dispositivi gemelli.

  • Il contenuto di destinazione definisce le proprietà desiderate da aggiungere o aggiornare nei moduli o nei dispositivi gemelli di destinazione. Il contenuto include un percorso della sezione delle proprietà desiderate da modificare.

  • Le metriche definiscono i conteggi di riepilogo dei vari stati di configurazione, ad esempio Success, In progress ed Error. Le metriche personalizzate vengono specificate come query sulle proprietà segnalate dei gemelli. Le metriche di sistema sono metriche predefinite che misurano lo stato di aggiornamento dei gemelli, ad esempio il numero di dispositivi gemelli di destinazione e di quelli che sono stati aggiornati.

Le configurazioni automatiche vengono eseguite per la prima volta poco dopo la creazione della configurazione e quindi a intervalli di cinque minuti. Le query per le metriche vengono eseguite ogni volta che viene eseguita la configurazione automatica. Un massimo di 100 configurazioni automatiche è supportato in hub IoT standard; dieci su hub IoT di livello gratuito. Si applicano anche limiti di limitazione. Per altre informazioni, vedere Quote e limitazione.

Prerequisiti dell'interfaccia della riga di comando

Nota

Questo articolo usa la versione più recente dell'estensione Azure IoT, denominata azure-iot. La versione legacy viene chiamata azure-cli-iot-ext. Deve essere installata solo una versione alla volta. È possibile usare il comando az extension list per convalidare le estensioni attualmente installate.

Usare az extension remove --name azure-cli-iot-ext per rimuovere la versione legacy dell'estensione.

Usare az extension add --name azure-iot per aggiungere la nuova versione dell'estensione.

Per visualizzare le estensioni installate, usare az extension list.

Implementare i dispositivi o i moduli gemelli

Le configurazioni automatiche dei dispositivi richiedono l'uso di dispositivi gemelli per la sincronizzazione dello stato tra il cloud e i dispositivi. Per altre informazioni, vedere Comprendere e usare dispositivi gemelli nell'hub IoT.

Le configurazioni automatiche dei dispositivi richiedono l'uso di moduli gemelli per la sincronizzazione dello stato tra il cloud e i moduli. Per altre informazioni, vedere Comprendere e usare moduli gemelli nell'hub IoT.

Usare i tag per individuare i gemelli

Prima di creare una configurazione, è necessario specificare i dispositivi o moduli a cui applicarla. L'hub IoT di Azure identifica i dispositivi, quindi usa i tag nel dispositivo gemello per identificare i moduli usando i tag nel modulo gemello. Ogni dispositivo o modulo può avere più tag ed è possibile definirli in qualsiasi modo che abbia senso per la soluzione. Ad esempio, se si gestiscono i dispositivi in posizioni diverse, aggiungere i tag seguenti a un dispositivo gemello:

"tags": {
	"location": {
		"state": "Washington",
		"city": "Tacoma"
    }
},

Definire il contenuto di destinazione e le metriche

I contenuti di destinazione e le query metriche vengono specificati come documenti JSON che descrivono le proprietà desiderate del dispositivo gemello o del modulo gemello per impostare e segnalare le proprietà da misurare. Per creare una configurazione automatica usando l'interfaccia della riga di comando di Azure, salvare il contenuto di destinazione e le metriche in locale come file di .txt. Quando si esegue il comando per applicare la configurazione al dispositivo, usare i percorsi file in una sezione successiva.

Ecco un esempio di contenuto di destinazione di base per una configurazione automatica del dispositivo:

{
  "content": {
    "deviceContent": {
      "properties.desired.chillerWaterSettings": {
        "temperature": 38,
        "pressure": 78
      }
    }
}

Le configurazioni automatiche dei moduli si comportano in modo molto simile, ma si punta moduleContent invece di deviceContent.

{
  "content": {
    "moduleContent": {
      "properties.desired.chillerWaterSettings": {
        "temperature": 38,
        "pressure": 78
      }
    }
}

Ecco alcuni esempi di query sulle metriche:

{
  "queries": {
    "Compliant": "select deviceId from devices where configurations.[[chillerdevicesettingswashington]].status = 'Applied' AND properties.reported.chillerWaterSettings.status='current'",
    "Error": "select deviceId from devices where configurations.[[chillerdevicesettingswashington]].status = 'Applied' AND properties.reported.chillerWaterSettings.status='error'",
    "Pending": "select deviceId from devices where configurations.[[chillerdevicesettingswashington]].status = 'Applied' AND properties.reported.chillerWaterSettings.status='pending'"
  }
}

Le query metriche per i moduli sono simili anche alle query per i dispositivi, ma si seleziona per moduleId da devices.modules. Ad esempio:

{
  "queries": {
    "Compliant": "select deviceId, moduleId from devices.module where configurations.[[chillermodulesettingswashington]].status = 'Applied' AND properties.reported.chillerWaterSettings.status='current'"
  }
}

Creare una configurazione

È possibile creare un massimo di 100 configurazioni automatiche in hub IoT standard; dieci su hub IoT di livello gratuito. Per altre informazioni, vedere Quote e limitazione.

Per configurare i dispositivi di destinazione si crea una configurazione costituita da contenuto di destinazione e metriche. Usare il comando seguente per creare una configurazione:

   az iot hub configuration create --config-id [configuration id] \
     --labels [labels] --content [file path] --hub-name [hub name] \
     --target-condition [target query] --priority [int] \
     --metrics [metric queries]

  • --config-id: il nome della configurazione che verrà creata nell'hub IoT. Assegnare alla configurazione un nome univoco con un massimo di 128 caratteri. Le lettere minuscole e i caratteri speciali seguenti sono consentiti: -+%_*!'. Gli spazi non sono consentiti.

  • --labels : aggiungere etichette per tenere traccia della configurazione. Le etichette sono coppie nome-valore che descrivono la distribuzione. Ad esempio, HostPlatform, Linux o Version, 3.0.1

  • --content: JSON inline o percorso del file per il contenuto di destinazione da impostare come proprietà desiderate del gemello.

  • --hub-name: nome dell'hub IoT in cui verrà creata la configurazione. L'hub deve trovarsi nella sottoscrizione corrente. Per passare alla sottoscrizione desiderata, usare il comando az account set -s [subscription name].

  • --condizione di destinazione : immettere una condizione di destinazione per determinare quali dispositivi o moduli verranno destinati a questa configurazione. Per la configurazione automatica del dispositivo, la condizione si basa su tag del dispositivo gemello o proprietà desiderate del dispositivo gemello e deve corrispondere al formato dell'espressione. Ad esempio, tags.environment='test' o properties.desired.devicemodel='4000x'. Per la configurazione automatica del modulo, la condizione è basata su tag del modulo gemello o proprietà desiderate del modulo gemello. Ad esempio, from devices.modules where tags.environment='test' o from devices.modules where properties.reported.chillerProperties.model='4000x'.

  • --priority - Intero positivo. Nel caso in cui due o più configurazioni siano destinate allo stesso dispositivo o modulo, la configurazione con il valore numerico più alto per Priorità verrà applicata.

  • --metrics: percorso del file per le query sulle metriche. Le metriche forniscono i conteggi di riepilogo dei diversi stati che un dispositivo o un modulo possono segnalare dopo l'applicazione del contenuto della configurazione. Ad esempio è possibile creare una metrica per le modifiche alle impostazioni in sospeso, una metrica per gli errori e una metrica per le modifiche alle impostazioni con esito positivo.

Monitorare una configurazione

Per visualizzare il contenuto di una configurazione, usare il comando seguente:

az iot hub configuration show --config-id [configuration id] \
  --hub-name [hub name]

  • --config-id: il nome della configurazione che si trova nell'hub IoT.

  • --hub-name: nome dell'hub IoT in cui si trova la configurazione. L'hub deve trovarsi nella sottoscrizione corrente. Per passare alla sottoscrizione desiderata, usare il comando az account set -s [subscription name].

Esaminare la configurazione nella finestra di comando.  La proprietà metrics visualizza un conteggio per ogni metrica valutata da ciascun hub:

  • targetCount: metrica di sistema che specifica il numero di dispositivi gemelli o moduli gemelli in hub IoT che corrispondono alla condizione di destinazione.

  • appliedCount : una metrica di sistema specifica il numero di dispositivi o moduli che hanno applicato il contenuto di destinazione.

  • Metrica personalizzata: qualsiasi metrica definita come metrica utente.

È possibile visualizzare un elenco di ID dispositivo, ID modulo o oggetti per ognuna delle metriche usando il comando seguente:

az iot hub configuration show-metric --config-id [configuration id] \
   --metric-id [metric id] --hub-name [hub name] --metric-type [type]

  • --config-id: nome della distribuzione esistente nell'hub IoT.

  • --metric-id : nome della metrica per cui si vuole visualizzare l'elenco di ID dispositivo o ID modulo, ad esempio appliedCount.

  • --hub-name : nome dell'hub IoT in cui esiste la distribuzione. L'hub deve trovarsi nella sottoscrizione corrente. Per passare alla sottoscrizione desiderata, usare il comando az account set -s [subscription name].

  • --metric-type: il tipo di metrica può essere system o user. Le metriche di sistema sono targetedCount e appliedCount. Tutte le altre metriche sono metriche dell'utente.

Modificare una configurazione

Quando si modifica una configurazione, le modifiche vengono replicate immediatamente in tutti i dispositivi di destinazione.

Se si aggiorna la condizione di destinazione, vengono eseguiti gli aggiornamenti seguenti:

  • Se un gemello non soddisfa la condizione di destinazione precedente, ma soddisfa la nuova condizione di destinazione e questa configurazione ha la priorità più alta per il gemello, viene applicata questa configurazione.

  • Se un gemello che attualmente esegue la configurazione non soddisfa più la condizione di destinazione, verranno rimosse le impostazioni dalla configurazione e il gemello verrà modificato dalla configurazione successiva con la priorità più alta.

  • Se un gemello che attualmente esegue questa configurazione non soddisfa più la condizione di destinazione e non soddisfa la condizione di destinazione delle altre configurazioni, le impostazioni vengono rimosse dalla configurazione e non verranno apportate altre modifiche al gemello.

Per aggiornare una configurazione, usare il comando seguente:

az iot hub configuration update --config-id [configuration id] \
   --hub-name [hub name] --set [property1.property2='value']

  • --config-id: il nome della configurazione che si trova nell'hub IoT.

  • --hub-name: nome dell'hub IoT in cui si trova la configurazione. L'hub deve trovarsi nella sottoscrizione corrente. Per passare alla sottoscrizione desiderata, usare il comando az account set -s [subscription name].

  • --set: aggiornare una proprietà nella configurazione. È possibile aggiornare le proprietà seguenti:

    • targetCondition, ad esempio targetCondition=tags.location.state='Oregon'

    • Etichette

    • priority

Eliminare una configurazione

Quando si elimina una configurazione, qualsiasi dispositivo gemello o modulo gemello assume la successiva configurazione con priorità più alta. Se i gemelli non soddisfano la condizione di destinazione di qualsiasi altra configurazione, non vengono applicate altre impostazioni.

Per eliminare una configurazione, usare il comando seguente:

az iot hub configuration delete --config-id [configuration id] \
   --hub-name [hub name]

  • --config-id: il nome della configurazione che si trova nell'hub IoT.

  • --hub-name: nome dell'hub IoT in cui si trova la configurazione. L'hub deve trovarsi nella sottoscrizione corrente. Per passare alla sottoscrizione desiderata, usare il comando az account set -s [subscription name].

Passaggi successivi

In questo articolo si è appreso come configurare e monitorare i dispositivi IoT su larga scala.

Per informazioni su come gestire le identità dei dispositivi hub IoT in blocco, vedere Importare ed esportare hub IoT identità del dispositivo in blocco