Verwalten von Gerätegruppen für Azure Device Update for IoT Hub

Azure Device Update for IoT Hub ermöglicht die Bereitstellung von Updates für benutzerdefinierte Gruppen von IoT-Geräten. Jedes verwaltete Gerät für Geräteupdates ist Mitglied einer Gerätegruppe, aber das Definieren von Gerätegruppen ist optional. Sie können alternativ für die Standardgerätegruppe bereitstellen, die von Device Update bereitgestellt wird.

Wenn Sie benutzerdefinierte Geräteupdate-Tagwerte für Geräte erstellen und zuweisen, erstellt Device Update automatisch Gruppen basierend auf den zugewiesenen Tags und Gerätekompatibilitätseigenschaften. Für jede Gerätegruppe kann Die Geräteaktualisierung mehrere Untergruppen mit unterschiedlichen Geräteklassen erstellen. Geräteaktualisierung platziert Geräte ohne Tags in der default Gerätegruppe.

In diesem Artikel wird beschrieben, wie Sie das Azure-Portal oder die Azure CLI verwenden, um benutzerdefinierte Geräteupdate-Gerätetags und -gruppen zu erstellen und zu verwalten. Informationen zum Bereitstellen von Updates für benutzerdefinierte oder Standardgerätegruppen finden Sie unter Bereitstellen eines Geräteupdates.

Voraussetzungen

Bevor Sie beginnen, beachten Sie die folgenden Voraussetzungen:

Geräte müssen erfolgreich für Device Update eingebunden werden, bevor eine Gruppenzuweisung erfolgen kann.
Geräte müssen eine unterstützte Plug & Play-Modell-ID angeben. Eine Liste der unterstützten Modell-IDs finden Sie unter Device Update Models.
Für IoT Edge-Szenarien läuft der Device Update Agent als Modul und muss die Modell-ID über die entsprechende Identität melden.

Azure Portal
Azure-Befehlszeilenschnittstelle

Eine Standardinstanz (S1) oder eine höhere Instanz von Azure IoT Hub, für die Device Update for IoT Hub aktiviert ist.
Ein für Device Update bereitgestelltes IoT-Gerät oder ein entsprechender Simulator im IoT-Hub.
Der Geräteupdate-Agent wurde auf dem Gerät entweder als Modul- oder Geräteebenenidentität installiert und gestartet.
Ein importiertes Update für das bereitgestellte Gerät.

Eine Standardinstanz (S1) oder eine höhere Instanz von Azure IoT Hub, für die Device Update for IoT Hub aktiviert ist.
Ein für Device Update bereitgestelltes IoT-Gerät oder ein entsprechender Simulator im IoT-Hub.
Der Geräteupdate-Agent wurde auf dem Gerät entweder als Modul- oder Geräteebenenidentität installiert und gestartet.
Ein importiertes Update für das bereitgestellte Gerät.
Die Bash-Umgebung in Azure Cloud Shell zum Ausführen von Azure CLI-Befehlen. Wählen Sie Cloud Shell starten aus, um Cloud Shell zu öffnen, oder wählen Sie das Cloud Shell-Symbol auf der oberen Symbolleiste des Azure-Portals aus.
Hinweis

Wenn Sie möchten, können Sie die Azure CLI-Befehle lokal ausführen:
1. Azure CLI installieren. Führen Sie az version aus, um die installierte Azure CLI-Version und abhängige Bibliotheken anzuzeigen, und führen Sie az upgrade aus, um die aktuelle Version zu installieren.
2. Melden Sie sich bei Azure an, indem Sie az login ausführen.
3. Installieren Sie bei der ersten Verwendung die Erweiterung azure-iot, wenn Sie dazu aufgefordert werden. Um sicherzustellen, dass Sie die aktuelle Version der Erweiterung verwenden, führen Sie az extension update --name azure-iot aus.

Hinzufügen von Tags zu Ihren Geräten

Um eine Device Update-Gerätegruppe zuzuweisen, fügen Sie das ADUGroup Tag einem Zielsatz von Device Update-verbundenen Geräten im IoT Hub hinzu. Fügen Sie das Tag dem Gerätezwilling hinzu, wenn Ihr Device Update-Agent mit einer Geräteidentität konfiguriert ist, oder dem entsprechenden Modulzwilling, wenn der Device Update-Agent mit einer Modulidentität konfiguriert ist.

Das Device Update-Tag ADUGroup verwendet ein Schlüsselwertformat, wie im folgenden Beispiel für Gerät oder Modulzwilling gezeigt:

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

