Informazioni su come distribuire moduli e definire route in IoT Edge

Si applica a: 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 l'uso di registri contenitori privati con immagini del modulo
  • Istruzioni per la creazione e la gestione di ogni modulo
• Il modulo gemello dell'hub IoT Edge , che include il flusso dei messaggi tra i moduli e l'hub IoT
• 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 viene configurato con un manifesto valido.

Nelle esercitazioni su Azure IoT Edge si crea 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 L'SDK del servizio dell'hub IoT. Per altre informazioni, vedere Informazioni sulle distribuzioni 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 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.

È 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 di distribuzione usano 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. Il modulo gemello $edgeAgent dispone quindi delle informazioni di configurazione e gestione per tutti i moduli. 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":{
              // 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 1.1 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 eseguiti in un dispositivo IoT Edge e come vengono 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 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 opzioni di creazione di contenitori per 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 avviato automaticamente. Per altre informazioni, vedere Docker Docs - Avviare automaticamente i contenitori. Obbligatorio.

• StartupOrder: introdotto in IoT Edge versione 1.0.10. L'ordine usato dall'agente di IoT Edge per avviare i moduli quando viene distribuito per la prima volta. 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 di 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 pull immagine
  • versione
  • ordine di avvio

  Se non vengono modificate proprietà del modulo, non viene attivato un riavvio del modulo.

Dichiarare le route

L'hub IoT Edge gestisce la comunicazione tra moduli, hub IoT e dispositivi downstream. Il modulo gemello $edgeHub ha una proprietà desiderata denominata route 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": { ... }
  }
}

La versione 1 dello schema dell'hub IoT Edge è stata rilasciata con IoT Edge versione 1.0.10 e consente di impostare la definizione delle priorità di route e la durata di vita. Usare lo schema 1.1 per qualsiasi distribuzione di 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.

Con gli SDK IoT, i moduli possono impostare code di output specifiche per i messaggi usando la classe ModuleClient. 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 all'hub IoT. Per altre informazioni, vedere Comprendere e usare Azure IoT Hub SDK.

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, escludere la clausola WHERE . In alternativa, usare il linguaggio di query dell'hub IoT per filtrare i messaggi o i 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 si spostano tra moduli in IoT Edge usano lo stesso formato dei messaggi tra i dispositivi e l'hub IoT di Azure. 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 all'hub IoT ed escludere i messaggi del modulo, usare questa route:

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

Lavandino

Il sink definisce la posizione in cui vengono inviati i messaggi. Solo i moduli e l'hub IoT 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 offre almeno una volta garanzie. L'hub IoT Edge memorizza localmente i messaggi se un percorso non riesce a consegnare il messaggio alla destinazione. Ad esempio, se l'hub IoT Edge non riesce a connettersi all'hub IoT o il modulo di destinazione non è connesso.

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

Priorità e durata

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 dell'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. I messaggi vengono accodati dagli endpoint a cui appartengono. Tutti i messaggi di priorità 0 per un endpoint specifico vengono elaborati prima di qualsiasi messaggio di priorità 1 per lo stesso endpoint. Se più route per lo stesso endpoint hanno la stessa priorità, i messaggi vengono elaborati 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 sia impostata direttamente. Il valore può essere qualsiasi numero intero positivo.

Per informazioni dettagliate sulla modalità di gestione delle code con priorità, vedere Priorità di route e durata.For details about how priority queues are managed, see Route priority and time-to-live.

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, l'hub IoT 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 l'aspetto di un documento manifesto della 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 è possibile 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, vedere i requisiti e gli strumenti per lo sviluppo di moduli IoT Edge.