Erste Schritte mit Gerätezwillingen (Azure CLI)

  • Artikel

Gerätezwillinge sind JSON-Dokumente, in denen Gerätestatusinformationen gespeichert werden, einschließlich Metadaten, Konfigurationen und Bedingungen. Von IoT Hub wird für jedes Gerät, das eine Verbindung herstellt, dauerhaft ein Gerätezwilling gespeichert.

Hinweis

Die in diesem Artikel beschriebenen Features stehen nur im Standard-Tarif von IoT Hub zur Verfügung. Weitere Informationen zu den IoT Hub-Tarifen „Basic“ und „Standard/Free“ finden Sie unter Wählen des richtigen IoT Hub-Tarifs für Ihre Lösung.

Verwenden Sie Gerätezwillinge für Folgendes:

  • Speichern von Gerätemetadaten von Ihrem Lösungs-Back-End

  • Melden von aktuellen Zustandsinformationen wie verfügbare Funktionen und Bedingungen, z.B. die verwendete Verbindungsmethode, von Ihrer Geräte-App

  • Synchronisieren des Zustands von Workflows mit langer Ausführungsdauer, z.B. Firmware- und Konfigurationsupdates, zwischen einer Geräte-App und einer Back-End-App

  • Abfragen von Metadaten, Konfiguration oder Status des Geräts

Gerätezwillinge sind für die Synchronisierung und zum Abfragen von Gerätekonfigurationen und -bedingungen ausgelegt. Weitere Informationen zu Gerätezwillingen, einschließlich der Verwendung von Gerätezwillingen, finden Sie unter Verstehen und Verwenden von Gerätezwillingen in IoT Hub.

IoT-Hubs speichern Gerätezwillinge, die die folgenden Elemente enthalten:

  • Tags. Gerätemetadaten, auf die nur vom Lösungs-Back-End zugegriffen werden kann.

  • Gewünschte Eigenschaften JSON-Objekte, die vom Lösungs-Back-End geändert und von der Geräte-App überwacht werden können.

  • Gemeldete Eigenschaften JSON-Objekte, die von der Geräte-App geändert und vom Lösungs-Back-End gelesen werden können.

Tags und Eigenschaften können keine Arrays, aber geschachtelte Objekte enthalten.

Die folgende Abbildung zeigt die Organisation des Gerätezwillings:

Screenshot eines Konzeptdiagramms für Gerätezwillinge.

Außerdem können mit dem Lösungs-Back-End Gerätezwillinge basierend auf allen obigen Daten abgefragt werden. Weitere Informationen zu Gerätezwillingen finden Sie unter Grundlegendes zu Gerätezwillingen. Weitere Informationen zu Abfragen finden Sie unter IoT Hub-Abfragesprache.

In diesem Artikel lernen Sie Folgendes:

  • Verwenden Sie ein simuliertes Gerät, um den Konnektivitätskanal als gemeldete Eigenschaft auf dem Gerätezwilling zu melden.

  • Fragen Sie Geräte ab, indem Sie Filter für die zuvor erstellten Tags und Eigenschaften verwenden.

Weitere Informationen zum Verwenden von auf Gerätezwillingen gemeldeten Eigenschaften finden Sie im Leitfaden zur D2C-Kommunikation.

In diesem Artikel erfahren Sie, wie Sie zwei Azure CLI-Sitzungen erstellen:

  • Eine Sitzung, die ein simuliertes Gerät erstellt. Das simulierte Gerät meldet seinen Konnektivitätskanal bei der Initialisierung als gemeldete Eigenschaft für den entsprechenden Gerätezwilling des Geräts.

  • Eine Sitzung, die die Tags des Gerätezwillings für das simulierte Gerät aktualisiert und dann Geräte von Ihrem IoT Hub abfragt. Die Abfragen verwenden Filter basierend auf den Tags und Eigenschaften, die zuvor in beiden Sitzungen aktualisiert wurden.

