Verwalten von Gerätegruppen in Device Update for IoT Hub

Device Update for IoT Hub ermöglicht die Bereitstellung eines Updates für eine Gruppe von IoT-Geräten. Dieser Schritt ist optional, wenn Sie Updates auf Ihren verwalteten Geräten bereitstellen. Sie können Updates auf Ihren Geräten mithilfe der für Sie erstellten Standardgruppe bereitstellen. Alternativ können Sie Ihren Geräten ein benutzerdefiniertes Tag zuweisen, das – basierend auf dem Tag und den Gerätekompatibilitätseigenschaften – automatisch gruppiert wird.

Hinweis

Wenn Sie die Bereitstellung in einer Standardgruppe statt in einer vom Benutzer erstellten Gruppe durchführen möchten, setzen Sie den Vorgang mit Bereitstellen eines Updates fort.

Voraussetzungen

• Greifen Sie auf einen IoT-Hub mit aktiviertem Device Update for IoT Hub zu. Wir empfehlen, für Ihre IoT Hub-Instanz den S1-Tarif (Standard) oder höher zu verwenden.
• Ein IoT-Gerät (oder Simulator), das/der für Device Update in IoT Hub bereitgestellt wird.
  • Installieren und starten Sie den Device Update-Agent auf Ihrem IoT-Gerät als eine Identität auf Modul- oder Geräteebene.
• Ein importiertes Update für das bereitgestellte Gerät.

Azure portal

Unterstützte Browser:

• Microsoft Edge
• Google Chrome

Azure-Befehlszeilenschnittstelle

Eine Azure CLI-Umgebung:

• Verwenden Sie die Bash-Umgebung in Azure Cloud Shell.

  

• Wenn Sie CLI-Referenzbefehle lieber lokal ausführen, installieren Sie die Azure CLI

  1. Melden Sie sich mit dem Befehl az login bei der Azure CLI an.
  2. Führen Sie az version aus, um die installierte Version und die abhängigen Bibliotheken zu ermitteln. Führen Sie az upgrade aus, um das Upgrade auf die aktuelle Version durchzuführen.
  3. Installieren Sie die Azure CLI-Erweiterungen bei der ersten Verwendung, wenn Sie dazu aufgefordert werden. Die Befehle in diesem Artikel verwenden die azure-iot-Erweiterung . Führen Sie az extension update --name azure-iot aus, um sicherzustellen, dass Sie die neueste Version der Erweiterung verwenden.

Hinzufügen eines Tags zu Ihren Geräten

Zum Erstellen einer Gerätegruppe müssen Sie als ersten Schritt dem Zielsatz von Geräten in IoT Hub ein Tag hinzufügen. Tags können Ihrem Gerät nur erfolgreich hinzugefügt werden, nachdem eine Verbindung mit Device Update hergestellt wurde.

Geräteupdatetags verwenden das Format im folgenden Beispiel:

"etag": "",
"deviceId": "",
"deviceEtag": "",
"version": <version>,
"tags": {
   "ADUGroup": "<CustomTagValue>"
}

Weitere Informationen und Beispiele zur JSON-Syntax für Zwillinge finden Sie unter Verstehen und Verwenden von Gerätezwillingen bzw. Verstehen und Verwenden von Modulzwillingen.

In den folgenden Abschnitten werden verschiedene Möglichkeiten zum Hinzufügen und Aktualisieren von Tags beschrieben.

Hinzufügen von Tags mit SDKs

Nachdem Sie das Gerät bei Device Update registriert haben, können Sie den Geräte- oder Modulzwilling mithilfe von RegistryManager mit dem entsprechenden Tag aktualisieren. Weitere Informationen finden Sie in den folgenden Artikeln:

• Weitere Informationen zum Hinzufügen von Tags mithilfe einer .NET-Beispiel-App.
• Weitere Informationen zu Tageigenschaften.

Fügen Sie Tags dem Gerätezwilling hinzu, wenn Ihr Device Update-Agent mit Geräteidentität bereitgestellt wird, oder dem entsprechenden Modulzwilling hinzu, wenn der Device Update-Agent mit einer Modulidentität bereitgestellt wird.

Hinzufügen von Tags mithilfe von Aufträgen

Sie können einen Auftrag auf mehreren Geräten planen, um ein Device Update-Tag hinzuzufügen oder zu aktualisieren. Beispiele für Auftragsvorgänge finden Sie unter Planen von Aufträgen auf mehreren Geräten. Sie können entweder Gerätezwillinge oder Modulzwillinge mithilfe von Aufträgen aktualisieren – je nachdem, ob der Device Update-Agent mit einer Geräte- oder Modulidentität bereitgestellt wird.

