Freigeben über

Bedarfsgerechtes Bereitstellen und Überwachen von IoT Edge-Modulen mithilfe der Azure CLI

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.

Verwenden Sie die Azure CLI, um eine automatische Bereitstellung von Azure IoT Edge zu erstellen und Bereitstellungen für viele Geräte gleichzeitig zu verwalten. Automatische Bereitstellungen für IoT Edge sind Teil des Features Geräteverwaltung von Azure IoT Hub. Mit Bereitstellungen können Sie mehrere Module auf mehreren Geräten bereitstellen, den Status und die Integrität von Modulen überwachen und bei Bedarf Änderungen vornehmen.

In diesem Artikel richten Sie die Azure CLI und die IoT-Erweiterung ein. Anschließend stellen Sie Module in einer Reihe von IoT Edge-Geräten bereit und überwachen den Fortschritt mithilfe von CLI-Befehlen.

Voraussetzungen

  • Ein IoT Hub in Ihrem Azure-Abonnement.

  • Mindestens ein IoT Edge-Gerät.

    Wenn Sie kein IoT Edge-Gerät eingerichtet haben, können Sie eines in einem virtuellen Azure-Computer erstellen. Führen Sie die Schritte in einer der folgenden Schnellstartanleitungen aus: Erstellen eines virtuellen Linux-Geräts oder Erstellen eines virtuellen Windows-Geräts.

  • Die Azure CLI ist in Ihrer Umgebung vorhanden. Sie benötigen die Azure CLI-Version 2.0.70 oder höher. Verwenden Sie az --version, um zu überprüfen. Diese Version unterstützt az-Erweiterungsbefehle, und das Framework für Knack-Befehle wird eingeführt.

  • Die IoT-Erweiterung für die Azure CLI ist vorhanden.

Konfigurieren eines Bereitstellungsmanifests

Ein Bereitstellungsmanifest ist ein JSON-Dokument, das beschreibt, welche Module bereitgestellt werden sollen, wie Daten zwischen den Modulen und die gewünschten Eigenschaften der Modul-Zwillinge fließen. Weitere Informationen finden Sie unter Informationen zum Bereitstellen von Modulen und Einrichten von Routen in IoT Edge.

Wenn Sie Module mithilfe der Azure CLI bereitstellen möchten, speichern Sie das Bereitstellungsmanifest lokal als TXT-Datei. Sie verwenden den Dateipfad im nächsten Abschnitt, wenn Sie den Befehl ausführen, um die Konfiguration auf Ihr Gerät anzuwenden.

Hier ist ein einfaches Bereitstellungsmanifest mit einem Modul als Beispiel.

{
  "content": {
    "modulesContent": {
      "$edgeAgent": {
        "properties.desired": {
          "schemaVersion": "1.1",
          "runtime": {
            "type": "docker",
            "settings": {
              "minDockerVersion": "v1.25",
              "loggingOptions": "",
              "registryCredentials": {}
            }
          },
          "systemModules": {
            "edgeAgent": {
              "type": "docker",
              "settings": {
                "image": "mcr.microsoft.com/azureiotedge-agent:1.5",
                "createOptions": "{}"
              }
            },
            "edgeHub": {
              "type": "docker",
              "status": "running",
              "restartPolicy": "always",
              "settings": {
                "image": "mcr.microsoft.com/azureiotedge-hub:1.5",
                "createOptions": "{\"HostConfig\":{\"PortBindings\":{\"5671/tcp\":[{\"HostPort\":\"5671\"}],\"8883/tcp\":[{\"HostPort\":\"8883\"}],\"443/tcp\":[{\"HostPort\":\"443\"}]}}}"
              }
            }
          },
          "modules": {
            "SimulatedTemperatureSensor": {
              "version": "1.5",
              "type": "docker",
              "status": "running",
              "restartPolicy": "always",
              "settings": {
                "image": "mcr.microsoft.com/azureiotedge-simulated-temperature-sensor:1.5",
                "createOptions": "{}"
              }
            }
          }
        }
      },
      "$edgeHub": {
        "properties.desired": {
          "schemaVersion": "1.1",
          "routes": {
            "upstream": "FROM /messages/* INTO $upstream"
          },
          "storeAndForwardConfiguration": {
            "timeToLiveSecs": 7200
          }
        }
      },
      "SimulatedTemperatureSensor": {
        "properties.desired": {
          "SendData": true,
          "SendInterval": 5
        }
      }
    }
  }
}