Voraussetzungen

  • Azure-Befehlszeilenschnittstelle. Sie können die Befehle in diesem Artikel auch mithilfe von Azure Cloud Shell ausführen. Diese interaktive CLI-Shell kann in Ihrem Browser oder einer Anwendung wie Windows Terminal ausgeführt werden. Bei Verwendung der Cloud Shell müssen Sie nichts installieren. Wenn Sie es vorziehen, die Befehlszeilenschnittstelle lokal zu verwenden, benötigen Sie für diesen Artikel mindestens die Azure CLI-Version 2.36. Führen Sie az --version aus, um die Version zu ermitteln. Informationen zur Installation oder zum Upgrade der Azure CLI finden Sie unter Installieren der Azure CLI.

  • Einen IoT Hub. Erstellen Sie einen mit der CLI oder dem Azure-Portal.

  • Stellen Sie sicher, dass der Port 8883 in Ihrer Firewall geöffnet ist. Die Beispiele in diesem Artikel verwenden das MQTT-Protokoll, das über Port 8883 kommuniziert. In einigen Netzwerkumgebungen einiger Unternehmen oder Bildungseinrichtungen kann dieser Port blockiert sein. Weitere Informationen und Problemumgehungen finden Sie unter Herstellen einer Verbindung mit IoT Hub (MQTT).

Vorbereiten von Cloud Shell

Wenn Sie Azure Cloud Shell verwenden möchten, müssen Sie den Dienst zuerst starten und konfigurieren. Falls Sie die CLI lokal nutzen, können Sie zum Abschnitt Vorbereiten von zwei CLI-Sitzungen springen.

  1. Wählen Sie im Azure-Portal in der Kopfzeile der Seite das Symbol Cloud Shell aus.

    Screenshot: Globale Steuerelemente aus der Kopfzeile des Azure-Portals mit hervorgehobenem Cloud Shell-Symbol

    Hinweis

    Falls Sie die Cloud Shell bisher noch nicht verwendet haben, werden Sie zum Erstellen von Speicher aufgefordert, der für die Nutzung der Cloud Shell erforderlich ist. Wählen Sie ein Abonnement aus, in dem ein Speicherkonto und eine Microsoft Azure Files-Freigabe erstellt werden sollen.

  2. Verwenden Sie die Umgebungsauswahl auf der Cloud Shell-Symbolleiste, um Ihre bevorzugte CLI-Umgebung auszuwählen. In diesem Artikel wird die Bash-Umgebung verwendet. Sie können auch die PowerShell-Umgebung verwenden.

    Hinweis

    Einige Befehle erfordern eine andere Syntax oder Formatierung in der Bash- und der PowerShell-Umgebung. Weitere Informationen finden Sie unter Tipps zur erfolgreichen Verwendung der Azure CLI.

    Screenshot: Azure Cloud Shell-Fenster, in dem die Umgebungsauswahl auf der Symbolleiste hervorgehoben ist

Vorbereiten von zwei CLI-Sitzungen