Important

Das Hinzufügen eines ADUGroup Tags führt nicht dazu, dass ein Gerät in Device Update integriert wird. Die Gruppenzuweisung erfolgt nur, nachdem das Geräteupdate das Gerät erfolgreich erkannt und verwaltet hat.

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.

Das ADUGroup Tag weist die folgenden Eigenschaften und Einschränkungen auf:

Ein Gerät kann jeweils nur ein ADUGroup-Tag haben und jeweils nur zu einer Device Update-Gruppe gehören. Durch Hinzufügen eines weiteren Tags mit dem Namen ADUGroup wird der vorhandene ADUGroup Wert außer Kraft gesetzt.
Sie können einen beliebigen Wert für das Tag verwenden, mit Ausnahme der reservierten Werte Uncategorized und $default.
Der Tagwert darf maximal 200 Zeichen enthalten.
Der Tagwert darf alphanumerische Zeichen und die folgenden Sonderzeichen enthalten: . - _ ~.
Bei den Werten für ADUGroup-Tagnamen und -Gruppennamen wird die Groß-/Kleinschreibung berücksichtigt.

In den folgenden Abschnitten werden verschiedene Möglichkeiten zum Hinzufügen und Aktualisieren des 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:

Hinzufügen von Tags mithilfe von Aufträgen

Sie können Aufträge planen, um Geräteupdatetags auf mehreren Geräten 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

Dieser Vorgang wird auf Ihr IoT Hub-Nachrichtenkontingent angerechnet. Wenn Sie 50.000 oder mehr Geräte- oder Modul-Twin-Tags gleichzeitig ändern, überschreiten Sie möglicherweise Ihr tägliches IoT Hub-Nachrichtenkontingent und müssen weitere IoT Hub-Einheiten kaufen. Weitere Informationen finden Sie unter Kontingente und Drosselung.

Hinzufügen von Tags durch Aktualisieren von Zwillingen

Sie können das ADUGroup Tag auch direkt im Gerät oder Modul Twin hinzufügen oder aktualisieren.

Azure Portal
Azure-Befehlszeilenschnittstelle

Navigieren Sie im Azure-Portal zu Ihrem IoT Hub.
Wählen Sie im linken Navigationsbereich unter Geräteverwaltung die Option Geräte aus. Wenn Sie über ein IoT Edge-Gerät verfügen, wählen Sie stattdessen IoT Edge aus.
Wählen Sie auf der Seite Geräte Ihr Gerät aus.
Wählen Sie auf der Geräteseite im oberen Menü entweder Gerätezwilling aus, oder wählen Sie unter Modulidentitäten die Modulidentität und dann den Modulzwilling aus.
Fügen Sie im Zwilling das Tag ADUGroup mit einem benutzerdefinierten Wert hinzu. Um einen vorhandenen ADUGroup Tagwert zu aktualisieren, überschreiben Sie ihn mit einem anderen benutzerdefinierten Wert.
```
    "tags": {
            "ADUGroup": "<CustomTagValue>"
            }
```
Wählen Sie Speichern.

Verwenden Sie az iot hub device-twin update oder az iot hub module-twin update, um das ADUGroup Tag dem Gerät oder Modul Twin mit einem geeigneten Wert hinzuzufügen. Für beide update Befehle akzeptiert das --tags Argument entweder inline JSON oder einen Pfad zu einer JSON-Datei.

Zum 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"}'

Im Azure-Portal gehen Sie zum IoT-Hub, der mit Ihrer Device Update Instanz verbunden ist.
Wählen Sie im linken Navigationsbereich die Option "Updates" unter "Geräteverwaltung " aus.
Wählen Sie die Registerkarte Gruppen und Bereitstellungen aus.

Wenn du eine Gruppe erstellst, aktualisieren sich das Compliance-Diagramm und die Gruppenliste. 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.

Die Gruppenliste zeigt bestehende Geräte-Update-Gruppen und alle verfügbaren Updates für die Geräte in diesen Gruppen. Geräte, die die Geräteklassenanforderungen der Gruppe nicht erfüllen, erscheinen in einer entsprechenden ungültigen Gruppe. Sie können für eine Gruppe aus dieser Ansicht das beste verfügbare Update bereitstellen, indem Sie neben der Gruppe Bereitstellen auswählen.

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>

Verwenden Sie das Argument, --order-by um die zurückgegebene Liste nach Gruppen-ID, Anzahl der Geräte oder Anzahl der Untergruppen mit neuen verfügbaren Updates zu ordnen.

