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 Basic e Standard/Gratuito dell'hub IoT, vedere Scegliere il livello appropriato dell'hub IoT 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 costituito da 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. Gli hub IoT di livello standard supportano un massimo di 100 configurazioni automatiche, gli hub IoT di livello gratuito ne supportano dieci. Si applicano anche limiti della larghezza di banda della rete. Per altre informazioni, vedere Quote e limitazioni.

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 nel modo più appropriato in base alla 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

Il contenuto di destinazione e le query sulle metriche vengono specificati come documenti JSON che descrivono le proprietà desiderate del dispositivo gemello o del modulo gemello da impostare e le proprietà restituite da misurare. Per creare una configurazione automatica usando l'interfaccia della riga di comando di Azure, salvare le metriche e il contenuto di destinazione in locale come file TXT. I percorsi dei file verranno usati in una sezione successiva quando si esegue il comando per applicare la configurazione al dispositivo.

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 del modulo si comportano in modo molto simile, ma è possibile impostare come destinazione moduleContent anziché 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'"
  }
}

Anche le query sulle metriche per i moduli sono simili alle query per i dispositivi, ma occorre selezionare 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 negli hub IoT di livello Standard e dieci negli hub IoT di livello gratuito. Per altre informazioni, vedere Quote e limitazioni.

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 lunghezza fino a 128 caratteri. Sono consentiti i caratteri minuscoli e i caratteri speciali seguenti: -+%_*!'. 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].

  • --target-condition: immettere una condizione di destinazione per determinare i dispositivi o i moduli di destinazione di questa configurazione. Per la configurazione automatica del dispositivo, la condizione è basata sui tag o sulle proprietà desiderate dei dispositivi gemelli 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 sui tag o sulle 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: numero intero positivo. Nel caso in cui due o più configurazioni abbiano lo stesso dispositivo o modulo di destinazione, verrà applicata quella con il valore di priorità più alto.

  • --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:

  • targetedCount: metrica di sistema che specifica il numero di dispositivi o moduli gemelli presenti nell'hub IoT che corrispondono alla condizione di destinazione.

  • appliedCount: metrica di sistema che specifica il numero di dispositivi o moduli a cui è stato 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 tramite 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 visualizzare l'elenco di ID dispositivo, ad esempio appliedCount.

  • --hub-name: nome dell'hub IoT in cui si trova 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, gli eventuali dispositivi o moduli gemelli ricevono la configurazione successiva con la 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 in blocco le identità dei dispositivi dell'hub IoT, vedere Importare ed esportare le identità dei dispositivi dell'hub IoT in blocco