Distribuire e monitorare i moduli di IoT Edge su larga scala tramite l'interfaccia della riga di comando di Azure

Si applica a: IoT Edge 1.5

Importante

IoT Edge 1.5 LTS è la versione supportata. IoT Edge 1.4 LTS è di fine vita a partire dal 12 novembre 2024. Se si usa una versione precedente, vedere Aggiornare IoT Edge.

Usare l'interfaccia della riga di comando di Azure per creare una distribuzione automatica di Azure IoT Edge e gestire le distribuzioni per più dispositivi contemporaneamente. Le distribuzioni automatiche per IoT Edge rientrano nella funzionalità di gestione dei dispositivi dell'hub IoT di Azure. Le distribuzioni consentono di distribuire più moduli in più dispositivi, tenere traccia dello stato e dell'integrità dei moduli e apportare modifiche quando necessario.

In questo articolo vengono configurate l'interfaccia della riga di comando di Azure e l'estensione IoT. Distribuire quindi i moduli in un set di dispositivi IoT Edge e monitorare lo stato di avanzamento usando i comandi dell'interfaccia della riga di comando.

Prerequisiti

• Un hub IoT nella sottoscrizione di Azure.

• Uno o più dispositivi IoT Edge.

  Se non si dispone di un dispositivo IoT Edge configurato, è possibile crearne uno in una macchina virtuale di Azure. Seguire la procedura descritta in uno di questi argomenti di avvio rapido: Creare un dispositivo Linux virtuale o Creare un dispositivo Windows virtuale.

• Interfaccia della riga di comando di Azure nell'ambiente in uso. La versione dell'interfaccia della riga di comando di Azure deve essere 2.0.70 o successiva. Usare az --version per controllare. Questa versione supporta i comandi dell'estensione az e introduce il framework dei comandi Knack.

• Estensione IoT per l'interfaccia della riga di comando di Azure.

Configurare un manifesto della distribuzione

Un manifesto della distribuzione è un documento JSON che descrive i moduli da distribuire, il flusso dei dati tra i moduli e le proprietà desiderate dei moduli gemelli. Per altre informazioni, vedere Informazioni su come distribuire moduli e definire route in IoT Edge.

Per distribuire i moduli tramite l'interfaccia della riga di comando di Azure, salvare il manifesto della distribuzione in locale come file con estensione .txt. Il percorso del file verrà usato nella sezione successiva quando si esegue il comando per applicare la configurazione al dispositivo.

Ecco un manifesto di distribuzione di base con un modulo come esempio.

{
  "content": {
    "modulesContent": {
      "$edgeAgent": {
        "properties.desired": {
          "schemaVersion": "1.1",
          "runtime": {
            "type": "docker",
            "settings": {
              "minDockerVersion": "v1.25",
              "loggingOptions": "",
              "registryCredentials": {}
            }
          },
          "systemModules": {
            "edgeAgent": {
              "type": "docker",
              "settings": {
                "image": "mcr.microsoft.com/azureiotedge-agent:1.5",
                "createOptions": "{}"
              }
            },
            "edgeHub": {
              "type": "docker",
              "status": "running",
              "restartPolicy": "always",
              "settings": {
                "image": "mcr.microsoft.com/azureiotedge-hub:1.5",
                "createOptions": "{\"HostConfig\":{\"PortBindings\":{\"5671/tcp\":[{\"HostPort\":\"5671\"}],\"8883/tcp\":[{\"HostPort\":\"8883\"}],\"443/tcp\":[{\"HostPort\":\"443\"}]}}}"
              }
            }
          },
          "modules": {
            "SimulatedTemperatureSensor": {
              "version": "1.5",
              "type": "docker",
              "status": "running",
              "restartPolicy": "always",
              "settings": {
                "image": "mcr.microsoft.com/azureiotedge-simulated-temperature-sensor:1.5",
                "createOptions": "{}"
              }
            }
          }
        }
      },
      "$edgeHub": {
        "properties.desired": {
          "schemaVersion": "1.1",
          "routes": {
            "upstream": "FROM /messages/* INTO $upstream"
          },
          "storeAndForwardConfiguration": {
            "timeToLiveSecs": 7200
          }
        }
      },
      "SimulatedTemperatureSensor": {
        "properties.desired": {
          "SendData": true,
          "SendInterval": 5
        }
      }
    }
  }
}

Nota

Questo manifesto della distribuzione di esempio usa la versione dello schema 1.1 per l'agente e l'hub di IoT Edge. La versione dello schema 1.1 viene rilasciata insieme a IoT Edge versione 1.0.10. Consente di usare funzionalità come l'ordine di avvio del modulo e la definizione delle priorità di route.

Distribuzione a livelli

Le distribuzioni a più livelli sono un tipo di distribuzione automatica che è possibile impilare l'una sull'altra. Per altre informazioni sulle distribuzioni a livelli, vedere Informazioni sulle distribuzioni automatiche di IoT Edge per singoli dispositivi o su vasta scala.