Hinweis

In diesem Beispielbereitstellungsmanifest wird die Schemaversion 1.1 für den IoT Edge-Agent und den Hub verwendet. Die Schemaversion 1.1 wird zusammen mit IoT Edge Version 1.0.10 veröffentlicht. Sie können Features wie die Startreihenfolge des Moduls und die Routenpriorisierung verwenden.

Mehrstufige Bereitstellung

Bei der mehrstufigen Bereitstellung handelt es sich um eine Art automatischer Bereitstellung, die Sie übereinander schichten können. Weitere Informationen zu mehrstufigen Bereitstellungen finden Sie unter Grundlegendes zu automatischen IoT Edge-Bereitstellungen für einzelne Geräte oder nach Bedarf.

Sie können mehrschichtige Bereitstellungen mit der Azure CLI wie jede automatische Bereitstellung erstellen und verwalten, mit nur wenigen Unterschieden. Nachdem Sie eine mehrschichtige Bereitstellung erstellt haben, funktioniert die Azure CLI für mehrschichtige Bereitstellungen genauso wie für jede Bereitstellung. Um eine mehrstufige Bereitstellung zu erstellen, fügen Sie dem Erstellungsbefehl das Flag --layered hinzu.

Der zweite Unterschied besteht darin, wie Sie das Bereitstellungsmanifest erstellen. Standardmäßige automatische Bereitstellungen müssen die Systemlaufzeitmodule und alle Benutzermodule enthalten. Mehrstufige Bereitstellungen können nur Benutzermodule umfassen. Für mehrstufige Bereitstellungen ist zusätzlich eine standardmäßige automatische Bereitstellung auf einem Gerät notwendig, um die erforderlichen Komponenten jedes IoT Edge-Geräts bereitzustellen, z. B. die Systemruntimemodule.

Hier ist ein einfaches Layered Deployment Manifest mit einem Modul als Beispiel.

{
  "content": {
    "modulesContent": {
      "$edgeAgent": {
        "properties.desired.modules.SimulatedTemperatureSensor": {
          "settings": {
            "image": "mcr.microsoft.com/azureiotedge-simulated-temperature-sensor:1.5",
              "createOptions": "{}"
          },
          "type": "docker",
          "status": "running",
          "restartPolicy": "always",
          "version": "1.5"
        }
      },
      "$edgeHub": {
        "properties.desired.routes.upstream": "FROM /messages/* INTO $upstream"
      },
      "SimulatedTemperatureSensor": {
        "properties.desired": {
          "SendData": true,
          "SendInterval": 5
        }
      }
    }
  }
}

Hinweis

Dieses mehrschichtige Bereitstellungsmanifest weist ein etwas anderes Format als ein Standardbereitstellungsmanifest auf. Die gewünschten Eigenschaften der Runtimemodule werden reduziert und nutzen die Punktnotation. Diese Formatierung ist erforderlich, damit das Azure-Portal die mehrschichtige Bereitstellung erkennen kann. Zum Beispiel:

  • properties.desired.modules.<module_name>
  • properties.desired.routes.<route_name>

Das vorherige Beispiel zeigt die Layered-Deployment-Einstellung properties.desired für ein Modul. Wenn diese mehrschichtige Bereitstellung auf ein Gerät ausgerichtet ist, auf das dasselbe Modul bereits angewendet wird, überschreibt es alle vorhandenen gewünschten Eigenschaften. Um die gewünschten Eigenschaften zu aktualisieren, anstatt sie zu überschreiben, definieren Sie einen neuen Unterabschnitt. Zum Beispiel:

"SimulatedTemperatureSensor": {
  "properties.desired.layeredProperties": {
    "SendData": true,
    "SendInterval": 5
  }
}

Sie können dasselbe auch mit der folgenden Syntax ausdrücken:

"SimulatedTemperatureSensor": {
  "properties.desired.layeredProperties.SendData" : true,
  "properties.desired.layeredProperties.SendInterval": 5
}

Hinweis

Derzeit müssen alle schichtbasierten Bereitstellungen ein edgeAgent-Objekt enthalten, um gültig zu sein. Obwohl eine mehrschichtige Bereitstellung nur Moduleigenschaften aktualisiert, schließen Sie ein leeres Objekt ein. Beispiel: "$edgeAgent":{} Eine mehrstufige Bereitstellung mit einem leeren edgeAgent-Objekt wird im -Modulzwilling als edgeAgent angezeigt, nicht als angewandt.

