Erste Schritte mit Gerätezwillingen (Azure CLI)
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:
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.
Wählen Sie im Azure-Portal in der Kopfzeile der Seite das Symbol Cloud Shell aus.
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.
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.
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.
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
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ßtazure-cli-iot-ext
. Es sollte jedoch jeweils nur eine Version installiert sein. Sie können den Befehlaz 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.Ö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.
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:
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}
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.
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.
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"}}'
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-Befehlaz 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.
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.
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
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 } }
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
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
Zum Senden von Telemetriedaten von Geräten finden Sie im Schnellstart: Senden von Telemetriedaten von einem IoT Plug & Play-Gerät an Azure IoT Hub.
Konfigurieren Sie Geräte mit den gewünschten Eigenschaften des Gerätezwillings, siehe Tutorial: Konfigurieren Sie Ihre Geräte über einen Back-End-Diens.
Steuern von Geräten interaktiv, z. B. das Aktivieren eines Lüfters von einer benutzergesteuerten App, finden Sie unter Schnellstart: Steuern eines Geräts, das mit einem IoT-Hub verbunden ist.