Als Nächstes müssen Sie zwei Azure CLI-Sitzungen vorbereiten. Wenn Sie Cloud Shell verwenden, führen Sie diese Sitzungen auf separaten Cloud Shell-Registerkarten aus. Wenn Sie einen lokalen CLI-Client nutzen, führen Sie separate CLI-Instanzen aus. Verwenden Sie die separaten CLI-Sitzungen für die folgenden Aufgaben:

  • Die erste Sitzung simuliert ein IoT-Gerät, das mit Ihrem IoT-Hub kommuniziert.
  • Die zweite Sitzung aktualisiert Ihr simuliertes Gerät und fragt Ihren IoT Hub ab.

  1. Wenn Sie die Cloud Shell verwenden, fahren Sie direkt mit dem nächsten Schritt fort. Wenn nicht, führen Sie den Befehl az login in der ersten CLI-Sitzung aus, um sich bei Ihrem Azure-Konto anzumelden.

    Wenn Sie Cloud Shell verwenden, werden Sie automatisch bei Ihrem Azure-Konto angemeldet. Die gesamte Kommunikation zwischen Ihrer Azure CLI-Sitzung und Ihrem IoT-Hub ist authentifiziert und verschlüsselt. Bei diesem Artikel ist daher keine weitere Authentifizierung, z. B. per Verbindungszeichenfolge, wie bei einem echten Gerät erforderlich. Weitere Informationen zum Anmelden mit der Azure-Befehlszeilenschnittstelle finden Sie unter Anmelden mit der Azure CLI.

    az login

  2. Führen Sie in der ersten CLI-Sitzung den Befehl az extension add aus. Der Befehl fügt Ihrer CLI-Shell die Microsoft Azure IoT-Erweiterung für Azure CLI hinzu. Die Erweiterung fügt der Azure-Befehlszeilenschnittstelle spezifische Befehle für IoT Hub, IoT Edge und IoT Device Provisioning Service (DPS) hinzu. Nachdem Sie die Erweiterung installiert haben, müssen Sie sie in Cloud Shell-Sitzungen nicht erneut installieren.

    az extension add --name azure-iot

    Hinweis

    In diesem Artikel wird die neueste Version der Azure IoT-Erweiterung namens azure-iot verwendet. Die Legacy-Version heißt azure-cli-iot-ext. Es sollte jedoch jeweils nur eine Version installiert sein. Sie können den Befehl az extension list verwenden, um die derzeit installierten Erweiterungen zu überprüfen.

    Verwenden Sie az extension remove --name azure-cli-iot-ext, um die Legacy-Version der Erweiterung zu entfernen.

    Verwenden Sie az extension add --name azure-iot, um die neue Version der Erweiterung hinzuzufügen.

    Verwenden Sie az extension list, um die installierten Erweiterungen anzuzeigen.

  3. Öffnen Sie die zweite CLI-Sitzung. Wenn Sie Cloud Shell in einem Browser verwenden, wählen Sie auf der Symbolleiste Ihrer ersten CLI-Sitzung das Symbol Neue Sitzung öffnen aus. Wenn Sie die CLI lokal nutzen, öffnen Sie eine zweite CLI-Instanz.

    Screenshot: Azure Cloud Shell-Fenster, in dem das Symbol „Neue Sitzung öffnen“ auf der Symbolleiste hervorgehoben ist

Erstellen und Simulieren eines Geräts

In diesem Abschnitt erstellen Sie in der ersten CLI-Sitzung eine Geräteidentität für Ihren IoT-Hub und simulieren dann mithilfe dieser Geräteidentität ein Gerät. Das simulierte Gerät reagiert auf die Aufträge, die Sie in der zweiten CLI-Sitzung planen.

Erstellen und starten Sie ein simuliertes Gerät wie folgt:

  1. Führen Sie in der ersten CLI-Sitzung den Befehl az iot hub device-identity create aus, und ersetzen Sie die folgenden Platzhalter durch die entsprechenden Werte. Mit diesem Befehl wird die Geräteidentität für Ihr simuliertes Gerät erstellt.

    {DeviceName}. Der Name Ihres simulierten Geräts.

    {HubName}. Der Name Ihres IoT-Hubs.

    az iot hub device-identity create --device-id {DeviceName} --hub-name {HubName}

  2. Führen Sie in der ersten CLI-Sitzung den Befehl az iot device simulate aus, und ersetzen Sie die folgenden Platzhalter durch die entsprechenden Werte. Mit diesem Befehl wird das Gerät simuliert, das Sie im vorherigen Schritt erstellt haben. Der Befehl konfiguriert auch das simulierte Gerät, damit dieses seinen Konnektivitätskanal bei der Initialisierung als gemeldete Eigenschaft für den entsprechenden Gerätezwilling des Geräts meldet.

    {DeviceName}. Der Name Ihres simulierten Geräts.

    {HubName}. Der Name Ihres IoT-Hubs.

    az iot device simulate --device-id {DeviceName} --hub-name {HubName} \
                       --init-reported-properties '{"connectivity":{"type": "cellular"}}'

    Tipp

    Standardmäßig sendet der Befehl az iot device simulate in einem Intervall von drei Sekunden zwischen Nachrichten 100 Gerät-zu-Cloud-Nachrichten. Die Simulation endet, sobald alle Nachrichten gesendet wurden. Wenn Sie die Simulation länger ausführen möchten, können Sie mithilfe des Parameters --msg-count mehr Nachrichten festlegen. Der Parameter --msg-interval erlaubt es Ihnen, ein längeres Intervall zwischen den Nachrichten festzulegen. Sie können den Befehl auch noch einmal ausführen, um das simulierte Gerät neu zu starten.

Gerätezwilling aktualisieren