So erstellen Sie eine mehrschichtige Bereitstellung:

  • Fügen Sie das Flag --layered dem Befehl zum Erstellen in der Azure-Befehlszeilenschnittstelle hinzu.
  • Fügen Sie keine Systemmodule ein.
  • Verwenden Sie die vollständige Punktnotation unter $edgeAgent und $edgeHub.

Weitere Informationen zum Konfigurieren von Modulzwillingen in mehrstufigen Bereitstellungen finden Sie unter Mehrstufige Bereitstellung.

Identifizieren von Geräten mithilfe von Tags

Bevor Sie eine Bereitstellung erstellen, müssen Sie angeben, welche Geräte Sie betreffen möchten. Azure IoT Edge erkennt Geräte anhand von Tags im Gerätezwilling.

Jedes Gerät kann mehrere Tags aufweisen, die Sie auf eine für Ihre Lösung sinnvolle Weise definieren können. Wenn Sie beispielsweise einen Campus intelligenter Gebäude verwalten, können Sie einem Gerät die folgenden Tags hinzufügen:

"tags":{
  "location":{
    "building": "20",
    "floor": "2"
  },
  "roomtype": "conference",
  "environment": "prod"
}

Weitere Informationen zu Gerätezwillingen und Tags finden Sie unter Verstehen und Verwenden von Gerätezwillingen in IoT Hub.

Erstellen einer Bereitstellung

Stellen Sie Module auf Zielgeräten bereit, indem Sie eine Bereitstellung mit dem Bereitstellungsmanifest und anderen Parametern erstellen.

Führen Sie den Befehl az iot edge deployment create aus, um eine Bereitstellung zu erstellen.

az iot edge deployment create --deployment-id <deployment-id> --hub-name <hub-name> --content <file-path> --labels "<labels>" --target-condition "<target-query>" --priority <priority>

Fügen Sie das --layered Flag hinzu, um eine mehrschichtige Bereitstellung zu erstellen.

Der az iot edge deployment create Befehl verwendet die folgenden Parameter:

  • --layered: Optionales Kennzeichen, das die Bereitstellung als mehrschichtige Bereitstellung identifiziert.
  • --deployment-id: Name der Bereitstellung, die im IoT-Hub erstellt wurde. Verwenden Sie einen eindeutigen Namen mit bis zu 128 Kleinbuchstaben. Vermeiden Sie Leerzeichen und diese ungültigen Zeichen: & ^ [ ] { } \ | " < > /. Dieser Parameter ist erforderlich.
  • --content: Dateipfad zur JSON-Datei des Bereitstellungsmanifests. Dieser Parameter ist erforderlich.
  • --hub-name: Name des IoT-Hubs, in dem die Bereitstellung erstellt wird. Der Hub muss aus dem aktuellen Abonnement stammen. Ändern Sie Ihr aktuelles Abonnement, indem Sie es ausführen az account set -s <subscription-name>.
  • --labels: Name-Wert-Paare, mit denen Sie Ihre Bereitstellungen beschreiben und nachverfolgen können. Bezeichnungen verwenden JSON-Formatierung für Namen und Werte. Beispiel: {"HostPlatform":"Linux", "Version":"3.0.1"}
  • --target-condition: Bedingung, die bestimmt, welche Geräte für diese Bereitstellung bestimmt werden. Die Bedingung basiert auf den Gerätezwillingstags oder auf den gemeldeten Gerätezwillingseigenschaften und muss dem Ausdrucksformat entsprechen. Beispiel: tags.environment='test' and properties.reported.devicemodel='4000x' Wenn Sie die Zielbedingung nicht angeben, wird die Bereitstellung auf keine Geräte angewendet.
  • --priority: Positiver Integer. Wenn zwei oder mehr Bereitstellungen auf dasselbe Gerät abzielen, gilt die Bereitstellung mit der höchsten Priorität.
  • --metrics: Metriken, die die edgeHub gemeldeten Eigenschaften abfragen, um den Status einer Bereitstellung nachzuverfolgen. Metriken verwenden JSON-Eingaben oder einen Dateipfad. Beispiel: '{"queries": {"mymetric": "SELECT deviceId FROM devices WHERE properties.reported.lastDesiredStatus.code = 200"}}'

Informationen zum Überwachen einer Bereitstellung mit der Azure CLI finden Sie unter Überwachen von IoT Edge-Bereitstellungen.