È possibile creare e gestire distribuzioni a più livelli con l'interfaccia della riga di comando di Azure come qualsiasi distribuzione automatica, con poche differenze. Dopo aver creato una distribuzione a più livelli, l'interfaccia della riga di comando di Azure funziona per le distribuzioni a più livelli come per qualsiasi distribuzione. Per creare una distribuzione a livelli, aggiungere il flag --layered al comando Crea.

La seconda differenza consiste nel modo in cui si costruisce il manifesto della distribuzione. Le distribuzioni automatiche standard devono includere i moduli di runtime di sistema e tutti i moduli utente. Le distribuzioni a più livelli possono includere solo i moduli utente. Le distribuzioni a livelli richiedono inoltre una distribuzione automatica standard in un dispositivo, per fornire i componenti necessari di ogni dispositivo IoT Edge, come i moduli di runtime di sistema.

Ecco un manifesto di distribuzione a più livelli di base con un modulo come esempio.

{
  "content": {
    "modulesContent": {
      "$edgeAgent": {
        "properties.desired.modules.SimulatedTemperatureSensor": {
          "settings": {
            "image": "mcr.microsoft.com/azureiotedge-simulated-temperature-sensor:1.5",
              "createOptions": "{}"
          },
          "type": "docker",
          "status": "running",
          "restartPolicy": "always",
          "version": "1.5"
        }
      },
      "$edgeHub": {
        "properties.desired.routes.upstream": "FROM /messages/* INTO $upstream"
      },
      "SimulatedTemperatureSensor": {
        "properties.desired": {
          "SendData": true,
          "SendInterval": 5
        }
      }
    }
  }
}

Nota

Questo manifesto della distribuzione a livelli ha un formato leggermente diverso rispetto a un manifesto della distribuzione standard. Le proprietà desiderate dei moduli di runtime sono compresse e usano la notazione con il punto. Questa formattazione è necessaria per il portale di Azure per riconoscere una distribuzione a livelli. Ad esempio:

• properties.desired.modules.<module_name>
• properties.desired.routes.<route_name>

L'esempio precedente mostra l'impostazione properties.desired di distribuzione a più livelli per un modulo. Se questa distribuzione a più livelli è destinata a un dispositivo in cui è già applicato lo stesso modulo, sovrascrive le proprietà desiderate esistenti. Per aggiornare le proprietà desiderate anziché sovrascriverle, definire una nuova sottosezione. Ad esempio:

"SimulatedTemperatureSensor": {
  "properties.desired.layeredProperties": {
    "SendData": true,
    "SendInterval": 5
  }
}

È anche possibile esprimere lo stesso con la sintassi seguente:

"SimulatedTemperatureSensor": {
  "properties.desired.layeredProperties.SendData" : true,
  "properties.desired.layeredProperties.SendInterval": 5
}

Nota

Attualmente, tutte le distribuzioni a più livelli devono includere un edgeAgent oggetto per essere valido. Anche se una distribuzione a livelli aggiorna solo le proprietà del modulo, includere un oggetto vuoto. Ad esempio: "$edgeAgent":{}. Una distribuzione a più livelli con un oggetto vuoto edgeAgent viene visualizzata come destinazione nel edgeAgent modulo gemello, non applicata.

Per creare una distribuzione a più livelli:

• Aggiungere il flag --layered al comando di creazione dell'interfaccia della riga di comando di Azure.
• Non includere moduli di sistema.
• Usare la notazione con il punto completa in $edgeAgent e $edgeHub.

Per altre informazioni sulla configurazione di moduli gemelli nelle distribuzioni a livelli, vedere Distribuzioni a livelli.

Identificare i dispositivi tramite tag

Prima di creare una distribuzione, è necessario specificare i dispositivi che desideri influenzare. Azure IoT Edge identifica i dispositivi tramite tag nel dispositivo gemello.

Ogni dispositivo può avere più tag, che è possibile definire in qualsiasi modo risulti appropriato per una soluzione specifica. Ad esempio, se si gestisce un campus di edifici intelligenti, è possibile aggiungere i tag seguenti a un dispositivo:

"tags":{
  "location":{
    "building": "20",
    "floor": "2"
  },
  "roomtype": "conference",
  "environment": "prod"
}

Per altre informazioni sui dispositivi gemelli e i tag, vedere Comprendere e usare dispositivi gemelli nell'hub IoT.

Creare una distribuzione

Distribuire moduli nei dispositivi di destinazione creando una distribuzione con il manifesto della distribuzione e altri parametri.

Eseguire il comando az iot edge deployment create per creare una distribuzione:

az iot edge deployment create --deployment-id <deployment-id> --hub-name <hub-name> --content <file-path> --labels "<labels>" --target-condition "<target-query>" --priority <priority>

Aggiungere il --layered flag per creare una distribuzione a più livelli.

Il az iot edge deployment create comando usa i parametri seguenti:

• --layered: flag facoltativo che identifica la distribuzione come distribuzione a più livelli.
• --deployment-id: nome della distribuzione creata nell'hub IoT. Usare un nome univoco con un massimo di 128 lettere minuscole. Evitare spazi e questi caratteri non validi: & ^ [ ] { } \ | " < > /. Questo parametro è obbligatorio.
• --content: percorso del file nel file JSON del manifesto della distribuzione. Questo parametro è obbligatorio.
• --hub-name: nome dell'hub IoT in cui viene creata la distribuzione. L'hub deve trovarsi nella sottoscrizione corrente. Modificare la sottoscrizione corrente eseguendo az account set -s <subscription-name>.
• --labels: coppie nome/valore che descrivono e consentono di tenere traccia delle distribuzioni. Le etichette usano la formattazione JSON per nomi e valori. Ad esempio: {"HostPlatform":"Linux", "Version":"3.0.1"}.
• --target-condition: condizione che determina quali dispositivi sono destinati a questa distribuzione. La condizione è basata sui tag o sulle proprietà segnalate dei dispositivi gemelli e deve corrispondere al formato di espressione. Ad esempio: tags.environment='test' and properties.reported.devicemodel='4000x'. Se non si specifica la condizione di destinazione, la distribuzione non viene applicata ad alcun dispositivo.
• --priority: Numero intero positivo. Se due o più distribuzioni hanno come destinazione lo stesso dispositivo, viene applicata la distribuzione con la priorità più alta.
• --metrics: metriche che eseguono query sulle edgeHub proprietà segnalate per tenere traccia dello stato di una distribuzione. Le metriche usano l'input JSON o un percorso di file. Ad esempio: '{"queries": {"mymetric": "SELECT deviceId FROM devices WHERE properties.reported.lastDesiredStatus.code = 200"}}'.

Per monitorare una distribuzione con l'interfaccia della riga di comando di Azure, vedere Monitorare le distribuzioni di IoT Edge.

Nota

Quando si crea una nuova distribuzione di IoT Edge, possono essere necessari fino a 5 minuti prima che l'hub IoT elabori la nuova configurazione e invii le nuove proprietà desiderate ai dispositivi di destinazione.

Modificare una distribuzione

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

Se si aggiorna la condizione di destinazione, si verificano le modifiche seguenti:

• Se un dispositivo non soddisfa la condizione di destinazione precedente ma soddisfa la nuova condizione di destinazione e questa distribuzione è la priorità più alta per il dispositivo, questa distribuzione viene applicata al dispositivo.
• Se un dispositivo attualmente in esecuzione questa distribuzione non soddisfa più la condizione di destinazione, disinstalla questa distribuzione e assume la successiva distribuzione con priorità più alta .
• Se un dispositivo attualmente in esecuzione questa distribuzione non soddisfa più la condizione di destinazione e non soddisfa la condizione di destinazione di nessun'altra distribuzione, non viene apportata alcuna modifica nel dispositivo. Il dispositivo continua a eseguire i moduli attuali nello stato attuale, ma non è più gestito come parte di questa distribuzione. Dopo che il dispositivo soddisfa la condizione di destinazione di un'altra distribuzione, disinstalla questa distribuzione e assume quella nuova.

Non è possibile aggiornare il contenuto di una distribuzione, che include i moduli e le route definiti nel manifesto della distribuzione. Per aggiornare il contenuto di una distribuzione, creare una nuova distribuzione destinata agli stessi dispositivi con priorità più alta. È possibile modificare determinate proprietà di un modulo esistente, tra cui la condizione di destinazione, le etichette, le metriche e la priorità.

Per aggiornare una distribuzione, usare il comando az iot edge deployment update:

az iot edge deployment update --deployment-id <deployment-id> --hub-name <hub-name> --set <property1.property2='value'>

Il comando deployment update usa i parametri seguenti:

• --deployment-id: nome della distribuzione nell'hub IoT.
• --hub-name: nome dell'hub IoT in cui è presente la distribuzione. L'hub deve trovarsi nella sottoscrizione corrente. Per passare a un'altra sottoscrizione, eseguire az account set -s <subscription-name>.
• --set: modificare una proprietà nella distribuzione. È possibile modificare le proprietà seguenti:
  • targetCondition (ad esempio, targetCondition=tags.location.state='Oregon')
  • labels
  • priority
• --add: Aggiungi una nuova proprietà all'implementazione, incluse le condizioni o le etichette di destinazione.
• --remove: rimuovere una proprietà esistente, incluse le condizioni di destinazione o le etichette.

Eliminare una distribuzione

Quando si elimina una distribuzione, i dispositivi usano la successiva distribuzione con priorità più alta. Se i dispositivi non soddisfano la condizione di destinazione di un'altra distribuzione, i moduli non vengono rimossi quando si elimina la distribuzione.

Eseguire il comando az iot edge deployment delete per eliminare una distribuzione:

az iot edge deployment delete --deployment-id <deployment-id> --hub-name <hub-name>

Il deployment delete comando usa i parametri seguenti:

• --deployment-id. Nome della distribuzione esistente nell'hub IoT.
• --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].

Passaggi successivi

Leggere altre informazioni sulla distribuzione di moduli nei dispositivi IoT Edge.