Hantera enhetsgrupper för Azure Device Update för IoT Hub

Med Azure Device Update för IoT Hub kan du distribuera uppdateringar till användardefinierade grupper av IoT-enheter. Varje enhetsuppdateringshanterad enhet är medlem i en enhetsgrupp, men det är valfritt att definiera enhetsgrupper. Du kan också distribuera till standardenhetsgruppen som enhetsuppdatering tillhandahåller.

Om du skapar och tilldelar användardefinierade taggvärden för enhetsuppdatering till enheter skapar Enhetsuppdatering automatiskt grupper baserat på de tilldelade taggarna och egenskaperna för enhetskompatibilitet. För varje enhetsgrupp kan Enhetsuppdatering skapa flera undergrupper som har olika enhetsklasser. Enhetsuppdatering placerar enheter som inte har några taggar i default enhetsgruppen.

Den här artikeln beskriver hur du använder Azure Portal eller Azure CLI för att skapa och hantera användardefinierade enhetstaggar och grupper för enhetsuppdatering. Information om hur du distribuerar uppdateringar till användardefinierade eller standardenhetsgrupper finns i Distribuera en enhetsuppdatering.

Förutsättningar

Azure-portalen

• En standardinstans (S1) eller en högre instans av Azure IoT Hub med Enhetsuppdatering för IoT Hub aktiverad.
• En IoT-enhet eller simulator som etablerats för Enhetsuppdatering i IoT-hubben.
• Enhetsuppdateringsagenten har installerats och startats på enheten antingen som en identitet på modul- eller enhetsnivå.
• En importerad uppdatering för den etablerade enheten.

Azure CLI

• En standardinstans (S1) eller en högre instans av Azure IoT Hub med Enhetsuppdatering för IoT Hub aktiverad.

• En IoT-enhet eller simulator som etablerats för Enhetsuppdatering i IoT-hubben.

• Enhetsuppdateringsagenten har installerats och startats på enheten antingen som en identitet på modul- eller enhetsnivå.

• En importerad uppdatering för den etablerade enheten.

• Bash-miljön i Azure Cloud Shell för att köra Azure CLI-kommandona. Välj Starta Cloud Shell för att öppna Cloud Shell eller välj Cloud Shell-ikonen i det översta verktygsfältet i Azure Portal.

  

  Kommentar

  Om du vill kan du köra Azure CLI-kommandon lokalt:

  1. Installera Azure CLI. Kör az version för att se den installerade Azure CLI-versionen och beroende bibliotek och kör az upgrade för att installera den senaste versionen.
  2. Logga in på Azure genom att köra az login.
  3. azure-iot Installera tillägget när du uppmanas att använda det första. Kontrollera att du använder den senaste versionen av tillägget genom att köra az extension update --name azure-iot.

Lägga till taggar på dina enheter

Om du vill tilldela en enhetsgrupp för enhetsuppdatering lägger du till taggen ADUGroup i en måluppsättning med enheter som är anslutna till Enhetsuppdatering i IoT Hub. Lägg till taggen i enhetstvillingen om enhetsuppdateringsagenten har etablerats med enhetsidentitet eller till motsvarande modultvilling om enhetsuppdateringsagenten etableras med en modulidentitet.

Taggen Enhetsuppdatering ADUGroup använder ett nyckelvärdesformat, enligt följande exempel på enhets- eller modultvilling:

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

Mer information och exempel på tvilling-JSON-syntax finns i Förstå och använda enhetstvillingar eller Förstå och använda modultvillingar.

Taggen ADUGroup har följande egenskaper och begränsningar:

• En enhet kan bara ha en ADUGroup tagg och tillhör endast en enhetsuppdateringsgrupp i taget. Om du lägger till en annan tagg med namnet ADUGroup åsidosätts det befintliga ADUGroup värdet.
• Du kan använda valfritt värde för taggen förutom de reserverade värdena Uncategorized och $default.
• Taggvärdet får inte överstiga 200 tecken.
• Taggvärdet kan innehålla alfanumeriska tecken och följande specialtecken: . - _ ~.
• Värdena ADUGroup för taggnamn och gruppnamn är skiftlägeskänsliga.

I följande avsnitt beskrivs flera sätt att lägga till och uppdatera taggen.

Lägga till taggar med SDK:er

Du kan uppdatera enhets- eller modultvillingen med lämplig tagg med Hjälp av RegistryManager när du har registrerat enheten med Enhetsuppdatering. Mer information finns i följande artiklar:

• Kom igång med enhetstvillingar med hjälp av .NET
• Förstå taggar och egenskapsformat

Lägga till taggar med jobb

Du kan schemalägga jobb för att lägga till eller uppdatera taggar för enhetsuppdatering på flera enheter. Exempel på jobbåtgärder finns i Schemalägga jobb på flera enheter. Du kan uppdatera antingen enhetstvillingar eller modultvillingar med hjälp av jobb, beroende på om enhetsuppdateringsagenten har etablerats med en enhets- eller modulidentitet. Mer information finns i Schemalägg och sända jobb.

Kommentar

Den här åtgärden räknas mot din IoT Hub-meddelandekvot. Om du ändrar 50 000 eller fler taggar för enhets- eller modultvillingar åt gången kan du överskrida din dagliga IoT Hub-meddelandekvot och behöva köpa fler IoT Hub-enheter. Mer information finns i Kvoter och begränsning.

Lägga till taggar genom att uppdatera tvillingar

Du kan också lägga till eller uppdatera taggen ADUGroup direkt i enheten eller modultvillingen.

Azure-portalen