Sobald eine Geräteidentität erstellt wurde, wird implizit ein Gerätezwilling in IoT Hub erstellt. In diesem Abschnitt verwenden Sie die zweite CLI-Sitzung, um einen Satz von Tags auf dem Gerätezwilling, der der Geräteidentität zugeordnet ist, die Sie im vorherigen Abschnitt erstellt haben, zu aktualisieren. Sie können Gerätezwillingstags verwenden, um Geräte in Ihren IoT-Lösungen zu organisieren und zu verwalten. Weitere Informationen zum Verwalten von Geräten mithilfe von Tags finden Sie unter Verwalten von Geräten mithilfe von Gerätezwillingstags in Azure IoT Hub.

  1. Vergewissern Sie sich, dass das simulierte Gerät in der ersten CLI-Sitzung ausgeführt wird. Wenn nicht, starten Sie es neu, indem Sie den Befehl az iot device simulate aus dem Abschnitt Erstellen und Simulieren eines Geräts noch einmal ausführen.

  2. Führen Sie in der zweiten CLI-Sitzung den Befehl az iot hub device-twin update aus, und ersetzen Sie die folgenden Platzhalter durch die entsprechenden Werte. In diesem Beispiel aktualisieren wir mehrere Tags auf dem Gerätezwilling für die Geräteidentität, die wir im vorherigen Abschnitt erstellt haben.

    {DeviceName}. Der Name Ihres Geräts.

    {HubName}. Der Name Ihres IoT-Hubs.

    az iot hub device-twin update --device-id {DeviceName} --hub-name {HubName} \
                              --tags '{"location":{"region":"US","plant":"Redmond43"}}'

  3. Stellen Sie in der zweiten CLI-Sitzung sicher, dass in der JSON-Antwort die Ergebnisse des Aktualisierungsvorgangs angezeigt werden. Im folgenden Beispiel einer JSON-Antwort haben wir SampleDevice für den Platzhalter {DeviceName} im CLI-Befehl az iot hub device-twin update verwendet.

    {
  "authenticationType": "sas",
  "capabilities": {
    "iotEdge": false
  },
  "cloudToDeviceMessageCount": 0,
  "connectionState": "Connected",
  "deviceEtag": "MTA2NTU1MDM2Mw==",
  "deviceId": "SampleDevice",
  "deviceScope": null,
  "etag": "AAAAAAAAAAI=",
  "lastActivityTime": "0001-01-01T00:00:00+00:00",
  "modelId": "",
  "moduleId": null,
  "parentScopes": null,
  "properties": {
    "desired": {
      "$metadata": {
        "$lastUpdated": "2023-02-21T10:40:10.5062402Z"
      },
      "$version": 1
    },
    "reported": {
      "$metadata": {
        "$lastUpdated": "2023-02-21T10:40:43.8539917Z",
        "connectivity": {
          "$lastUpdated": "2023-02-21T10:40:43.8539917Z",
          "type": {
            "$lastUpdated": "2023-02-21T10:40:43.8539917Z"
          }
        }
      },
      "$version": 2,
      "connectivity": {
        "type": "cellular"
      }
    }
  },
  "status": "enabled",
  "statusReason": null,
  "statusUpdateTime": "0001-01-01T00:00:00+00:00",
  "tags": {
    "location": {
      "plant": "Redmond43",
      "region": "US"
    }
  },
  "version": 4,
  "x509Thumbprint": {
    "primaryThumbprint": null,
    "secondaryThumbprint": null
  }
}

IoT Hub-Instanz nach Gerätezwillingen abfragen

