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

  • Artikel

Van toepassing op:IoT Edge 1.4 checkmark IoT Edge 1.4

Belangrijk

IoT Edge 1.4 is de ondersteunde release. Raadpleeg IoT Edge bijwerken als u een eerdere versie hebt.

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

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

  • De IoT Edge-agentmoduledubbel , die drie onderdelen bevat:
    • De containerinstallatiekopieën voor elke module die op het apparaat wordt uitgevoerd.
    • De referenties voor toegang tot privécontainerregisters die module-installatiekopieën bevatten.
    • Instructies voor het maken en beheren van elke module.
  • De IoT Edge Hub-moduledubbel , waaronder de manier waarop berichten tussen modules stromen en uiteindelijk naar IoT Hub.
  • De gewenste eigenschappen van extra moduledubbels (optioneel).

Alle IoT Edge-apparaten moeten worden geconfigureerd met een implementatiemanifest. Een nieuw geïnstalleerde IoT Edge-runtime rapporteert een foutcode totdat deze is geconfigureerd met een geldig manifest.

In de zelfstudies voor Azure IoT Edge bouwt u een implementatiemanifest door een wizard te doorlopen 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

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

Er zijn twee modules vereist in elk implementatiemanifest: $edgeAgenten $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.

Naast de twee runtimemodules kunt u maximaal 50 modules toevoegen die u zelf kunt uitvoeren op een IoT Edge-apparaat.

Een implementatiemanifest dat alleen de IoT Edge-runtime (edgeAgent en edgeHub) bevat, is geldig.

Implementatiemanifesten volgen 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. Daarom bevat de $edgeAgent moduledubbel 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":{
              // 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": { ... }
  }
}

Het Schema van de IoT Edge-agent versie 1.1 is uitgebracht samen met IoT Edge versie 1.0.10 en schakelt de opstartvolgorde van de module in. Schemaversie 1.1 wordt aanbevolen 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 geïmplementeerd op een IoT Edge-apparaat en hoe deze moeten worden geconfigureerd 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.

Bijvoorbeeld:

{
  "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 instellingseigenschap die de module-installatiekopieën bevat, een adres voor de containerinstallatiekopieën in een containerregister en createOptions om de installatiekopieën bij het opstarten te configureren. 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 moet worden uitgevoerd of gestopt wanneer de module voor het eerst wordt geïmplementeerd. Vereist.

  • RestartPolicy: Wanneer en als de IoT Edge-agent de module opnieuw moet starten als deze stopt. Als de module zonder fouten wordt gestopt, 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. In welke volgorde de IoT Edge-agent moet worden gestart wanneer de modules voor het eerst worden geïmplementeerd. De volgorde wordt gedeclareerd met gehele getallen, waarbij een module met een opstartwaarde van 0 eerst wordt gestart en vervolgens hogere getallen volgen. De edgeAgent-module heeft geen opstartwaarde omdat deze altijd eerst wordt gestart. Optioneel.

    De IoT Edge-agent initieert de modules in de volgorde van de opstartwaarde, maar wacht niet tot elke module is voltooid voordat u naar de volgende module gaat.

    Opstartvolgorde is handig als sommige modules afhankelijk zijn van andere. 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 die gegevens naar deze module verzenden. U moet echter altijd uw modules ontwerpen om fouten van andere modules af te handelen. Het is de aard van containers die ze op elk gewenst moment kunnen stoppen en opnieuw kunnen starten, en een willekeurig aantal keren.

    Notitie

    Wijzigingen in de eigenschappen van een module resulteren in het opnieuw opstarten van die module. Er wordt bijvoorbeeld opnieuw opgestart als u de eigenschappen voor het volgende wijzigt:

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

    Als er geen module-eigenschap wordt gewijzigd, wordt de module niet opnieuw opgestart.

Routes declareren

De IoT Edge-hub beheert de communicatie tussen modules, IoT Hub en eventuele downstreamapparaten. Daarom bevat de $edgeHub moduledubbel een gewenste eigenschap met de naam routes die aangeven hoe berichten binnen een implementatie worden doorgegeven. U kunt meerdere routes binnen dezelfde implementatie hebben.

Routes worden gedeclareerd in de $edgeHub gewenste eigenschappen met de volgende 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": { ... }
  }
}

