Informazioni su come distribuire moduli e stabilire route in IoT Edge

Applica a: IoT Edge 1.5

Ogni dispositivo IoT Edge esegue almeno due moduli: $edgeAgent e $edgeHub, che fanno parte del runtime di IoT Edge. Un dispositivo IoT Edge può eseguire più moduli per processi diversi. Usare un manifesto di distribuzione per indicare al dispositivo quali moduli installare e come configurarli per collaborare.

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 eseguito nel dispositivo.
  • Credenziali per usare i registri di contenitori privati che contengono immagini del modulo.
  • Istruzioni per la creazione e la gestione di ogni modulo.
• Il modulo gemello IoT Edge hub, che include il flusso dei messaggi tra moduli e IoT Hub.
• Proprietà desiderate di qualsiasi modulo gemello aggiuntivo (facoltativo).

Tutti i dispositivi IoT Edge necessitano di un manifesto della distribuzione. Un runtime di IoT Edge appena installato mostra un codice di errore fino a quando non si configura un manifesto valido.

Nelle esercitazioni Azure IoT Edge si compila un manifesto della distribuzione usando 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 Comprendere le distribuzioni di IoT Edge.

Creare un manifesto della distribuzione

Un manifesto di distribuzione è un elenco di moduli gemelli impostati con le proprietà desiderate. Indica a un dispositivo o a un gruppo di dispositivi IoT Edge quali moduli installare e come configurarli. I manifesti della distribuzione includono le proprietà desiderate per ogni modulo gemello. I dispositivi IoT Edge segnalano le proprietà segnalate per ogni modulo.

Ogni manifesto della distribuzione richiede due moduli: $edgeAgent e $edgeHub. Questi moduli fanno parte del runtime di IoT Edge che gestisce il dispositivo IoT Edge e i moduli in esecuzione. Per altre informazioni su questi moduli, vedere Understand the IoT Edge runtime and its architecture.

È possibile aggiungere fino a 50 moduli aggiuntivi da eseguire in un dispositivo IoT Edge, oltre ai due moduli di runtime.

Un manifesto di distribuzione con solo il runtime di IoT Edge ($edgeAgent e $edgeHub) è valido.

I manifesti della distribuzione usano questo formato:

