Erfahren Sie, wie Sie Module bereitstellen und Routen in IoT Edge einrichten.

Gilt für: IoT Edge 1,5

Jedes IoT Edge Gerät führt mindestens zwei Module aus: $edgeAgent und $edgeHub, die Teil der IoT Edge Laufzeit sind. 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 Modul twin, 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, die Modulimages enthalten.
  • Anweisungen zum Erstellen und Verwalten der einzelnen Module.
• Der IoT Edge Hub-Modul-Zwilling, der beschreibt, wie Nachrichten zwischen Modulen und zum IoT Hub fließen.
• 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 ein gültiges Manifest eingerichtet haben.

In den Lernprogrammen Azure IoT Edge 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 Verstehen Sie 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 berichtten Eigenschaften für jedes Modul.

Jedes Bereitstellungsmanifest erfordert zwei Module: $edgeAgent und $edgeHub. Diese Module sind Teil der IoT Edge Laufzeit, die das IoT Edge Gerät und die darauf ausgeführten Module verwaltet. Weitere Informationen zu diesen Modulen finden Sie unter Understand the IoT Edge runtime and its architecture.

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 mit nur der IoT Edge Laufzeit ($edgeAgent und $edgeHub) ist gültig.

Bereitstellungsmanifeste verwenden dieses Format:

{
  "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 Laufzeit die Module in Ihrer Bereitstellung installiert. Der IoT Edge Agent ist die Laufzeitkomponente, die die Installation, Updates und Statusberichte für ein IoT Edge Gerät verwaltet. $edgeAgent Das Modul Twin verfügt also über die Konfigurations- und Verwaltungsinformationen für alle Module. Diese Informationen enthalten die Konfigurationsparameter für den IoT Edge Agent selbst.

Die $edgeAgent Eigenschaften verwenden dieses Format:

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

Die IoT Edge Agentschema Version 1.1 wurde mit IoT Edge Version 1.0.10 veröffentlicht und ermöglicht ihnen das Festlegen der Startreihenfolge des Moduls. Verwenden Sie Schemaversion 1.1 für jede IoT Edge Bereitstellung mit Version 1.0.10 oder höher.

Modulkonfiguration und -verwaltung

Definieren Sie, welche Module auf einem IoT Edge Gerät ausgeführt werden, und wie Sie sie in der Liste der gewünschten Eigenschaften des IoT Edge Agents einrichten und verwalten.

Eine vollständige Liste der gewünschten Eigenschaften, die Sie einschließen können oder müssen, finden Sie unter Properties des IoT Edge Agents und IoT Edge Hub.

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 in IoT Edge-Modulen.

Das EdgeHub-Modul und benutzerdefinierte Module verfügen außerdem über drei Eigenschaften, die dem IoT Edge-Agent mitteilen, wie sie verwaltet werden:

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

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

• StartupOrder: In IoT Edge Version 1.0.10 eingeführt. 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. Das modul $edgeAgent hat keinen Startwert, da es immer zuerst gestartet wird. Wahlfrei.

  Der IoT Edge-Agent startet die Module in der Startreihenfolge, wartet jedoch nicht darauf, bis jedes Modul gestartet ist, bevor es mit dem nächsten beginnt.

  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:

  • Modulbild
  • Docker-Erstellungsoptionen
  • Umgebungsvariablen
  • Neustartrichtlinie
  • Richtlinie zur Imageübertragung per Pull
  • version
  • Startreihenfolge

  Wenn Sie keine Moduleigenschaften ändern, wird kein Modulneustart ausgelöst.

Deklarieren von Routen

IoT Edge Hub verwaltet die Kommunikation zwischen Modulen, IoT Hub und nachgeschalteten Geräten. Das $edgeHub Modul twin hat eine gewünschte Eigenschaft, routes 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 mit IoT Edge Version 1.0.10 veröffentlicht und ermöglicht es Ihnen, die Routenpriorisierung und Lebensdauer festzulegen. Verwenden Sie 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 können Nachrichten von Modulen oder nachgeschalteten Geräten weiterleiten.

Mithilfe der 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 Klasse DeviceClient in den IoT-SDKs, um Nachrichten an IoT Edge Gatewaygeräte zu senden, genau wie Nachrichten an den IoT-Hub. Weitere Informationen finden Sie unter Understand und Verwenden Azure IoT Hub SDKs.

Die Quelleigenschaft kann einen der folgenden Werte verwenden:

Bedingung

Die Bedingung ist in einer Routendeklaration optional. Wenn Sie alle Nachrichten von der Quelle an die Spüle übergeben möchten, lassen Sie die WHERE-Klausel weg. Sie können auch die Abfragesprache IoT Hub verwenden, um Nachrichten oder Nachrichtentypen zu filtern, die die Bedingung erfüllen. IoT Edge Routen unterstützen das Filtern von Nachrichten nicht auf Grundlage von Zwillings-Tags oder Eigenschaften.

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 für einen der drei Parameter, indem Sie diese Syntax verwenden:

• Systemeigenschaften: $<propertyName> oder {$<propertyName>}
• Anwendungseigenschaften: <propertyName>
• Körpereigenschaften: $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 Spüle definiert, wo Nachrichten gesendet werden sollen. 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:

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

IoT Edge Hub speichert Nachrichten bis zur zeit, die in der eigenschaft storeAndForwardConfiguration.timeToLiveSecs der gewünschten Eigenschaften des IoT Edge Hubs festgelegt ist.

Priorität und Lebensdauer

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 Hubschema, 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. Das System stellt Nachrichten nach ihren Endpunkten in die Warteschlange. Das System verarbeitet alle Prioritäts-0-Nachrichten für einen bestimmten Endpunkt, bevor alle Prioritäts-1-Nachrichten für denselben Endpunkt verarbeitet werden. Wenn mehrere Routen für denselben Endpunkt dieselbe Priorität haben, verarbeitet das System Nachrichten in der Reihenfolge, in der sie eingehen. Wenn Sie keine Priorität festlegen, verwendet die Route die niedrigste Priorität.

Die Eigenschaft timeToLiveSecs verwendet den Wert aus IoT Edge Hubs storeAndForwardConfiguration, 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 Moduls nicht im Bereitstellungsmanifest festlegen, ändert IoT Hub den Modul twin 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 im Modul-Zwilling Entwicklerhandbuch.

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

• Eine vollständige Liste der Eigenschaften, die Sie in $edgeAgent und $edgeHub einfügen können oder müssen, finden Sie unter Eigenschaften des IoT Edge Agents und des IoT Edge Hubs.
• Nachdem Sie jetzt wissen, wie IoT Edge Module funktionieren, erfahren Sie mehr über die Anforderungen und Tools für die Entwicklung von IoT Edge Modulen.