Informazioni su come distribuire moduli e definire route in IoT Edge

Si applica a: IoT Edge 1.5 IoT Edge 1.4

Ogni dispositivo IoT Edge esegue almeno due moduli: $edgeAgent e $edgeHub, che fanno parte del runtime di IoT Edge. Il dispositivo IoT Edge può eseguire più moduli per un numero qualsiasi di processi. Usare un manifesto della distribuzione per indicare a un dispositivo quali moduli installare e come configurarli perché possano interagire.

Il manifesto della distribuzione è un documento JSON che descrive:

• Il modulo gemello dell'agente IoT Edge, che include tre componenti:
  • Immagine del contenitore per ogni modulo in esecuzione nel dispositivo.
  • Credenziali per accedere ai registri di contenitori privati che contengono immagini del modulo.
  • Istruzioni per la creazione e la gestione di ogni modulo.
• Il modulo gemello dell'agente IoT Edge, che include le modalità di flusso dei messaggi tra i moduli e con l'hub IoT.
• Proprietà desiderate di qualsiasi modulo gemello aggiuntivo (facoltativo).

Tutti i dispositivi IoT Edge devono essere configurati con un manifesto della distribuzione. Un runtime IoT Edge appena installato segnala un codice di errore finché non verrà configurato con un manifesto valido.

Nelle esercitazioni di Azure IoT Edge viene creato un manifesto della distribuzione seguendo una procedura guidata nel portale di Azure IoT Edge. È anche possibile applicare un manifesto della distribuzione a livello di codice usando REST o IoT Hub Service SDK. Per altre informazioni, vedere Informazioni sulle distribuzioni IoT Edge.

Creare un manifesto della distribuzione

A livello generale, un manifesto della distribuzione è un elenco di moduli gemelli configurati con le relative proprietà desiderate. Un manifesto della distribuzione indica a un dispositivo IoT Edge (o a un gruppo di dispositivi) quali moduli installare e come configurarli. I manifesti della distribuzione includono le proprietà desiderate per ogni modulo gemello. I dispositivi IoT Edge riportano le proprietà segnalate per ogni modulo.

In ogni manifesto della distribuzione sono necessari due moduli: $edgeAgent, e $edgeHub. Questi moduli costituiscono parte del runtime di IoT Edge che gestisce il dispositivo IoT Edge e i moduli in esecuzione su di esso. Per altre informazioni su questi moduli, vedere Comprendere il runtime di IoT Edge e la relativa architettura.

Oltre ai due moduli di runtime, è possibile aggiungere fino a 50 moduli personalizzati da eseguire in un dispositivo IoT Edge.

È valido anche un manifesto della distribuzione contenente solo il runtime di IoT Edge (edgeAgent and edgeHub).

I manifesti di distribuzione seguono questa struttura:

{
  "modulesContent": {
    "$edgeAgent": { // required
      "properties.desired": {
        // desired properties of the IoT Edge agent
        // includes the image URIs of all deployed modules
        // includes container registry credentials
      }
    },
    "$edgeHub": { //required
      "properties.desired": {
        // desired properties of the IoT Edge hub
        // includes the routing information between modules, and to IoT Hub
      }
    },
    "module1": {  // optional
      "properties.desired": {
        // desired properties of module1
      }
    },
    "module2": {  // optional
      "properties.desired": {
        // desired properties of module2
      }
    }
  }
}

Configurare moduli

È necessario indicare al runtime di IoT Edge come installare i moduli nella distribuzione. L'agente IoT Edge è il componente di runtime che gestisce l'installazione, gli aggiornamenti e i rapporti di stato di un dispositivo IoT Edge. Le informazioni di configurazione e gestione di tutti i moduli sono quindi disponibili nel modulo gemello $edgeAgent. Nelle informazioni sono inclusi anche i parametri di configurazione dell'agente IoT Edge.

Le proprietà di $edgeAgent seguono questa struttura:

{
  "modulesContent": {
    "$edgeAgent": {
      "properties.desired": {
        "schemaVersion": "1.1",
        "runtime": {
          "settings":{
            "registryCredentials":{
              // give the IoT Edge agent access to container images that aren't public
            }
          }
        },
        "systemModules": {
          "edgeAgent": {
            // configuration and management details
          },
          "edgeHub": {
            // configuration and management details
          }
        },
        "modules": {
          "module1": {
            // configuration and management details
          },
          "module2": {
            // configuration and management details
          }
        }
      }
    },
    "$edgeHub": { ... },
    "module1": { ... },
    "module2": { ... }
  }
}

