Meer informatie over het implementeren van modules en het vaststellen van routes naar IoT Edge

Van toepassing op: IoT Edge 1.5

Elk IoT Edge-apparaat voert ten minste twee modules uit: $edgeAgent en $edgeHub, die deel uitmaken van de IoT Edge-runtime. Een IoT Edge-apparaat kan meerdere modules uitvoeren voor verschillende processen. Gebruik een implementatiemanifest om uw apparaat te laten weten welke modules moeten worden geïnstalleerd en hoe u deze kunt instellen om samen te werken.

Het implementatiemanifest is een JSON-document waarin het volgende wordt beschreven:

• De IoT Edge-agentmoduledubbel , die drie onderdelen bevat:
  • De containerafbeelding voor elke module die op het apparaat draait
  • De referenties voor het gebruiken van privécontainerregisters met module afbeeldingen
  • Instructies voor het maken en beheren van elke module
• De IoT Edge hub-moduletweeling, inclusief hoe berichten tussen modules en naar de IoT Hub stromen
• De gewenste eigenschappen van optionele extra module-tweelingen

Alle IoT Edge-apparaten hebben een implementatiemanifest nodig. Een zojuist geïnstalleerde IoT Edge-runtime toont een foutcode totdat deze is ingesteld met een geldig manifest.

In de zelfstudies voor Azure IoT Edge bouwt u een implementatiemanifest met behulp van een wizard in de Azure IoT Edge-portal. U kunt ook programmatisch een implementatiemanifest toepassen met behulp van REST of de IoT Hub Service SDK. Zie IoT Edge-implementaties begrijpen voor meer informatie.

Een implementatiemanifest maken

Een implementatiemanifest is een lijst met moduledubbels die zijn ingesteld met de gewenste eigenschappen. Het vertelt een IoT Edge-apparaat of -groep apparaten welke modules moeten worden geïnstalleerd en hoe deze moeten worden ingesteld. Implementatiemanifesten bevatten de gewenste eigenschappen voor elke moduledubbel. IoT Edge-apparaten rapporteren de gerapporteerde eigenschappen voor elke module.

Elk implementatiemanifest vereist twee modules: $edgeAgent en $edgeHub. Deze modules maken deel uit van de IoT Edge-runtime waarmee het IoT Edge-apparaat en de modules die erop worden uitgevoerd, worden beheerd. Zie Inzicht in de IoT Edge-runtime en de bijbehorende architectuur voor meer informatie over deze modules.

U kunt maximaal 50 extra modules toevoegen om te worden uitgevoerd op een IoT Edge-apparaat, naast de twee runtimemodules.

Een implementatiemanifest met alleen de IoT Edge-runtime ($edgeAgent en $edgeHub) is geldig.

Implementatiemanifesten maken gebruik van deze structuur:

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

Modules configureren

Definieer hoe de IoT Edge-runtime de modules in uw implementatie installeert. De IoT Edge-agent is het runtime-onderdeel dat de installatie, updates en statusrapportage voor een IoT Edge-apparaat beheert. De $edgeAgent moduledubbel bevat dus de configuratie- en beheergegevens voor alle modules. Deze informatie bevat de configuratieparameters voor de IoT Edge-agent zelf.

De $edgeAgent eigenschappen volgen deze structuur:

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

Het Schema van de IoT Edge-agent versie 1.1 is uitgebracht met IoT Edge versie 1.0.10 en u kunt de opstartvolgorde van de module instellen. Gebruik schemaversie 1.1 voor elke IoT Edge-implementatie met versie 1.0.10 of hoger.

Moduleconfiguratie en -beheer

In de lijst met gewenste eigenschappen van de IoT Edge-agent definieert u welke modules worden uitgevoerd op een IoT Edge-apparaat en hoe ze worden ingesteld en beheerd.

Zie Eigenschappen van de IoT Edge-agent en De IoT Edge-hub voor een volledige lijst met gewenste eigenschappen die wel of niet moeten worden opgenomen.

Voorbeeld:

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

Elke module heeft een instellingen eigenschap met de moduleafbeelding, een adres voor de containerafbeelding in een containerregister en createOptions om de afbeelding op te zetten bij het opstarten. Zie Opties voor het maken van containers configureren voor IoT Edge-modules voor meer informatie.

De edgeHub-module en aangepaste modules hebben ook drie eigenschappen die de IoT Edge-agent laten weten hoe ze moeten worden beheerd:

• Status: Of de module wordt uitgevoerd of gestopt wanneer de module voor het eerst wordt geïmplementeerd. Vereist.

• RestartPolicy: Wanneer en als de IoT Edge-agent de module opnieuw start als deze stopt. Als de module zonder fouten stopt, wordt deze niet automatisch gestart. Zie Docker Docs - Containers automatisch starten voor meer informatie. Vereist.

• StartupOrder: geïntroduceerd in IoT Edge versie 1.0.10. De volgorde waarin de IoT Edge-agent wordt gebruikt om de modules te starten bij de eerste implementatie. De volgorde maakt gebruik van gehele getallen, waarbij een module met een opstartwaarde van 0 eerst begint en vervolgens hogere getallen volgen. De edgeAgent-module heeft geen opstartwaarde omdat deze altijd eerst wordt gestart. Optioneel.

  De IoT Edge-agent start de modules in de volgorde van de opstartwaarde, maar wacht niet tot elke module is gestart voordat de volgende wordt gestart.

  Opstartvolgorde helpt als sommige modules afhankelijk zijn van andere modules. U wilt bijvoorbeeld dat de edgeHub-module eerst wordt gestart, zodat deze klaar is om berichten te routeren wanneer de andere modules worden gestart. U kunt ook een opslagmodule starten voordat u modules start waarmee gegevens naar deze module worden verzonden. Maar ontwerp altijd uw modules om fouten van andere modules af te handelen. Containers kunnen op elk gewenst moment stoppen en opnieuw opstarten, en elk gewenst aantal keren.

  Notitie

  Als u de eigenschappen van een module wijzigt, wordt die module opnieuw gestart. Er wordt bijvoorbeeld opnieuw opgestart als u eigenschappen voor het volgende wijzigt:

  • module-installatiekopieën
  • Opties voor Docker-maken
  • Omgevingsvariabelen
  • beleid voor opnieuw opstarten
  • pull-beleid voor installatiekopieën
  • Versie
  • opstartvolgorde

  Als er geen module-eigenschappen worden gewijzigd, wordt het opnieuw opstarten van een module niet geactiveerd.

Routes declareren

IoT Edge Hub beheert de communicatie tussen modules, IoT Hub en downstreamapparaten. De $edgeHub module-tweeling heeft een gewenste eigenschap genaamd routes waarmee wordt bepaald hoe berichten zich binnen een implementatie voortbewegen. U kunt meerdere routes instellen in dezelfde implementatie.

Declareer routes in de $edgeHub gewenste eigenschappen met behulp van deze syntaxis.