1. I Azure Portal, navigerar du till din IoT-hubb.

2. Välj Enheter under Enhetshantering i det vänstra navigeringsfönstret. Om du har en IoT Edge-enhet väljer du IoT Edge i stället.

3. På sidan Enheter väljer du din enhet.

4. På enhetssidan väljer du antingen Enhetstvilling på den översta menyn eller väljer modulidentiteten under Modulidentiteter och väljer sedan modultvillingen.

5. I tvillingen lägger du till taggen ADUGroup med ett användardefinierat värde enligt följande. Om du vill uppdatera ett befintligt ADUGroup taggvärde skriver du över det med ett annat användardefinierat värde.

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

6. Välj Spara.

Azure CLI

Använd az iot hub device-twin update eller az iot hub module-twin update för att lägga till taggen ADUGroup till enheten eller modultvillingen med ett lämpligt värde. För båda update kommandona --tags accepterar argumentet antingen infogad JSON eller en sökväg till en JSON-fil.

Till exempel:

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

Visa enhetsgrupper

Azure-portalen

1. I Azure Portal navigerar du till den IoT-hubb som är ansluten till enhetsuppdateringsinstansen.

2. Välj alternativet Uppdateringar under Enhetshantering i det vänstra navigeringsfältet.

3. Välj fliken Grupper och distributioner .

   

När du har skapat en grupp uppdateras efterlevnadsdiagrammet och grupplistan. I diagrammet Enhetsuppdateringsefterlevnad visas antalet enheter i olika efterlevnadstillstånd: Den senaste uppdateringen, nya uppdateringar som är tillgängliga och Uppdateringar pågår. Mer information finns i Enhetsuppdateringsefterlevnad.

Befintliga enhetsuppdateringsgrupper och eventuella tillgängliga uppdateringar för enheterna i dessa grupper visas i grupplistan. Alla enheter som inte uppfyller enhetsklasskraven för gruppen visas i en motsvarande ogiltig grupp. Du kan distribuera den bästa tillgängliga uppdateringen till en grupp från den här vyn genom att välja Distribuera bredvid gruppen.

Azure CLI

Använd listan az iot du device group för att visa alla enhetsgrupper i en enhetsuppdateringsinstans.

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

Du kan använda --order-by argumentet för att ordna den returnerade listan efter aspekter som grupp-ID, antal enheter eller antal undergrupper med nya tillgängliga uppdateringar.

Visa enhetsinformation för en grupp

Azure-portalen

1. På fliken Grupper och distributioner väljer du namnet på gruppen.

   Sidan Gruppinformation visar diagrammet för uppdateringsefterlevnad med antalet gruppmedlemsenheter i olika efterlevnadstillstånd och listan över gruppmedlemsenheter med sina enhetsuppdateringsegenskaper.

   

2. Välj en enskild enhet i en grupp för att gå till enhetens informationssida i IoT Hub.

   

   

Azure CLI

Använd az iot du device group show för att visa information om en specifik enhetsgrupp.

• Den valfria --best-updates flaggan returnerar en lista över de bästa tillgängliga uppdateringarna för enhetsgruppen, inklusive antalet enheter som behöver varje uppdatering.

• Den valfria --update-compliance flaggan returnerar efterlevnadsinformation för enhetsgruppen, inklusive hur många enheter som har den senaste uppdateringen, behöver nya uppdateringar eller om uppdateringar pågår.

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

Ta bort en enhet från en enhetsgrupp

Om du vill ta bort en enhet från en enhetsgrupp ändrar du ADUGroup taggvärdet till null i tvillingen och väljer Spara.

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

Den här åtgärden tar bort grupptaggen från enhetstvillingen och tar bort enheten från enhetsgruppen.

Ta bort en enhetsgrupp

Enhetsuppdatering skapar automatiskt enhetsgrupper och behåller enhetsgrupper, enhetsklasser och distributioner för historiska poster eller andra användarbehov, i stället för att automatiskt rensa dem. Du kan ta bort enhetsgrupper via Azure Portal genom att välja och ta bort grupperna individuellt, eller genom att anropa az iot du device group delete Azure CLI-kommandot i gruppen.

För att kunna tas bort måste en grupp uppfylla följande krav:

• Får inte vara en default grupp.
• Får inte ha några medlemsenheter. Det innebär att ingen enhet som etableras i enhetsuppdateringsinstansen kan ha en ADUGroup tagg med ett värde som matchar gruppens namn.
• Det får inte ha några associerade aktiva eller avbrutna distributioner.

Kommentar

Om du inte kan ta bort en grupp som uppfyller ovanstående krav kontrollerar du om du har några felaktiga enheter taggade som en del av gruppen. Enheter som inte är felfria kan inte ta emot en distribution, så de visas inte direkt i listan över medlemsenheter i en grupp.

Så här kontrollerar du om du har några enheter som inte är felfria:

1. Gå till din IoT-hubb på Azure Portal.
2. Välj Uppdateringar i det vänstra navigeringsfältet och välj sedan fliken Diagnostik .
3. Expandera avsnittet Hitta saknade enheter .

Om du har felaktiga enheter som taggats som en del av gruppen måste du ändra taggvärdet eller ta bort enheten innan du kan ta bort gruppen.

Om en enhet någonsin tilldelas ett borttaget gruppnamn igen återskapar Enhetsuppdatering automatiskt gruppen, men det finns ingen associerad enhets- eller distributionshistorik.

Relaterat innehåll

• Enhetsgrupper
• Efterlevnad av enhetsuppdatering
• Distribuera en uppdatering