Hantera enhetsgrupper i Enhetsuppdatering för IoT Hub

Enhetsuppdatering för IoT Hub gör det möjligt att distribuera en uppdatering till en grupp IoT-enheter. Det här steget är valfritt när du distribuerar uppdateringar till dina hanterade enheter. Du kan distribuera uppdateringar till dina enheter med hjälp av standardgruppen som skapas åt dig. Du kan också tilldela en användardefinierad tagg till dina enheter, och de grupperas automatiskt baserat på taggen och enhetens kompatibilitetsegenskaper.

Kommentar

Om du vill distribuera till en standardgrupp i stället för en användarskapad grupp fortsätter du till Så här distribuerar du en uppdatering.

Förutsättningar

• Åtkomst till en IoT Hub med Enhetsuppdatering för IoT Hub aktiverat. Vi rekommenderar att du använder en S1-nivå (Standard) eller högre för din IoT Hub.
• En IoT-enhet (eller simulator) som etablerats för enhetsuppdatering i IoT Hub.
  • Installera och starta enhetsuppdateringsagenten på din IoT-enhet, antingen som en modul- eller enhetsidentitet.
• En importerad uppdatering för den etablerade enheten.

Azure-portalen

Webbläsare som stöds:

• Microsoft Edge
• Google Chrome

Azure CLI

En Azure CLI-miljö:

• Använd Bash-miljön i Azure Cloud Shell.

  

• Eller om du föredrar att köra CLI-referenskommandon lokalt installerar du Azure CLI

  1. Logga in på Azure CLI med kommandot az login .
  2. Kör az version om du vill hitta versionen och de beroende bibliotek som är installerade. Om du vill uppgradera till den senaste versionen kör du az upgrade.
  3. När du uppmanas till det installerar du Azure CLI-tillägg vid första användningen. Kommandona i den här artikeln använder azure-iot-tillägget . Kör az extension update --name azure-iot för att se till att du använder den senaste versionen av tillägget.

Lägga till en tagg till dina enheter

För att skapa en enhetsgrupp är det första steget att lägga till en tagg i måluppsättningen med enheter i IoT Hub. Taggar kan bara läggas till på enheten när den har anslutits till Enhetsuppdatering.

Enhetsuppdateringstaggar använder formatet i följande exempel:

"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.

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

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:

• Lär dig hur du lägger till taggar med hjälp av en .NET-exempelapp.
• Läs mer om taggegenskaper.

Lägg till taggar i enhetstvillingen om enhetsuppdateringsagenten har etablerats med enhetsidentitet eller till motsvarande modultvilling om enhetsuppdateringsagenten har etablerats med en modulidentitet.

Lägga till taggar med jobb

Du kan schemalägga ett jobb på flera enheter för att lägga till eller uppdatera en tagg för enhetsuppdatering. 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. Vi rekommenderar att du bara ändrar upp till 50 000 taggar för enhets- eller modultvillingar åt gången, annars kan du behöva köpa fler IoT Hub-enheter om du överskrider din dagliga IoT Hub-meddelandekvot. Mer information finns i Kvoter och begränsning.

Lägga till taggar genom att uppdatera tvillingar

Taggar kan också läggas till eller uppdateras direkt i enhets- eller modultvillingar.

Azure-portalen

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

2. Från Enheter eller IoT Edge i det vänstra navigeringsfönstret hittar du din IoT-enhet. Navigera antingen till enhetstvillingen eller modulen Enhetsuppdatering och sedan dess modultvilling, beroende på om enhetsuppdateringsagenten har etablerats med en enhets- eller modulidentitet.

3. I tvillinginformationen tar du bort alla befintliga taggvärden för enhetsuppdatering genom att ange dem till null.

4. Lägg till ett nytt taggvärde för enhetsuppdatering enligt nedan.

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

Azure CLI

Använd az iot hub device-twin update eller az iot hub module-twin update för att lägga till en tagg i en enhet eller modultvilling.

För båda update kommandona --tags accepterar argumentet antingen infogad json eller en filsökväg till json-innehåll.

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

Begränsningar