{
  "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 versie 1 uitgebracht met IoT Edge versie 1.0.10 en hiermee kunt u routeprioriteit en time-to-live instellen. Gebruik schemaversie 1.1 voor elke IoT Edge-implementatie met versie 1.0.10 of hoger.

Elke route heeft een bron nodig voor binnenkomende berichten en een sink voor uitgaande berichten. De voorwaarde is optioneel en u kunt berichten filteren.

Wijs eerst prioriteit toe aan routes om belangrijke berichten te verwerken. Deze functie helpt wanneer de upstream-verbinding zwak of beperkt is en u prioriteit moet geven aan kritieke gegevens boven standaardtelemetrieberichten.

Bron

De bron geeft aan waar de berichten vandaan komen. IoT Edge kan berichten routeren van modules of downstreamapparaten.

Met de IoT SDK's kunnen modules specifieke uitvoerwachtrijen instellen voor hun berichten met behulp van de ModuleClient-klasse. Uitvoerwachtrijen zijn niet vereist, maar ze helpen bij het beheren van meerdere routes. Downstreamapparaten gebruiken de DeviceClient-klasse in de IoT SDK's om berichten te verzenden naar IoT Edge-gatewayapparaten, net zoals ze berichten verzenden naar IoT Hub. Zie Azure IoT Hub SDK's begrijpen en gebruiken voor meer informatie.

De broneigenschap kan een van deze waarden gebruiken:

Conditie

De voorwaarde is optioneel in een routedeclaratie. Als u alle berichten van de bron naar de sink wilt doorgeven, laat u de WHERE-component weg. Of gebruik de Querytaal van IoT Hub om berichten of berichttypen te filteren die voldoen aan de voorwaarde. IoT Edge-routes bieden geen ondersteuning voor het filteren van berichten op basis van dubbeltags of eigenschappen.

Berichten die schakelen tussen modules in IoT Edge gebruiken dezelfde indeling als berichten tussen uw apparaten en Azure IoT Hub. Alle berichten gebruiken de JSON-indeling en hebben systemProperties, appProperties en hoofdtekstparameters .

Bouw query's rond een van de drie parameters met behulp van deze syntaxis:

• Systeemeigenschappen: $<propertyName> of {$<propertyName>}
• Toepassingseigenschappen: <propertyName>
• Hoofdteksteigenschappen: $body.<propertyName>

Voor voorbeelden van het maken van query's voor berichteigenschappen raadpleegt u Query-expressies voor apparaat-naar-cloud-berichten.

U kunt bijvoorbeeld berichten filteren die binnenkomen op een gatewayapparaat vanaf een downstreamapparaat. Berichten die vanuit modules worden verzonden, bevatten een systeemeigenschap genaamd connectionModuleId. Gebruik deze route om berichten van downstreamapparaten rechtstreeks naar IoT Hub te routeren en moduleberichten uit te sluiten:

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

Zinken

De sink definieert waar berichten worden verzonden. Alleen modules en IoT Hub kunnen berichten ontvangen. U kunt geen berichten routeren naar andere apparaten. De sink-eigenschap biedt geen ondersteuning voor jokertekens.

De sink-eigenschap kan een van deze waarden gebruiken:

IoT Edge biedt ten minste eenmaal garanties. IoT Edge-hub slaat berichten lokaal op als een route het bericht niet kan bezorgen aan de sink. Als de IoT Edge-hub bijvoorbeeld geen verbinding kan maken met IoT Hub of als de doelmodule niet is verbonden.

IoT Edge Hub slaat berichten op tot de tijd die is ingesteld in de storeAndForwardConfiguration.timeToLiveSecs eigenschap van de gewenste eigenschappen van de IoT Edge-hub.

Prioriteit en time-to-live

Declareer routes als een tekenreeks die de route definieert, of als een object met een routetekenreeks, een prioriteitsgeheel getal en een time-to-live geheel getal.

Optie 1

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

Optie 2 (geïntroduceerd in IoT Edge versie 1.0.10 met ioT Edge-hubschema versie 1.1)

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

Prioriteitswaarden variëren van 0 tot 9, waarbij 0 de hoogste prioriteit is. Berichten worden bij hun eindpunten in de wachtrij geplaatst. Alle prioriteit 0-berichten voor een specifiek eindpunt worden verwerkt vóór berichten met prioriteit 1 voor hetzelfde eindpunt. Als meerdere routes voor hetzelfde eindpunt dezelfde prioriteit hebben, worden berichten verwerkt in de volgorde waarin ze binnenkomen. Als u geen prioriteit instelt, gebruikt de route de laagste prioriteit.

De eigenschap timeToLiveSecs gebruikt de waarde uit de storeAndForwardConfiguration van de IoT Edge-hub, tenzij u deze rechtstreeks instelt. De waarde kan elk positief geheel getal zijn.

Zie Routeprioriteit en time-to-live voor meer informatie over hoe prioriteitswachtrijen worden beheerd.

Gewenste eigenschappen definiëren of bijwerken

Het implementatiemanifest stelt de gewenste eigenschappen in voor elke module die is geïmplementeerd op het IoT Edge-apparaat. Gewenste eigenschappen in het implementatiemanifest overschrijven alle gewenste eigenschappen die momenteel in de moduledubbel aanwezig zijn.

Als u de gewenste eigenschappen van een moduledubbel niet instelt in het implementatiemanifest, verandert IoT Hub de moduledubbel niet. Stel in plaats daarvan de gewenste eigenschappen programmatisch in.

Met dezelfde mechanismen waarmee u tweelingen van apparaten kunt aanpassen, kunt u ook tweelingen van modules aanpassen. Zie de ontwikkelaarshandleiding voor moduledubbels voor meer informatie.

Voorbeeld van het implementatiemanifest

In het volgende voorbeeld ziet u hoe een geldig implementatiemanifestdocument eruit kan zien.

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

Volgende stappen

• Zie Eigenschappen van de IoT Edge-agent en IoT Edge-hub voor een volledige lijst met eigenschappen die u wel of niet kunt opnemen in $edgeAgent en $edgeHub.

• Nu u weet hoe IoT Edge-modules werken, leert u meer over de vereisten en hulpprogramma's voor het ontwikkelen van IoT Edge-modules.