Weitere Informationen finden Sie unter Planen und Übertragen von Aufträgen.

Hinweis

Diese Aktion wird auf Ihr IoT Hub-Nachrichtenkontingent angerechnet. Wir empfehlen, jeweils nur bis zu 50.000 Geräte- oder Modulzwillingstags zu ändern. Andernfalls müssen Sie möglicherweise weitere IoT Hub-Einheiten erwerben, wenn Sie Ihr tägliches IoT Hub-Nachrichtenkontingent überschreiten. Weitere Informationen finden Sie unter Kontingente und Drosselung.

Hinzufügen von Tags durch Aktualisieren von Zwillingen

Tags können auch direkt in Geräte- oder Modulzwillingen hinzugefügt oder aktualisiert werden.

Azure portal

1. Navigieren Sie im Azure-Portal zu Ihrem IoT Hub.

2. Suchen Sie im linken Navigationsbereich über Geräte oder IoT Edge nach Ihrem IoT-Gerät. Navigieren Sie entweder zum Gerätezwilling oder zum Device Update-Modul und dann zu dessen Modulzwilling – je nachdem, ob der Device Update-Agent mit einer Geräte- oder Modulidentität bereitgestellt wird.

3. Löschen Sie in den Zwillingsdetails alle vorhandenen Device Update-Tagwerte, indem Sie sie auf „NULL“ festlegen.

4. Fügen Sie wie unten gezeigt einen neuen Device Update-Tagwert hinzu.

       "tags": {
               "ADUGroup": "<CustomTagValue>"
               }
   

Azure-Befehlszeilenschnittstelle

Verwenden Sie az iot hub device-twin update oder az iot hub module-twin update, um einem Gerät- oder Modulzwilling ein Tag hinzuzufügen.

Bei beiden update-Befehlen akzeptiert das Argument --tags entweder Inline-JSON oder einen Dateipfad zu JSON-Inhalten.

Beispiel:

az iot hub module-twin update \
    --hub-name <IoT Hub name> \
    --device-id <device name> \
    --module-id <module name> \
    --tags '{"ADUGroup": "<custom_tag_value"}'

Einschränkungen

• Sie können Ihrem Tag jeden beliebigen Wert hinzufügen – mit Ausnahme von Uncategorized und $default, die reservierte Werte sind.
• Der Tagwert darf maximal 200 Zeichen enthalten.
• Der Tagwert kann alphanumerische Zeichen und die folgenden Sonderzeichen enthalten: . - _ ~.
• Für Tag- und Gruppennamen wird Groß-/Kleinschreibung beachtet.
• Ein Gerät kann nur ein Tag mit dem Namen „ADUGroup“ haben. Durch Hinzufügen eines Tags mit diesem Namen wird der vorhandene Wert für das Tag „ADUGroup“ außer Kraft gesetzt.
• Ein Gerät kann nur zu einer Gruppe gehören.

Anzeigen von Gerätegruppen

Gruppen werden – basierend auf den zugewiesenen Tags und den Kompatibilitätseigenschaften der Geräte – automatisch erstellt. Bei einer Gruppe kann es mehrere Untergruppen mit unterschiedlichen Geräteklassen geben.

Azure portal

1. Navigieren Sie im Azure-Portal zu dem IoT Hub, den Sie zuvor mit Ihrer Device Update-Instanz verbunden haben.

2. Wählen Sie in der linken Navigationsleiste unter Geräteverwaltung die Option Updates aus.

3. Wählen Sie die Registerkarte Gruppen und Bereitstellungen aus.

   

4. Sobald eine Gruppe erstellt wurde, sehen Sie, dass das Konformitätsdiagramm und die Gruppenliste aktualisiert werden. Das Konformitätsdiagramm „Device Update“ zeigt die Anzahl von Geräten in verschiedenen Konformitätszuständen: Mit neuestem Update, Neue Updates verfügbar und Updates werden ausgeführt. Weitere Informationen finden Sie unter Konformität von Device Update.

   

5. In der Gruppenliste sollten vorhandene Gruppen und alle verfügbaren Updates für die darin enthaltenen Geräte angezeigt werden. Wenn Geräte vorhanden sind, die die Geräteklassenanforderungen der Gruppe nicht erfüllen, werden sie in einer entsprechenden Gruppe ungültiger Geräte angezeigt. Sie können für eine Gruppe aus dieser Ansicht das beste verfügbare Update bereitstellen, indem Sie neben der Gruppe die Schaltfläche Bereitstellen auswählen.

Azure-Befehlszeilenschnittstelle

Verwenden Sie az iot du device group list zum Anzeigen aller Gerätegruppen in einer Device Update-Instanz.