IoT Hub macht die Gerätezwillinge für Ihre IoT Hub als eine Dokumentensammlung namens Geräte verfügbar. In diesem Abschnitt verwenden Sie die zweite CLI-Sitzung, um zwei Abfragen für den Satz von Gerätezwillingen für Ihren IoT Hub auszuführen: Die erste Abfrage wählt nur die Gerätezwillinge von Geräten aus, die sich im Werk Redmond43 befinden, und die zweite optimiert die Abfrage so, dass nur die Geräte ausgewählt werden, die darüber hinaus über ein Mobilfunknetz verbunden sind. Beide Abfragen geben nur die ersten 100 Geräte im Resultset zurück. Weitere Informationen zu Abfragen von Gerätezwillingen finden Sie unter Abfragen für IoT Hub Geräte- und Modulzwillingen.

  1. Vergewissern Sie sich, dass das simulierte Gerät in der ersten CLI-Sitzung ausgeführt wird. Wenn nicht, starten Sie es neu, indem Sie den Befehl az iot device simulate aus dem Abschnitt Erstellen und Simulieren eines Geräts noch einmal ausführen.

  2. Führen Sie in der zweiten CLI-Sitzung den Befehl az iot hub query aus, und ersetzen Sie die folgenden Platzhalter durch die entsprechenden Werte. In diesem Beispiel filtern wir die Abfrage so, dass nur die Gerätezwillinge von Geräten zurückgegeben werden, die sich im Werk Redmond43 befinden.

    {HubName}. Der Name Ihres IoT-Hubs.

    az iot hub query --hub-name {HubName} \
                 --query-command "SELECT * FROM devices WHERE tags.location.plant = 'Redmond43'" \
                 --top 100

  3. Stellen Sie in der zweiten CLI-Sitzung sicher, dass in der JSON-Antwort die Ergebnisse der Abfrage angezeigt werden.

    {
  "authenticationType": "sas",
  "capabilities": {
    "iotEdge": false
  },
  "cloudToDeviceMessageCount": 0,
  "connectionState": "Connected",
  "deviceEtag": "MTA2NTU1MDM2Mw==",
  "deviceId": "SampleDevice",
  "deviceScope": null,
  "etag": "AAAAAAAAAAI=",
  "lastActivityTime": "0001-01-01T00:00:00+00:00",
  "modelId": "",
  "moduleId": null,
  "parentScopes": null,
  "properties": {
    "desired": {
      "$metadata": {
        "$lastUpdated": "2023-02-21T10:40:10.5062402Z"
      },
      "$version": 1
    },
    "reported": {
      "$metadata": {
        "$lastUpdated": "2023-02-21T10:40:43.8539917Z",
        "connectivity": {
          "$lastUpdated": "2023-02-21T10:40:43.8539917Z",
          "type": {
            "$lastUpdated": "2023-02-21T10:40:43.8539917Z"
          }
        }
      },
      "$version": 2,
      "connectivity": {
        "type": "cellular"
      }
    }
  },
  "status": "enabled",
  "statusReason": null,
  "statusUpdateTime": "0001-01-01T00:00:00+00:00",
  "tags": {
    "location": {
      "plant": "Redmond43",
      "region": "US"
    }
  },
  "version": 4,
  "x509Thumbprint": {
    "primaryThumbprint": null,
    "secondaryThumbprint": null
  }
}

  4. Führen Sie in der zweiten CLI-Sitzung den Befehl az iot hub query aus, und ersetzen Sie die folgenden Platzhalter durch die entsprechenden Werte. In diesem Beispiel filtern wir die Abfrage so, dass nur die Gerätezwillinge von Geräten im Werk Redmond43 zurückgegeben werden, die darüber hinaus über ein Mobilfunknetz verbunden sind.

    {HubName}. Der Name Ihres IoT-Hubs.

    az iot hub query --hub-name {HubName} \
                 --query-command "SELECT * FROM devices WHERE tags.location.plant = 'Redmond43' \
                                  AND properties.reported.connectivity.type = 'cellular'" \
                 --top 100

  5. Stellen Sie in der zweiten CLI-Sitzung sicher, dass in der JSON-Antwort die Ergebnisse der Abfrage angezeigt werden. Die Ergebnisse dieser Abfrage sollten mit den Ergebnissen der vorherigen Abfrage in diesem Abschnitt übereinstimmen.

In diesem Artikel führen Sie folgende Schritte aus:

  • Fügte Gerätemetadaten als Tags aus einer Azure CLI-Sitzung hinzu
  • Simulierte ein Gerät, das Informationen zur Gerätekonnektivität im Gerätezwilling meldete
  • Sie haben zudem erfahren, wie die Gerätezwillingsinformationen mithilfe der SQL-ähnlichen IoT Hub-Abfragesprache in einer Azure CLI-Sitzung abgefragt werden können.

Nächste Schritte

Eine entsprechende Anleitung