Anzeigen von Gerätedetails für eine Gruppe

Azure Portal
Azure-Befehlszeilenschnittstelle

Wählen Sie auf der Registerkarte "Gruppen und Bereitstellungen " den Namen der Gruppe aus.

Auf der Seite "Gruppendetails " wird das Updatekonformitätsdiagramm mit der Anzahl von Gruppenmitgliedsgeräten in verschiedenen Konformitätszuständen und der Liste der Gruppenmitgliedsgeräte mit ihren Geräteaktualisierungseigenschaften angezeigt.
Wählen Sie ein einzelnes Gerät in einer Gruppe aus, um zur Seite mit den Gerätedetails im IoT Hub zu wechseln.

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 --update-compliance-Flag gibt Compliance-Informationen für die Gerätegruppe zurück, einschließlich der Anzahl der Geräte, die auf dem neuesten Stand sind, neue Updates benötigen oder bei denen Updates gerade ausgeführt werden.

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>
    --best-updates
    --update-compliance

Entfernen eines Geräts aus einer Gerätegruppe

Wenn Sie ein Gerät aus einer Gerätegruppe entfernen möchten, ändern Sie den Tag-Wert ADUGroup in null im Zwilling und wählen Sie dann Speichern aus.

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

Diese Aktion löscht das Gruppen-Tag aus dem Gerätezwilling und entfernt das Gerät aus der Gerätegruppe.

Löschen einer Gerätegruppe

Device Update erstellt automatisch Gerätegruppen und behält Gerätegruppen, Geräteklassen und Bereitstellungen für historische Datensätze oder andere Benutzeranforderungen bei, anstatt sie automatisch zu bereinigen. Sie können Gerätegruppen über das Azure-Portal löschen, indem Sie die Gruppen einzeln auswählen und löschen oder den az iot du device group delete Azure CLI-Befehl für die Gruppe aufrufen.

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

Darf keine default-Gruppe sein.
Darf keine Mitgliedsgeräte haben. Das heißt, kein Gerät, das in der Device Update-Instanz bereitgestellt wird, kann ein ADUGroup Tag mit einem Wert aufweisen, der dem Namen der Gruppe entspricht.
Es dürfen keine zugeordneten aktiven oder stornierten Bereitstellungen vorhanden sein.

Hinweis

Wenn Sie eine Gruppe, die die vorherigen Anforderungen erfüllt, nicht löschen können, überprüfen Sie, ob fehlerhafte Geräte als Teil der Gruppe gekennzeichnet sind. Nicht funktionsfähige Geräte können keine Bereitstellung erhalten und werden daher nicht direkt in der Liste der Mitgliedsgeräte einer Gruppe angezeigt.

So überprüfen Sie, ob Sie Geräte mit Problemen haben:

Navigieren Sie im Azure-Portal zu Ihrem IoT Hub.
Wählen Sie im linken Navigationsbereich Updates aus, und wählen Sie dann die Registerkarte Diagnose aus.
Erweitern Sie den Abschnitt Fehlende Geräte suchen.

Wenn Sie fehlerhafte Geräte als Teil der Gruppe markiert haben, müssen Sie den Tag-Wert ändern oder das Gerät löschen, bevor Sie die Gruppe löschen können.

Wenn einem gelöschten Gruppennamen jemals ein Gerät zugewiesen wird, erstellt Device Update die Gruppe automatisch neu, es gibt jedoch keinen zugeordneten Geräte- oder Bereitstellungsverlauf.

Troubleshooting

Wenn du ein Gerät markierst, aber keine Gruppe siehst, probiere die folgenden Schritte zur Fehlerbehebung aus:

Überprüfen Sie, ob das Tag korrekt konfiguriert ist.
Überprüfen Sie, ob das Gerät eine gültige Plug & Play-Modell-ID und ein gültiges ADUGroup Etikett enthält.
Bestätigen Sie, dass die Nachrichtenrouten des IoT Hub korrekt konfiguriert sind. Für weitere Informationen siehe Nachrichtenrouten.
Stellen Sie sicher, dass der IoT Hub korrekt mit der Device Update Instanz verknüpft ist.
Führe Geräte-Update-Diagnosen und die Agentenprüfung durch.
Führe bei Bedarf eine Gerätesynchronisation durch.

Weitere Informationen finden Sie unter Plug & Play in Azure Device Update und Device Update for Azure IoT Hub Agent Check.

Feedback

War diese Seite hilfreich?

Zuletzt aktualisiert um 2026-09-17