• Du kan lägga till valfritt värde i taggen förutom och Uncategorized $default, som är reserverade värden.
• Taggvärdet får inte överstiga 200 tecken.
• Taggvärdet kan innehålla alfanumeriska tecken och följande specialtecken: . - _ ~.
• Tagg- och gruppnamn är skiftlägeskänsliga.
• En enhet kan bara ha en tagg med namnet ADUGroup. Eventuella tillägg av en tagg med det namnet åsidosätter det befintliga värdet för taggnamnet ADUGroup.
• En enhet kan bara tillhöra en grupp.

Visa enhetsgrupper

Grupper skapas automatiskt baserat på de tilldelade taggarna samt enheternas kompatibilitetsegenskaper. En grupp kan ha flera undergrupper med olika enhetsklasser.

Azure-portalen

1. I Azure-portalen navigerar du till den IoT-hubb som du tidigare anslöt till enhetsuppdateringsinstansen.

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

3. Välj fliken Grupper och distributioner .

   

4. När en grupp har skapats ser du att efterlevnadsdiagrammet och grupplistan uppdateras. I diagrammet Enhetsuppdateringsefterlevnad visas antalet enheter i olika efterlevnadstillstånd: Vid senaste uppdatering, Nya tillgängliga uppdateringar och Uppdateringar pågår. Mer information finns i Enhetsuppdateringsefterlevnad.

   

5. Du bör se befintliga grupper och eventuella tillgängliga uppdateringar för enheterna i dessa grupper i grupplistan. Om det finns enheter som inte uppfyller enhetens klasskrav för gruppen visas de 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 knappen 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 beställa de grupper som returneras baserat på 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å den grupp som du vill visa.

2. På sidan gruppinformation kan du se en lista över enheter som ingår i gruppen tillsammans med deras egenskaper för enhetsuppdatering. I den här vyn kan du också se information om uppdateringsefterlevnad för alla enheter som är medlemmar i gruppen. I efterlevnadsdiagrammet visas antalet enheter i olika efterlevnadstillstånd.

   

3. Du kan också välja en enskild enhet i en grupp som ska omdirigeras till sidan enhetsinformation 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 finns på den senaste uppdateringen, hur många som behöver nya uppdateringar och hur många som pågår för en ny uppdatering.

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>

Ta bort en enhet från en enhetsgrupp

Om du vill ta bort en enhet från en enhetsgrupp måste taggvärdet ADUGroup ändras till "null".

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

Då tas taggen ADUGroup bort från enhetstvillingen och enheten tas bort från enhetsgruppen.

Ta bort enhetsgrupper

Även om enhetsgrupper skapas automatiskt rensas inte grupper, enhetsklasser och distributioner automatiskt för att behålla dem för historiska poster eller andra användarbehov. Enhetsgrupper kan tas bort via Azure-portalen genom att välja och ta bort önskade grupper individuellt, eller genom att anropa DELETE-API:et i gruppen. Läs mer

Om en enhet någonsin ansluts igen för den här gruppen när gruppen har tagits bort, medan gruppen skapas på nytt, kommer det inte att finnas någon associerad enhets- eller distributionshistorik.

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

• Gruppen måste ha INGA medlemsenheter. Det innebär att ingen enhet som har etablerats i enhetsuppdateringsinstansen ska ha en ADUGroup-tagg med ett värde som matchar den valda gruppens namn.
• Gruppen får INTE vara en standardgrupp.
• Gruppen får inte ha några aktiva eller avbrutna distributioner associerade med den.

Kommentar

Om du fortfarande inte kan ta bort en grupp efter att ha uppfyllt ovanstående krav kontrollerar du om du har några enheter som inte är felfria som en del av gruppen. Enheter som inte är felfria är enheter som inte kan ta emot en distribution och som ett resultat visas inte direkt i listan över medlemsenheter i en grupp. Du kan kontrollera om du har några enheter som inte är felfria genom att gå till "Hitta enheter som saknas" på fliken Diagnostik i enhetsuppdateringsportalen. Om du har enheter med feltillstånd som är taggade som en del av gruppen måste du ändra taggvärdet eller ta bort enheten helt innan du försöker ta bort gruppen.

Nästa steg

• Distribuera en uppdatering

• Läs mer om enhetsgrupper

• Läs mer om enhetsuppdateringsefterlevnad