Hinweis

Wenn Sie eine neue IoT Edge-Bereitstellung erstellen, kann es bis zu 5 Minuten dauern, bis IoT Hub die neue Konfiguration verarbeitet und die neuen gewünschten Eigenschaften an die Zielgeräte gesendet wird.

Ändern einer Bereitstellung

Wenn Sie eine Bereitstellung ändern, werden die Änderungen sofort auf alle Zielgeräte repliziert.

Wenn Sie die Zielbedingung aktualisieren, treten die folgenden Änderungen auf:

  • Wenn ein Gerät nicht die alte Zielbedingung erfüllt, sondern die neue Zielbedingung erfüllt, und diese Bereitstellung ist die höchste Priorität für dieses Gerät, wird diese Bereitstellung auf das Gerät angewendet.
  • Wenn ein Gerät, das derzeit diese Bereitstellung ausführt, die Zielbedingung nicht mehr erfüllt, deinstalliert es diese Bereitstellung und übernimmt die Bereitstellung mit der nächsten höchsten Priorität .
  • Wenn ein Gerät, das derzeit diese Bereitstellung ausführt, die Zielbedingung nicht mehr erfüllt und die Zielbedingung einer anderen Bereitstellung nicht erfüllt, tritt keine Änderung auf dem Gerät auf. Das Gerät führt seine aktuellen Module weiterhin im aktuellen Zustand aus, wird aber nicht mehr als Teil dieser Bereitstellung verwaltet. Nachdem das Gerät die Zielbedingung einer anderen Bereitstellung erfüllt hat, deinstalliert es diese Bereitstellung und übernimmt die neue Bereitstellung.

Sie können den Inhalt einer Bereitstellung nicht aktualisieren. Dies gilt auch für die im Bereitstellungsmanifest definierten Module und Routen. Um den Inhalt einer Bereitstellung zu aktualisieren, erstellen Sie eine neue Bereitstellung, die auf dieselben Geräte mit höherer Priorität ausgerichtet ist. Sie können bestimmte Eigenschaften eines vorhandenen Moduls ändern, einschließlich der Zielbedingung, Bezeichnungen, Metriken und Priorität.

Führen Sie zum Aktualisieren einer Bereitstellung den Befehl az group deployment update aus:

az iot edge deployment update --deployment-id <deployment-id> --hub-name <hub-name> --set <property1.property2='value'>

Der Befehl "Bereitstellungsupdate" verwendet die folgenden Parameter:

  • --deployment-id: Der Name der Bereitstellung im IoT-Hub.
  • --hub-name: Der Name des IoT-Hubs, in dem die Bereitstellung vorhanden ist. Der Hub muss aus dem aktuellen Abonnement stammen. Führen Sie az account set -s <subscription-name> aus, um zu einem anderen Abonnement zu wechseln.
  • --set: Ändern einer Eigenschaft in der Bereitstellung. Sie können die folgenden Eigenschaften ändern:
    • targetCondition (z. B. targetCondition=tags.location.state='Oregon')
    • labels
    • priority
  • --add: Fügen Sie der Bereitstellung eine neue Eigenschaft hinzu, einschließlich Zielbedingungen oder Bezeichnungen.
  • --remove: Entfernen Sie eine vorhandene Eigenschaft, einschließlich Zielbedingungen oder Bezeichnungen.

Löschen einer Bereitstellung

Wenn Sie eine Bereitstellung löschen, verwenden die Geräte die nächsthöhere Bereitstellung in der Prioritätsreihenfolge. Wenn Geräte nicht die Zielbedingung einer anderen Bereitstellung erfüllen, werden die Module beim Löschen der Bereitstellung nicht entfernt.

Führen Sie den Befehl az iot edge deployment delete aus, um eine Bereitstellung zu löschen.

az iot edge deployment delete --deployment-id <deployment-id> --hub-name <hub-name>

Der deployment delete Befehl verwendet die folgenden Parameter:

  • --deployment-id. Der Name der Bereitstellung, die im IoT-Hub vorhanden ist.
  • --hub-name. Der Name des IoT Hubs, in dem die Bereitstellung vorhanden ist. Der Hub muss aus dem aktuellen Abonnement stammen. Wechseln Sie zum gewünschten Abonnement mit dem Befehl az account set -s [subscription name].

Nächste Schritte

Erfahren Sie mehr zum Bereitstellen von Modulen auf IoT Edge-Geräten.

  • Last updated on