Lo schema dell'agente IoT Edge versione 1.1 è stato rilasciato insieme a IoT Edge versione 1.0.10 e abilita l'ordine di avvio del modulo. Lo schema versione 1.1 è consigliato per qualsiasi distribuzione di IoT Edge che esegue la versione 1.0.10 o successiva.

Configurazione e gestione dei moduli

L'elenco delle proprietà desiderate dell'agente IoT Edge consente di definire quali moduli vengono distribuiti in un dispositivo IoT Edge e come devono essere configurati e gestiti.

Per un elenco completo delle proprietà desiderate che possono o devono essere incluse, vedere Proprietà dell'agente IoT Edge e dell'hub IoT Edge.

Ad esempio:

{
  "modulesContent": {
    "$edgeAgent": {
      "properties.desired": {
        "schemaVersion": "1.1",
        "runtime": { ... },
        "systemModules": {
          "edgeAgent": { ... },
          "edgeHub": { ... }
        },
        "modules": {
          "module1": {
            "version": "1.0",
            "type": "docker",
            "status": "running",
            "restartPolicy": "always",
            "startupOrder": 2,
            "settings": {
              "image": "myacr.azurecr.io/module1:latest",
              "createOptions": "{}"
            }
          },
          "module2": { ... }
        }
      }
    },
    "$edgeHub": { ... },
    "module1": { ... },
    "module2": { ... }
  }
}

Ogni modulo ha una proprietà settings che contiene l'immagine del modulo, un indirizzo per l'immagine del contenitore in un registro contenitori ed eventuali createOptions per configurare l'immagine all'avvio. Per altre informazioni, vedere Come configurare le opzioni di creazione di contenitori per i moduli IoT Edge.

Il modulo edgeHub e i moduli personalizzati hanno anche tre proprietà che indicano all'agente IoT Edge come gestirli:

• Stato: indica se il modulo deve essere in esecuzione o arrestato quando viene distribuito per la prima volta. Obbligatorio.

• RestartPolicy: quando e se l'agente IoT Edge deve riavviare il modulo se si arresta. Se il modulo viene arrestato senza errori, non verrà avviato automaticamente. Per altre informazioni, vedere Docker Docs - Avviare automaticamente i contenitori. Obbligatorio.

• StartupOrder: introdotto in IoT Edge versione 1.0.10. Quale ordine dell'agente IoT Edge deve avviare i moduli quando viene distribuito per la prima volta. L'ordine viene dichiarato con numeri interi, in cui un modulo dato un valore di avvio pari a 0 viene avviato per primo e quindi i numeri più alti seguono. Il modulo edgeAgent non ha un valore di avvio perché viene sempre avviato per primo. Facoltativo.

  L'agente IoT Edge avvia i moduli in ordine di valore di avvio, ma non attende il completamento di ogni modulo prima di passare a quello successivo.

  L'ordine di avvio è utile se alcuni moduli dipendono da altri. Ad esempio, è possibile che il modulo edgeHub inizi prima in modo che sia pronto per instradare i messaggi all'avvio degli altri moduli. In alternativa, è possibile avviare un modulo di archiviazione prima di avviare i moduli che inviano dati. È tuttavia consigliabile progettare sempre i moduli per gestire gli errori di altri moduli. È la natura dei contenitori che possono arrestare e riavviare in qualsiasi momento e qualsiasi numero di volte.

  Nota

  Le modifiche apportate alle proprietà di un modulo comportano il riavvio del modulo. Ad esempio, si verificherà un riavvio se si modificano le proprietà per :

  • immagine del modulo
  • Opzioni di creazione di Docker
  • variabili di ambiente
  • criteri di riavvio
  • criterio pull immagine
  • versione
  • ordine di avvio

  Se non viene modificata alcuna proprietà del modulo, il modulo non verrà riavviato.

Dichiarare le route

L'hub IoT Edge gestisce la comunicazione tra moduli, hub IoT ed eventuali dispositivi downstream. Pertanto, il modulo gemello $edgeHub contiene una proprietà desiderata chiamata routes che dichiara come i messaggi vengono passati all'interno di una distribuzione. È possibile che nella stessa distribuzione siano presenti più route.

Le route vengono dichiarate nelle proprietà desiderate di $edgeHub con la sintassi seguente:

{
  "modulesContent": {
    "$edgeAgent": { ... },
    "$edgeHub": {
      "properties.desired": {
        "schemaVersion": "1.1",
        "routes": {
          "route1": "FROM <source> WHERE <condition> INTO <sink>",
          "route2": {
            "route": "FROM <source> WHERE <condition> INTO <sink>",
            "priority": 0,
            "timeToLiveSecs": 86400
          }
        },
        "storeAndForwardConfiguration": {
          "timeToLiveSecs": 10
        }
      }
    },
    "module1": { ... },
    "module2": { ... }
  }
}