az iot du device group list \
    --account <Device Update account name> \
    --instance <Device Update instance name>

Mithilfe des Arguments --order-by können Sie die zurückgegebenen Gruppen – basierend auf Aspekten wie Gruppen-ID, Anzahl von Geräten oder Anzahl von Untergruppen – mit neuen verfügbaren Updates sortieren.

Anzeigen von Gerätedetails für eine Gruppe

Azure portal

1. Wählen Sie auf der Registerkarte Gruppen und Bereitstellungen den Namen der Gruppe aus, die Sie anzeigen möchten.

2. Auf der Seite mit den Gruppendetails können Sie eine Liste der Geräte, die zur Gruppe gehören, zusammen mit deren Device Update-Eigenschaften sehen. In dieser Ansicht können Sie auch die Updatekonformitätsinformationen für alle Geräte anzeigen, die Mitglieder der Gruppe sind. Das Konformitätsdiagramm zeigt die Anzahl der Geräte in verschiedenen Konformitätszuständen.

   

3. Sie können auch ein einzelnes Gerät innerhalb einer Gruppe auswählen, um in IoT Hub auf die Seite mit den Gerätedetails umgeleitet zu werden.

   

   

Azure-Befehlszeilenschnittstelle

Verwenden Sie az iot du device group show zum Anzeigen von Details einer bestimmten Gerätegruppe.

Das optionale --best-updates Flag gibt eine Liste der besten verfügbaren Updates für die Gerätegruppe zurück, einschließlich der Anzahl der Geräte, die jedes Update benötigen.

Das optionale Flag --update-compliance gibt Konformitätsinformationen für die Gerätegruppe zurück – einschließlich der Anzahl der Geräte, die das neueste Update verwenden, der Geräte, die neue Updates benötigen, und der Geräte, bei denen gerade ein neues Update durchgeführt wird.

az iot du device group show \
    --account <Device Update account name> \
    --instance <Device Update instance name> \
    --group-id <value of the ADUGroup tag for this group>

Entfernen eines Geräts aus einer Gerätegruppe

Um ein Gerät aus einer Gerätegruppe zu entfernen, muss der ADUGroup-Tagwert in „null“ geändert werden.

    "tags": {
            "ADUGroup": "null"
            }

Dadurch wird das ADUGroup-Tag vom Gerätezwilling gelöscht und das Gerät aus der Gerätegruppe entfernt.

Löschen von Gerätegruppen

Gerätegruppen werden zwar automatisch erstellt, Gruppen, Geräteklassen und Bereitstellungen werden aber nicht automatisch bereinigt, um sie für Verlaufsdatensätze oder andere Benutzeranforderungen beizubehalten. Gerätegruppen können über das Azure-Portal gelöscht werden, indem Sie die gewünschten Gruppen einzeln auswählen und löschen oder die DELETE-API für die Gruppe aufrufen. Weitere Informationen

Wenn nach dem Löschen der Gruppe ein Gerät daraus erneut verbunden wird, wird die Gruppe zwar automatisch neu erstellt, es gibt aber keinen zugeordneten Geräte- oder Bereitstellungsverlauf mehr.

Für das Löschen muss eine Gruppe die folgenden Anforderungen erfüllen:

• Die Gruppe dar KEINE Mitgliedsgeräte enthalten. Dies bedeutet, dass kein in der Device Update-Instanz bereitgestelltes Gerät über ein ADUGroup-Tag mit einem Wert verfügen darf, der dem Namen der ausgewählten Gruppe entspricht.
• Die Gruppe darf KEINE Standardgruppe sein.
• Der Gruppe dürfen KEINE aktiven oder abgebrochenen Bereitstellungen zugeordnet sein.

Hinweis

Wenn Sie eine Gruppe auch nach Erfüllung der oben genannten Anforderungen nicht löschen können, überprüfen Sie, ob fehlerhafte Geräte vorhanden sind, die Mitglied der Gruppe sind. Fehlerhafte Geräte sind Geräte, die keine Bereitstellung empfangen können und daher nicht direkt in der Liste der Mitgliedergeräte innerhalb einer Gruppe angezeigt werden. Sie können überprüfen, ob Sie über fehlerhafte Geräte verfügen, indem Sie auf der Registerkarte „Diagnose“ im Device Update-Portal zu „Fehlende Geräte suchen“ navigieren. Falls Sie fehlerhafte Geräte haben, die als Teil der Gruppe markiert sind, müssen Sie den Tagwert ändern oder das Gerät vollständig löschen, bevor Sie Ihre Gruppe löschen können.

Nächste Schritte

• Bereitstellen eines Updates

• Weitere Informationen zu Gerätegruppen

• Weitere Informationen zur Konformität von Device Update