{
  "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

Definire il modo in cui il runtime di IoT Edge installa i moduli nella distribuzione. L'agente IoT Edge è il componente di runtime che gestisce l'installazione, gli aggiornamenti e la segnalazione dello stato per un dispositivo IoT Edge. $edgeAgent Il modulo gemello ha quindi le informazioni di configurazione e gestione per tutti i moduli. Queste informazioni includono i parametri di configurazione per l'agente IoT Edge stesso.

Le $edgeAgent proprietà usano questo formato:

{
  "modulesContent": {
    "$edgeAgent": {
      "properties.desired": {
        "schemaVersion": "1.1",
        "runtime": {
          "settings":{
            "registryCredentials":{
              // let the IoT Edge agent use 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 con IoT Edge versione 1.0.10 e consente di impostare l'ordine di avvio del modulo. Usare lo schema versione 1.1 per qualsiasi distribuzione IoT Edge che esegue la versione 1.0.10 o successiva.

Configurazione e gestione dei moduli

Definire i moduli eseguiti in un dispositivo IoT Edge e come configurarli e gestirli nell'elenco delle proprietà desiderate dell'agente IoT Edge.

Per un elenco completo delle proprietà desiderate che è possibile includere o che è necessario includere, vedere Properties dell'agente di 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 con l'immagine del modulo, un indirizzo per l'immagine del contenitore in un registro di container ed eventuali createOptions per configurare l'immagine all'avvio. Per altre informazioni, vedere Come configurare le opzioni di creazione del contenitore 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 viene eseguito o arrestato quando viene distribuito per la prima volta. Obbligatorio.

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

• StartupOrder: introdotto in IoT Edge, versione 1.0.10. Ordine usato dall'agente di IoT Edge per avviare i moduli al momento della prima distribuzione. L'ordine usa numeri interi, in cui un modulo con un valore di avvio pari a 0 inizia per primo e quindi segue numeri più alti. 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 iniziare quello successivo.

  L'ordine di avvio aiuta se alcuni moduli dipendono da altri. Ad esempio, è possibile che il modulo edgeHub venga avviato per primo 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. Ma progettare sempre i moduli per gestire gli errori di altri moduli. I contenitori possono fermarsi e riavviarsi in qualsiasi momento e qualsiasi numero di volte.

  Nota

  La modifica delle proprietà di un modulo riavvia quel modulo. Ad esempio, un riavvio si verifica se si modificano le proprietà per :

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

  Se non si modificano le proprietà del modulo, non viene attivato un riavvio del modulo.

Dichiarare le route

IoT Edge hub gestisce la comunicazione tra moduli, IoT Hub e dispositivi downstream. Il modulo gemello $edgeHub ha una proprietà desiderata denominata routes che definisce il modo in cui i messaggi vengono spostati all'interno di una distribuzione. È possibile configurare più rotte nella stessa distribuzione.

Dichiarare le route nelle proprietà desiderate di $edgeHub utilizzando questa sintassi:

{
  "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": { ... }
  }
}

IoT Edge hub schema versione 1 rilasciata con IoT Edge versione 1.0.10 e consente di impostare la priorità di instradamento e il tempo di vita. Usare lo schema versione 1.1 per qualsiasi distribuzione IoT Edge che esegue la versione 1.0.10 o successiva.

Ogni route richiede un'origine per i messaggi in arrivo e un sink per i messaggi in uscita. La condizione è facoltativa e consente di filtrare i messaggi.

Assegna priorità alle rotte per elaborare prima i messaggi importanti. Questa funzionalità consente quando la connessione upstream è debole o limitata ed è necessario assegnare priorità ai dati critici sui messaggi di telemetria standard.

Origine

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

Usando gli SDK IoT, i moduli possono impostare code di output specifiche per i messaggi usando la ModuleClient classe . Le code di output non sono necessarie, ma consentono di gestire più percorsi. I dispositivi downstream usano la classe DeviceClient negli SDK IoT per inviare messaggi ai dispositivi gateway IoT Edge, proprio come inviano messaggi a IoT Hub. Per ulteriori informazioni, consultare Comprendere e utilizzare gli SDK di Azure IoT Hub.

La proprietà di origine può usare uno di questi valori:

Condizione

La condizione è facoltativa in una dichiarazione di route. Per passare tutti i messaggi dall'origine al sink, omettere la clausola WHERE . In alternativa, usare il linguaggio di query IoT Hub per filtrare i messaggi o i tipi di messaggio che soddisfano la condizione. IoT Edge route non supportano il filtro dei messaggi in base a tag o proprietà gemelli.

I messaggi che si spostano tra moduli in IoT Edge usano lo stesso formato dei messaggi tra i dispositivi e Azure IoT Hub. Tutti i messaggi usano il formato JSON e hanno parametri systemProperties, appProperties e body .

Compilare query su uno dei tre parametri usando questa sintassi:

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

Per esempi su come creare query per le proprietà dei messaggi, vedere Espressioni di query dei percorsi dei messaggi da dispositivo a cloud.

Ad esempio, è possibile filtrare i messaggi che arrivano a un dispositivo gateway da un dispositivo downstream. I messaggi inviati dai moduli includono una proprietà di sistema denominata connectionModuleId. Per instradare i messaggi dai dispositivi downstream direttamente a IoT Hub ed escludere i messaggi del modulo, usare questa route:

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

Lavandino

Il sink definisce dove inviare messaggi. Solo i moduli e IoT Hub possono ricevere messaggi. Non è possibile instradare i messaggi ad altri dispositivi. La proprietà sink non supporta i caratteri jolly.

La proprietà sink può usare uno di questi valori:

IoT Edge fornisce almeno una volta garanzie. IoT Edge hub archivia i messaggi localmente se una route non è in grado di recapitare il messaggio al sink. Ad esempio, se IoT Edge hub non riesce a connettersi a IoT Hub o il modulo di destinazione non è connesso.

IoT Edge hub archivia i messaggi fino al tempo impostato nella proprietà storeAndForwardConfiguration.timeToLiveSecs delle proprietà desiderate dell'hub IoT Edge.

Priorità e tempo di vita

Dichiarate le rotte come una stringa che definisce il percorso, oppure come un oggetto contenente una stringa del percorso, un numero intero per la priorità e un numero intero per il tempo di vita.

Opzione 1

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

Opzione 2 (introdotta in IoT Edge versione 1.0.10 con schema hub IoT Edge versione 1.1)

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

I valori di priorità sono compresi tra 0 e 9, dove 0 è la priorità più alta. Il sistema accoda i messaggi in base ai relativi endpoint. Il sistema elabora tutti i messaggi con priorità 0 per un endpoint specifico prima di elaborare qualsiasi messaggio di priorità 1 per lo stesso endpoint. Se più route per lo stesso endpoint hanno la stessa priorità, il sistema elabora i messaggi nell'ordine in cui arrivano. Se non si imposta una priorità, la route usa la priorità più bassa.

La proprietà timeToLiveSecs utilizza il valore della storeAndForwardConfiguration dell'hub IoT Edge, a meno che non venga impostato direttamente. Il valore può essere qualsiasi numero intero positivo.

Per informazioni dettagliate sulla gestione delle code con priorità, vedere Priorità e tempo di vita.

Definire o aggiornare le proprietà desiderate

Il manifesto della distribuzione imposta 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 impostano le proprietà desiderate di un modulo gemello nel manifesto della distribuzione, IoT Hub non modifica il modulo gemello. Impostare invece le proprietà desiderate a livello di codice.

Gli stessi meccanismi che consentono di modificare i dispositivi gemelli consentono anche di 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 può o deve includere in $edgeAgent e $edgeHub, vedere Proprietà dell'agente IoT Edge e dell'hub IoT Edge.
• Ora che si conosce il funzionamento dei moduli IoT Edge, informazioni sui requisiti e sugli strumenti per lo sviluppo di moduli IoT Edge.