Freigeben über

Bereitstellen von Modulen und Einrichten von Routen in IoT Edge

Gilt für:Häkchen für IoT Edge 1.5 IoT Edge 1.5

Wichtig

IoT Edge 1.5 LTS ist das unterstützte Release. IoT Edge 1.4 LTS wurde am 12. November 2024 eingestellt. Wenn Sie ein früheres Release verwenden, finden Sie weitere Informationen unter Aktualisieren von IoT Edge.

Jedes IoT Edge-Gerät führt mindestens zwei Module aus, die die IoT Edge-Runtime ausmachen: „$edgeAgent“ und „$edgeHub“. Ein IoT Edge-Gerät kann mehrere Module für verschiedene Prozesse ausführen. Verwenden Sie ein Bereitstellungsmanifest, um Ihrem Gerät mitzuteilen, welche Module installiert werden sollen und wie sie für die Zusammenarbeit eingerichtet werden.

Das Bereitstellungsmanifest ist ein JSON-Dokument, das Folgendes beschreibt:

  • Der IoT Edge-Agent-Modulzwilling, der drei Komponenten umfasst:
    • Das Containerimage für jedes Modul, das auf dem Gerät ausgeführt wird
    • Die Anmeldeinformationen für die Verwendung privater Containerregistrierungen mit Modulimages
    • Anweisungen zum Erstellen und Verwalten der einzelnen Module
  • Den Modulzwilling des IoT Edge-Hubs, der u. a. festlegt, wie Nachrichten zwischen Modulen und an IoT Hub gesendet werden
  • Die gewünschten Eigenschaften aller zusätzlichen Modul-Zwillinge (optional)

Alle IoT Edge-Geräte benötigen ein Bereitstellungsmanifest. Eine neu installierte IoT Edge-Laufzeit zeigt einen Fehlercode an, bis sie mit einem gültigen Manifest eingerichtet ist.

In den Azure IoT Edge-Lernprogrammen erstellen Sie ein Bereitstellungsmanifest mithilfe eines Assistenten im Azure IoT Edge-Portal. Sie können ein Bereitstellungsmanifest auch programmgesteuert mithilfe von REST oder dem IoT Hub Service SDK anwenden. Weitere Informationen finden Sie unter Grundlegendes zu IoT Edge-Bereitstellungen.

Erstellen eines Bereitstellungsmanifests

Ein Bereitstellungsmanifest ist eine Liste der Modul-Zwillinge, die mit ihren gewünschten Eigenschaften festgelegt sind. Es teilt einem IoT Edge-Gerät oder einer Gruppe von Geräten mit, welche Module installiert und wie sie eingerichtet werden sollen. Bereitstellungsmanifeste enthalten die gewünschten Eigenschaften für jeden Modulzwilling. IoT Edge-Geräte melden die gemeldeten Eigenschaften für jedes Modul.

Jedes Bereitstellungsmanifest erfordert zwei Module: $edgeAgent und $edgeHub. Diese Module gehören zur IoT Edge-Runtime, die das IoT Edge-Gerät und die darauf ausgeführten Module verwaltet. Weitere Informationen zu diesen Modulen finden Sie unter Grundlegendes zur IoT Edge-Runtime und ihrer Architektur.

Sie können zusätzlich zu den beiden Laufzeitmodulen bis zu 50 zusätzliche Module hinzufügen, die auf einem IoT Edge-Gerät ausgeführt werden können.

Ein Bereitstellungsmanifest, das nur die IoT Edge-Laufzeit ($edgeAgent und $edgeHub) besitzt, ist gültig.

Bereitstellungsmanifeste verwenden diese Struktur:

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

Konfigurieren von Modulen

Definieren Sie, wie die IoT Edge-Runtime die Module in Ihrer Bereitstellung installiert. Der IoT Edge-Agent ist die Runtimekomponente, die Installation, Updates und Statusberichte für ein IoT Edge-Gerät verwaltet. Das $edgeAgent Modul Twin verfügt also über die Konfigurations- und Verwaltungsinformationen für alle Module. Zu diesen Informationen zählen die Konfigurationsparameter für den IoT Edge-Agent selbst.