Het IoT Edge-hubschema versie 1 is uitgebracht samen met IoT Edge versie 1.0.10 en maakt route-prioriteitstelling en time to live mogelijk. Schemaversie 1.1 wordt aanbevolen voor elke IoT Edge-implementatie met versie 1.0.10 of hoger.

Elke route heeft een bron nodig waar de berichten vandaan komen en een sink waar de berichten naartoe gaan. De voorwaarde is een optioneel onderdeel dat u kunt gebruiken om berichten te filteren.

U kunt prioriteit toewijzen aan routes die u ervoor wilt zorgen dat hun berichten eerst worden verwerkt. Deze functie is handig in scenario's waarin de upstream-verbinding zwak of beperkt is en u kritieke gegevens hebt die prioriteit moeten krijgen boven standaardtelemetrieberichten.

Source

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 declareren voor hun berichten met behulp van de ModuleClient-klasse. Uitvoerwachtrijen zijn niet nodig, maar zijn handig voor het beheren van meerdere routes. Downstreamapparaten kunnen de DeviceClient-klasse van de IoT-SDK's gebruiken om berichten te verzenden naar IoT Edge-gatewayapparaten op dezelfde manier als ze berichten naar IoT Hub zouden verzenden. Zie Azure IoT Hub SDK's begrijpen en gebruiken voor meer informatie.

De broneigenschap kan een van de volgende waarden zijn:

Source Omschrijving
/* Alle apparaat-naar-cloud-berichten of meldingen van dubbels wijzigen van een module of downstreamapparaat
/twinChangeNotifications Elke wijziging van dubbels (gerapporteerde eigenschappen) die afkomstig zijn van een module of downstreamapparaat
/messages/* Elk apparaat-naar-cloudbericht dat door een module wordt verzonden via een bepaalde of geen uitvoer, of door een downstreamapparaat
/messages/modules/* Elk apparaat-naar-cloud-bericht dat door een module wordt verzonden via een deel of geen uitvoer
/messages/modules/<moduleId>/* Elk apparaat-naar-cloud-bericht dat door een specifieke module wordt verzonden via een bepaalde of geen uitvoer
/messages/modules/<moduleId>/outputs/* Elk apparaat-naar-cloud-bericht dat door een specifieke module wordt verzonden via een bepaalde uitvoer
/messages/modules/<moduleId>/outputs/<output> Elk apparaat-naar-cloud-bericht dat door een specifieke module wordt verzonden via een specifieke uitvoer

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 helemaal weg. U kunt ook de IoT Hub-querytaal gebruiken om te filteren op bepaalde berichten of berichttypen die voldoen aan de voorwaarde. IoT Edge-routes bieden geen ondersteuning voor het filteren van berichten op basis van dubbeltags of eigenschappen.

De berichten die worden doorgegeven tussen modules in IoT Edge, zijn hetzelfde opgemaakt als de berichten die worden doorgegeven tussen uw apparaten en Azure IoT Hub. Alle berichten zijn opgemaakt als JSON en hebben systemProperties, appProperties en hoofdtekstparameters .

U kunt query's maken rond een van de drie parameters met de volgende syntaxis:

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

Zie Query-expressies voor apparaat-naar-cloud-berichten om voorbeelden te maken van query-expressies voor berichteigenschappen.

Een voorbeeld dat specifiek is voor IoT Edge, is wanneer u wilt filteren op berichten die zijn aangekomen op een gatewayapparaat vanaf een downstreamapparaat. Berichten die vanuit modules worden verzonden, bevatten een systeemeigenschap genaamd connectionModuleId. Dus als u berichten van downstreamapparaten rechtstreeks naar IoT Hub wilt routeren, gebruikt u de volgende route om moduleberichten uit te sluiten:

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

Sink

De sink definieert waar de berichten worden verzonden. Alleen modules en IoT Hub kunnen berichten ontvangen. Berichten kunnen niet worden doorgestuurd naar andere apparaten. Er zijn geen opties voor jokertekens in de sink-eigenschap.

De sink-eigenschap kan een van de volgende waarden zijn:

Sink Omschrijving
$upstream Het bericht verzenden naar IoT Hub
BrokeredEndpoint("/modules/<moduleId>/inputs/<input>") Het bericht verzenden naar een specifieke invoer van een specifieke module

IoT Edge biedt ten minste eenmaal garanties. In de IoT Edge-hub worden berichten lokaal opgeslagen voor het geval 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 de berichten op tot de tijd die is opgegeven in de storeAndForwardConfiguration.timeToLiveSecs eigenschap van de gewenste eigenschappen van de IoT Edge-hub.

Prioriteit en time-to-live

Routes kunnen worden gedeclareerd met alleen een tekenreeks die de route definieert of als een object dat een routetekenreeks, een prioriteits integer en een time-to-live geheel getal gebruikt.

Optie 1:

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

Optie 2, geïntroduceerd in IoT Edge versie 1.0.10 met ioT Edge-hubschemaversie 1.1:

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

Prioriteitswaarden kunnen 0-9 zijn, inclusief, waarbij 0 de hoogste prioriteit is. Berichten worden in de wachtrij geplaatst op basis van hun eindpunten. Alle berichten met prioriteit 0 die gericht zijn op een specifiek eindpunt, worden verwerkt voordat berichten met prioriteit 1 die gericht zijn op hetzelfde eindpunt, worden verwerkt en verderop. Als meerdere routes voor hetzelfde eindpunt dezelfde prioriteit hebben, worden hun berichten verwerkt in een eerste-come-first-serve-basis. Als er geen prioriteit is opgegeven, wordt de route toegewezen aan de laagste prioriteit.

De eigenschap timeToLiveSecs neemt de waarde over van de storeAndForwardConfiguration van de IoT Edge-hub, tenzij deze expliciet is ingesteld. De waarde kan elk positief geheel getal zijn.

Zie de referentiepagina voor routeprioriteit en time-to-live voor gedetailleerde informatie over hoe wachtrijen worden beheerd.

Gewenste eigenschappen definiëren of bijwerken

Het implementatiemanifest geeft de gewenste eigenschappen op 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 opgeeft in het implementatiemanifest, wijzigt IoT Hub de moduledubbel op geen enkele manier. In plaats daarvan kunt u de gewenste eigenschappen programmatisch instellen.

Dezelfde mechanismen waarmee u apparaatdubbels kunt wijzigen, worden gebruikt om moduledubbels te wijzigen. 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.4",
              "createOptions": "{}"
            }
          },
          "edgeHub": {
            "type": "docker",
            "status": "running",
            "restartPolicy": "always",
            "startupOrder": 0,
            "settings": {
              "image": "mcr.microsoft.com/azureiotedge-hub:1.4",
              "createOptions": "{\"HostConfig\":{\"PortBindings\":{\"443/tcp\":[{\"HostPort\":\"443\"}],\"5671/tcp\":[{\"HostPort\":\"5671\"}],\"8883/tcp\":[{\"HostPort\":\"8883\"}]}}}"
            }
          }
        },
        "modules": {
          "SimulatedTemperatureSensor": {
            "version": "1.0",
            "type": "docker",
            "status": "running",
            "restartPolicy": "always",
            "startupOrder": 2,
            "settings": {
              "image": "mcr.microsoft.com/azureiotedge-simulated-temperature-sensor:1.0",
              "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