Lo schema dell'hub IoT Edge versione 1 è stato rilasciato insieme a IoT Edge versione 1.0.10 e abilita la definizione delle priorità e il tempo di esecuzione delle route. Lo schema versione 1.1 è consigliato per qualsiasi distribuzione di IoT Edge che esegue la versione 1.0.10 o successiva.

Ogni route richiede un'origine da cui provengono i messaggi e un sink in cui vengono inviati i messaggi. La condizione è una parte facoltativa che è possibile usare per filtrare i messaggi.

È possibile assegnare priorità alle route che si vuole prima di tutto elaborare i messaggi. Questa funzionalità è utile negli scenari in cui la connessione upstream è debole o limitata e si dispone di dati critici che devono essere classificati in ordine di priorità rispetto ai messaggi di telemetria standard.

Origine

L'origine specifica da dove provengono i messaggi. IoT Edge può instradare i messaggi da moduli o dispositivi downstream.

Con gli SDK IoT, i moduli possono dichiarare code di output specifiche per i messaggi usando la classe ModuleClient. Le code di output non sono necessarie, ma sono utili per la gestione di più route. I dispositivi downstream possono usare la classe DeviceClient degli SDK IoT per inviare messaggi ai dispositivi gateway IoT Edge nello stesso modo in cui inviano messaggi a hub IoT. Per altre informazioni, vedere Comprendere e usare Azure IoT Hub SDK.

La proprietà di origine può essere uno dei valori seguenti:

Condizione

La condizione è facoltativa in una dichiarazione di route. Se si intende passare tutti i messaggi dall'origine al sink, escludere interamente la clausola WHERE. In alternativa è possibile usare il linguaggio di query di hub IoT per filtrare alcuni messaggi o tipi di messaggio che soddisfano la condizione. Le route di IoT Edge non supportano i messaggi di filtro in base a tag o proprietà gemelli.

I messaggi che passano tra i moduli in IoT Edge sono formattati come i messaggi che passano tra i dispositivi e l'hub IoT di Azure. Tutti i messaggi sono formattati come JSON e hanno i parametri systemProperties, appProperties e body.

È possibile compilare query in base a qualunque dei tre parametri con la sintassi seguente:

• Proprietà di sistema: $<propertyName> o {$<propertyName>}
• Proprietà dell'applicazione: <propertyName>
• Proprietà del corpo: $body.<propertyName>

Per esempi su come creare query in base alle proprietà dei messaggi, vedere Espressioni di query per route di messaggi da dispositivo a cloud.

Un esempio specifico di IoT Edge è quando si vuole filtrare i messaggi arrivati a un dispositivo gateway da un dispositivo downstream. I messaggi inviati dai moduli includono una proprietà di sistema denominata connectionModuleId. Pertanto, se si desidera instradare i messaggi dai dispositivi downstream direttamente a hub IoT, usare la route seguente per escludere i messaggi del modulo:

FROM /messages/* WHERE NOT IS_DEFINED($connectionModuleId) INTO $upstream

Sink

Il sink definisce dove vengono inviati i messaggi. Solo i moduli e l'hub IoT possono ricevere messaggi. I messaggi non possono essere indirizzati ad altri dispositivi. Non esistono opzioni con caratteri jolly nella proprietà sink.

La proprietà sink può essere uno dei valori seguenti:

IoT Edge offre garanzie di tipo at-least-once. L'hub di IoT Edge archivia i messaggi in locale nel caso in cui una route non riesca a recapitare il messaggio al relativo sink. Ad esempio, se l'hub di IoT Edge non riesce a connettersi all'hub IoT o il modulo di destinazione non è connesso.

L'hub di IoT Edge archivia i messaggi fino all'ora specificata nella proprietà storeAndForwardConfiguration.timeToLiveSecs delle proprietà desiderate dell'hub di IoT Edge.

Priorità e durata

Le route possono essere dichiarate con solo una stringa che definisce la route o come oggetto che accetta una stringa di route, un numero intero prioritario e un numero intero di durata.

Opzione 1:

"route1": "FROM <source> WHERE <condition> INTO <sink>",

Opzione 2, introdotta in IoT Edge versione 1.0.10 con lo schema dell'hub IoT Edge versione 1.1:

"route2": {
  "route": "FROM <source> WHERE <condition> INTO <sink>",
  "priority": 0,
  "timeToLiveSecs": 86400
}

I valori di priorità possono essere compresi tra 0 e 9, inclusi, dove 0 è la priorità più alta. I messaggi vengono accodati in base ai relativi endpoint. Tutti i messaggi con priorità 0 destinati a un endpoint specifico vengono elaborati prima che vengano elaborati tutti i messaggi con priorità 1 destinati allo stesso endpoint e verso il basso nella riga. Se più route per lo stesso endpoint hanno la stessa priorità, i messaggi vengono elaborati in base alla prima volta. Se non viene specificata alcuna priorità, la route viene assegnata alla priorità più bassa.

La proprietà timeToLiveSecs eredita il valore dall'hub IoT Edge StoreAndForwardConfiguration , a meno che non sia impostato in modo esplicito. Il valore può essere qualsiasi numero intero positivo.

Per informazioni dettagliate sulla modalità di gestione delle code con priorità, vedere la pagina di riferimento relativa alla priorità di route e alla durata.

Definire o aggiornare le proprietà desiderate

Il manifesto di distribuzione specifica le proprietà desiderate per ogni modulo distribuito nel dispositivo IoT Edge. Le proprietà desiderate nel manifesto di distribuzione sovrascrivono le proprietà desiderate attualmente nel modulo gemello.

Se non si specificano le proprietà desiderate di un modulo gemello nel manifesto della distribuzione, hub IoT non modificherà il modulo gemello in alcun modo. In alternativa, è possibile impostare le proprietà desiderate a livello di codice.

Gli stessi meccanismi che consentono di modificare i dispositivi gemelli vengono usati per modificare i moduli gemelli. Per altre informazioni, vedere il modulo per sviluppatori sui dispositivi gemelli.

Esempio di manifesto della distribuzione

L'esempio seguente mostra come viene visualizzato un documento del manifesto di distribuzione valido.

{
  "modulesContent": {
    "$edgeAgent": {
      "properties.desired": {
        "schemaVersion": "1.1",
        "runtime": {
          "type": "docker",
          "settings": {
            "minDockerVersion": "v1.25",
            "loggingOptions": "",
            "registryCredentials": {
              "ContosoRegistry": {
                "username": "myacr",
                "password": "<password>",
                "address": "myacr.azurecr.io"
              }
            }
          }
        },
        "systemModules": {
          "edgeAgent": {
            "type": "docker",
            "settings": {
              "image": "mcr.microsoft.com/azureiotedge-agent:1.5",
              "createOptions": "{}"
            }
          },
          "edgeHub": {
            "type": "docker",
            "status": "running",
            "restartPolicy": "always",
            "startupOrder": 0,
            "settings": {
              "image": "mcr.microsoft.com/azureiotedge-hub:1.5",
              "createOptions": "{\"HostConfig\":{\"PortBindings\":{\"443/tcp\":[{\"HostPort\":\"443\"}],\"5671/tcp\":[{\"HostPort\":\"5671\"}],\"8883/tcp\":[{\"HostPort\":\"8883\"}]}}}"
            }
          }
        },
        "modules": {
          "SimulatedTemperatureSensor": {
            "version": "1.5",
            "type": "docker",
            "status": "running",
            "restartPolicy": "always",
            "startupOrder": 2,
            "settings": {
              "image": "mcr.microsoft.com/azureiotedge-simulated-temperature-sensor:1.5",
              "createOptions": "{}"
            }
          },
          "filtermodule": {
            "version": "1.0",
            "type": "docker",
            "status": "running",
            "restartPolicy": "always",
            "startupOrder": 1,
            "env": {
              "tempLimit": {"value": "100"}
            },
            "settings": {
              "image": "myacr.azurecr.io/filtermodule:latest",
              "createOptions": "{}"
            }
          }
        }
      }
    },
    "$edgeHub": {
      "properties.desired": {
        "schemaVersion": "1.1",
        "routes": {
          "sensorToFilter": {
            "route": "FROM /messages/modules/SimulatedTemperatureSensor/outputs/temperatureOutput INTO BrokeredEndpoint(\"/modules/filtermodule/inputs/input1\")",
            "priority": 0,
            "timeToLiveSecs": 1800
          },
          "filterToIoTHub": {
            "route": "FROM /messages/modules/filtermodule/outputs/output1 INTO $upstream",
            "priority": 1,
            "timeToLiveSecs": 1800
          }
        },
        "storeAndForwardConfiguration": {
          "timeToLiveSecs": 100
        }
      }
    }
  }
}

Passaggi successivi

• Per un elenco completo delle proprietà che possono o devono essere incluse in $edgeAgent e $edgeHub, vedere Proprietà dell'agente di IoT Edge e dell'hub di IoT Edge.

• Dopo aver appreso come usare i moduli IoT Edge, passare alla pagina Informazioni sui requisiti e gli strumenti per sviluppare moduli di IoT Edge.