Die $edgeAgent-Eigenschaften weisen die folgende Struktur auf:

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

Das IoT Edge-Agent-Schema Version 1.1 wurde mit IoT Edge Version 1.0.10 veröffentlicht und ermöglicht ihnen das Festlegen der Modulstartreihenfolge. Verwenden Sie Die Schemaversion 1.1 für jede IoT Edge-Bereitstellung mit Version 1.0.10 oder höher.

Modulkonfiguration und -verwaltung

In der Liste der gewünschten Eigenschaften des IoT Edge-Agents definieren Sie, welche Module auf einem IoT Edge-Gerät ausgeführt werden und wie sie eingerichtet und verwaltet werden.

Eine vollständige Liste der gewünschten Eigenschaften, die hinzugefügt werden können oder müssen, finden Sie unter Properties of the IoT Edge agent and Edge hub (Eigenschaften des IoT Edge-Agents und IoT Edge-Hubs).

Zum Beispiel:

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

Jedes Modul verfügt über eine Einstellungseigenschaft mit dem Modulimage, eine Adresse für das Containerimage in einer Containerregistrierung und alle createOptions zum Einrichten des Images beim Start. Weitere Informationen finden Sie unter Konfigurieren von Erstellungsoptionen für Container für IoT Edge-Module.

Das edgeHub-Modul und die benutzerdefinierten Module haben auch drei Eigenschaften, die den IoT Edge-Agent informieren, wie sie verwaltet werden müssen:

  • Status: Gibt an, ob das Modul bei der ersten Bereitstellung ausgeführt oder beendet wird. Erforderlich.

  • RestartPolicy: Wann und ob der IoT Edge-Agent das Modul neu startet, wenn es beendet wird. Wenn das Modul ohne Fehler beendet wird, wird es nicht automatisch gestartet. Weitere Informationen finden Sie in der Docker-Dokumentation: Automatisches Starten von Containern. Erforderlich.

  • StartupOrder: Eingeführt in IoT Edge, Version 1.0.10. Die Reihenfolge, in der der IoT Edge-Agent zum Starten der Module bei der ersten Bereitstellung verwendet wird. Die Reihenfolge verwendet ganze Zahlen, wobei ein Modul mit dem Startwert 0 zuerst beginnt und dann höhere Zahlen folgen. Für das Modul „edgeAgent“ gibt es keinen Startwert, weil es immer zuerst gestartet wird. Wahlfrei.

    Der IoT Edge-Agent startet die Module in der Reihenfolge ihres Startwerts, wartet aber nicht, bis der Start jedes Moduls abgeschlossen wurde, bevor er den nächsten startet.

    Die Startreihenfolge hilft, wenn einige Module von anderen abhängig sind. Sie können z. B. möchten, dass das EdgeHub-Modul zuerst gestartet wird, damit es bereit ist, Nachrichten weiterzuleiten, wenn die anderen Module beginnen. Oder Sie möchten ein Speichermodul starten, bevor Sie Module starten, die Daten an das Modul senden. Entwerfen Sie ihre Module jedoch immer so, dass Fehler anderer Module behandelt werden. Container können jederzeit und beliebig oft beendet und neu gestartet werden.

    Hinweis

    Durch Das Ändern der Eigenschaften eines Moduls wird dieses Modul neu gestartet. Ein Neustart erfolgt beispielsweise, wenn Sie die Eigenschaften für folgendes ändern:

    • Modulimage
    • Docker-Erstellungsoptionen
    • Umgebungsvariablen
    • Neustartrichtlinie
    • Richtlinie zur Imageübertragung per Pull
    • Ausgabe
    • Startreihenfolge

    Wenn keine Moduleigenschaften geändert werden, wird kein Modulneustart ausgelöst.

Deklarieren von Routen

Der IoT Edge-Hub verwaltet die Kommunikation zwischen Modulen, IoT Hub und downstream-Geräten. Das $edgeHub Modul twin verfügt über eine gewünschte Eigenschaft namens Routen , die definiert, wie Nachrichten innerhalb einer Bereitstellung verschoben werden. Sie können mehrere Routen in derselben Bereitstellung einrichten.

Deklarieren Sie Routen in den $edgeHub gewünschten Eigenschaften mithilfe dieser Syntax:

{
  "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 Version 1 wurde zusammen mit IoT Edge Version 1.0.10 veröffentlicht und ermöglicht Ihnen das Festlegen von Routenpriorisierung und Lebensdauer. Verwenden Sie Die Schemaversion 1.1 für jede IoT Edge-Bereitstellung mit Version 1.0.10 oder höher.

Jede Route benötigt eine Quelle für eingehende Nachrichten und eine Spüle für ausgehende Nachrichten. Die Bedingung ist optional und ermöglicht es Ihnen, Nachrichten zu filtern.

Weisen Sie zuerst Routen zum Verarbeiten wichtiger Nachrichten Priorität zu. Dieses Feature hilft, wenn die Upstreamverbindung schwach oder begrenzt ist und Sie wichtige Daten über Standard-Telemetrienachrichten priorisieren müssen.

Quelle

Die Quelle gibt an, woher die Nachrichten stammen. IoT Edge kann Nachrichten von Modulen oder nachgeschalteten Geräten weiterleiten.

Mit den IoT-SDKs können Module bestimmte Ausgabewarteschlangen für ihre Nachrichten mithilfe der ModuleClient-Klasse festlegen. Ausgabewarteschlangen sind nicht erforderlich, aber sie helfen bei der Verwaltung mehrerer Routen. Nachgeschaltete Geräte verwenden die DeviceClient-Klasse in den IoT-SDKs, um Nachrichten an IoT Edge-Gatewaygeräte zu senden, genau wie sie Nachrichten an IoT Hub senden. Weitere Informationen finden Sie unter Verstehen und Verwenden von Azure IoT Hub-SDKs.

Die Quelleigenschaft kann einen der folgenden Werte verwenden:

Quelle Beschreibung
/* Alle Gerät-zu-Cloud-Nachrichten oder Benachrichtigungen über Änderungen am Zwilling, die von Modulen oder nachgeschalteten Geräten gesendet wurden
/twinChangeNotifications Alle Änderungen am Zwilling (gemeldete Eigenschaften), die von Modulen oder nachgeschalteten Geräten gesendet wurden
/messages/* Alle Gerät-zu-Cloud-Nachrichten, die von einem Modul über eine beliebige oder keine Ausgabe oder von einem nachgeschalteten Gerät gesendet wurden
/messages/modules/* Alle Gerät-zu-Cloud-Nachrichten, die von einem Modul über eine beliebige oder keine Ausgabe versendet wurden
/messages/modules/<moduleId>/* Alle Gerät-zu-Cloud-Nachrichten, die von einem bestimmten Modul über eine beliebige oder keine Ausgabe gesendet wurden
/messages/modules/<moduleId>/outputs/* Alle Gerät-zu-Cloud-Nachrichten, die von einem bestimmten Modul über eine beliebige Ausgabe gesendet wurden
/messages/modules/<moduleId>/outputs/<output> Alle Gerät-zu-Cloud-Nachrichten, die von einem bestimmten Modul über eine bestimmte Ausgabe gesendet wurden

Bedingung

Die Bedingung ist in einer Routendeklaration optional. Um alle Nachrichten von der Quelle an die Spüle zu übergeben, lassen Sie die WHERE-Klausel aus. Oder verwenden Sie die IoT Hub-Abfragesprache , um Nachrichten oder Nachrichtentypen zu filtern, die die Bedingung erfüllen. IoT Edge-Routen unterstützen keine Nachrichtenfilterung, die auf Zwillingstags oder -eigenschaften basiert.

Nachrichten, die zwischen Modulen in IoT Edge wechseln, verwenden dasselbe Format wie Nachrichten zwischen Ihren Geräten und Azure IoT Hub. Alle Nachrichten verwenden das JSON-Format und weisen systemProperties, appProperties und Bodyparameter auf.

Erstellen Sie Abfragen um einen der drei Parameter, die diese Syntax verwenden:

  • Systemeigenschaften: $<propertyName> oder {$<propertyName>}
  • Anwendungseigenschaften: <propertyName>
  • Texteigenschaften: $body.<propertyName>

Beispiele zum Erstellen von Abfragen für Nachrichteneigenschaften finden Sie unter Device-to-Cloud message routes query expressions.

Sie können z. B. Nachrichten filtern, die von einem nachgeschalteten Gerät an einem Gatewaygerät eingehen. Nachrichten von Modulen enthalten eine die Systemeigenschaft connectionModuleId. Um Nachrichten von nachgeschalteten Geräten direkt an IoT Hub weiterzuleiten und Modulnachrichten auszuschließen, verwenden Sie diese Route:

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

Senke

Die Senke definiert, wohin Nachrichten gesendet werden. Nur Module und IoT Hub können Nachrichten empfangen. Nachrichten können nicht an andere Geräte weitergeleitet werden. Die Senkeneigenschaft unterstützt keine Platzhalter.

Die Sinkeigenschaft kann einen der folgenden Werte verwenden:

Senke Beschreibung
$upstream Sendet die Nachricht an IoT Hub
BrokeredEndpoint("/modules/<moduleId>/inputs/<input>") Sendet die Nachricht an eine bestimmte Eingabe eines bestimmten Moduls

IoT Edge bietet mindestens einmalige Garantien. Der IoT Edge-Hub speichert Nachrichten lokal, wenn eine Route die Nachricht nicht an die Spüle übermitteln kann. Wenn beispielsweise der IoT Edge-Hub keine Verbindung mit IoT Hub herstellen kann oder das Zielmodul nicht verbunden ist.

Der IoT Edge-Hub speichert Nachrichten bis zur in der storeAndForwardConfiguration.timeToLiveSecs Eigenschaft der gewünschten Eigenschaften des IoT Edge-Hubs festgelegte Zeit.

Priorität und Gültigkeitsdauer

Deklarieren Sie Routen als Zeichenfolge, die die Route definiert, oder als Objekt mit einer Routenzeichenfolge, einer Prioritätszahl und einer ganzzahligen Zeit-zu-Live-Zahl.

Option 1:

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

Option 2 (eingeführt in IoT Edge Version 1.0.10 mit IoT Edge Hub Schema Version 1.1)

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

Prioritätswerte liegen zwischen 0 und 9, wobei 0 die höchste Priorität ist. Nachrichten werden von ihren Endpunkten in die Warteschlange gestellt. Alle Nachrichten der Priorität 0 für einen bestimmten Endpunkt werden vor allen Nachrichten der Priorität 1 für denselben Endpunkt verarbeitet. Wenn mehrere Routen für denselben Endpunkt dieselbe Priorität haben, werden Nachrichten in der Reihenfolge verarbeitet, in der sie eingehen. Wenn Sie keine Priorität festlegen, verwendet die Route die niedrigste Priorität.

Die timeToLiveSecs-Eigenschaft verwendet den Wert aus dem StoreAndForwardConfiguration des IoT Edge Hub, es sei denn, Sie legen ihn direkt fest. Der Wert kann eine beliebige positive ganze Zahl sein.

Ausführliche Informationen zur Verwaltung von Prioritätswarteschlangen finden Sie unter Route priority and time-to-live.

Definieren oder Aktualisieren der gewünschten Eigenschaften

Das Bereitstellungsmanifest legt die gewünschten Eigenschaften für jedes Modul fest, das auf dem IoT Edge-Gerät bereitgestellt wird. Die im Bereitstellungsmanifest angegebenen gewünschten Eigenschaften überschreiben alle gewünschten Eigenschaften, die aktuell im Modulzwilling vorhanden sind.

Wenn Sie die gewünschten Eigenschaften eines Modulzwillings nicht im Bereitstellungsmanifest festlegen, ändert IoT Hub den Modulzwilling nicht. Legen Sie stattdessen die gewünschten Eigenschaften programmgesteuert fest.

Die gleichen Mechanismen, mit denen Sie Gerätezwillinge ändern können, können verwendet werden, um Modulzwillinge zu ändern. Weitere Informationen finden Sie unter Verstehen und Verwenden von Gerätezwillingen in IoT Hub.

Beispiel für ein Bereitstellungsmanifest

Das folgende Beispiel zeigt, wie ein gültiges Bereitstellungsmanifestdokument aussehen kann.

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

Nächste Schritte