Automatisk hantering av IoT-enheter och -moduler med Azure CLI

Artikel
03/17/2023

Automatisk enhetshantering i Azure IoT Hub automatiserar många av de repetitiva och komplexa uppgifterna med att hantera stora enhetsflottor. Med automatisk enhetshantering kan du rikta en uppsättning enheter baserat på deras egenskaper, definiera en önskad konfiguration och sedan låta IoT Hub uppdatera enheterna när de ingår i omfånget. Den här uppdateringen görs med hjälp av en automatisk enhetskonfiguration eller automatisk modulkonfiguration, som gör att du kan sammanfatta slutförande och efterlevnad, hantera sammanslagningar och konflikter samt distribuera konfigurationer i en stegvis metod.

Anteckning

Funktionerna som beskrivs i den här artikeln är endast tillgängliga på standardnivån för IoT Hub. Mer information om nivåerna grundläggande och standard/kostnadsfri IoT Hub finns i Välj rätt IoT Hub nivå för din lösning.

Automatisk enhetshantering fungerar genom att uppdatera en uppsättning enhetstvillingar eller modultvillingar med önskade egenskaper och rapportera en sammanfattning som baseras på tvillingrapporterade egenskaper. Den introducerar ett nytt klass- och JSON-dokument som kallas för en konfiguration som har tre delar:

Målvillkoret definierar omfånget för enhetstvillingar eller modultvillingar som ska uppdateras. Målvillkoret anges som en fråga för enhetstvillingtaggar och/eller rapporterade egenskaper.
Målinnehållet definierar önskade egenskaper som ska läggas till eller uppdateras i målenhetstvillingar eller modultvillingar. Innehållet innehåller en sökväg till avsnittet med önskade egenskaper som ska ändras.
Måtten definierar sammanfattningsantalet för olika konfigurationstillstånd, till exempel Lyckades, Pågår och Fel. Anpassade mått anges som frågor på tvillingrapporterade egenskaper. Systemmått är standardmått som mäter tvillinguppdateringsstatus, till exempel antalet tvillingar som är mål och antalet tvillingar som har uppdaterats.

Automatiska konfigurationer körs för första gången kort efter att konfigurationen har skapats och sedan med fem minuters intervall. Måttfrågor körs varje gång den automatiska konfigurationen körs. Högst 100 automatiska konfigurationer stöds på IoT-hubbar på standardnivå. tio på IoT-hubbar på den kostnadsfria nivån. Begränsningsgränser gäller också. Mer information finns i Kvoter och begränsningar.

CLI-krav

En IoT-hubb i din Azure-prenumeration.
Azure CLI i din miljö. Azure CLI-versionen måste minst vara 2.0.70 eller senare. Validera med az –-version. Den här versionen har stöd för az-tilläggskommandon och introducerar kommandoramverket Knack.
IoT-tillägget för Azure CLI.

Anteckning

Den här artikeln använder den senaste versionen av Azure IoT-tillägget med namnet azure-iot. Den äldre versionen heter azure-cli-iot-ext. Du bör bara ha en version installerad åt gången. Du kan använda kommandot az extension list för att verifiera de för närvarande installerade tilläggen.

Använd az extension remove --name azure-cli-iot-ext för att ta bort den äldre versionen av tillägget.

Använd az extension add --name azure-iot för att lägga till den nya versionen av tillägget.

Om du vill se vilka tillägg som du har installerat använder du az extension list.

Implementera tvillingar

Automatiska enhetskonfigurationer kräver användning av enhetstvillingar för att synkronisera tillstånd mellan molnet och enheterna. Mer information finns i Understand and use device twins in IoT Hub (Förstå och använda enhetstvillingar i IoT Hub).

Automatiska modulkonfigurationer kräver att modultvillingar används för att synkronisera tillståndet mellan molnet och modulerna. Mer information finns i Förstå och använda modultvillingar i IoT Hub.

Använda taggar till måltvillingar

Innan du skapar en konfiguration måste du ange vilka enheter eller moduler du vill påverka. Azure IoT Hub identifierar enheter och använder taggar i enhetstvillingen och identifierar moduler med hjälp av taggar i modultvillingen. Varje enhet eller modul kan ha flera taggar och du kan definiera dem på alla sätt som passar din lösning. Om du till exempel hanterar enheter på olika platser lägger du till följande taggar i en enhetstvilling:

"tags": {
	"location": {
		"state": "Washington",
		"city": "Tacoma"
    }
},

Definiera målinnehåll och mått

Målinnehålls- och måttfrågorna anges som JSON-dokument som beskriver önskade egenskaper för enhetstvillingen eller modultvillingen för att ange och rapporterade egenskaper som ska mätas. Om du vill skapa en automatisk konfiguration med Azure CLI sparar du målinnehållet och måtten lokalt som .txt filer. Du använder filsökvägarna i ett senare avsnitt när du kör kommandot för att tillämpa konfigurationen på enheten.

Här är ett grundläggande exempel på målinnehåll för en automatisk enhetskonfiguration:

{
  "content": {
    "deviceContent": {
      "properties.desired.chillerWaterSettings": {
        "temperature": 38,
        "pressure": 78
      }
    }
}

Automatiska modulkonfigurationer fungerar på ungefär samma sätt, men du riktar in moduleContent dig på i stället för deviceContent.

{
  "content": {
    "moduleContent": {
      "properties.desired.chillerWaterSettings": {
        "temperature": 38,
        "pressure": 78
      }
    }
}

Här är exempel på måttfrågor:

{
  "queries": {
    "Compliant": "select deviceId from devices where configurations.[[chillerdevicesettingswashington]].status = 'Applied' AND properties.reported.chillerWaterSettings.status='current'",
    "Error": "select deviceId from devices where configurations.[[chillerdevicesettingswashington]].status = 'Applied' AND properties.reported.chillerWaterSettings.status='error'",
    "Pending": "select deviceId from devices where configurations.[[chillerdevicesettingswashington]].status = 'Applied' AND properties.reported.chillerWaterSettings.status='pending'"
  }
}

Måttfrågor för moduler liknar också frågor för enheter, men du väljer för moduleId från devices.modules. Ett exempel:

{
  "queries": {
    "Compliant": "select deviceId, moduleId from devices.module where configurations.[[chillermodulesettingswashington]].status = 'Applied' AND properties.reported.chillerWaterSettings.status='current'"
  }
}

Skapa en konfiguration

Du kan skapa högst 100 automatiska konfigurationer på IoT-hubbar på standardnivå. tio på IoT-hubbar på den kostnadsfria nivån. Mer information finns i Kvoter och begränsningar.

Du konfigurerar målenheter genom att skapa en konfiguration som består av målinnehållet och måtten. Använd följande kommando för att skapa en konfiguration:

   az iot hub configuration create --config-id [configuration id] \
     --labels [labels] --content [file path] --hub-name [hub name] \
     --target-condition [target query] --priority [int] \
     --metrics [metric queries]

--config-id – namnet på konfigurationen som ska skapas i IoT-hubben. Ge konfigurationen ett unikt namn som är upp till 128 tecken långt. Gemener och följande specialtecken tillåts: -+%_*!'. Blanksteg är inte tillåtna.
--etiketter – Lägg till etiketter för att spåra konfigurationen. Etiketter är Namn, Värdepar som beskriver distributionen. Det kan till exempel vara HostPlatform, Linux eller Version, 3.0.1
--content – Infogad JSON eller filsökväg till målinnehållet som ska anges som önskade tvillingegenskaper.
--hub-name – Namnet på den IoT-hubb där konfigurationen ska skapas. Hubben måste finnas i den aktuella prenumerationen. Växla till önskad prenumeration med kommandot az account set -s [subscription name]
--target-condition – Ange ett målvillkor för att avgöra vilka enheter eller moduler som ska riktas mot den här konfigurationen. För automatisk enhetskonfiguration baseras villkoret på enhetstvillingtaggar eller önskade egenskaper för enhetstvillingar och ska matcha uttrycksformatet. Exempel: tags.environment='test' eller properties.desired.devicemodel='4000x'. För automatisk modulkonfiguration baseras villkoret på modultvillingtaggar eller önskade egenskaper för modultvillingar.. Exempel: from devices.modules where tags.environment='test' eller from devices.modules where properties.reported.chillerProperties.model='4000x'.
--priority – Ett positivt heltal. Om två eller flera konfigurationer riktas mot samma enhet eller modul gäller konfigurationen med det högsta numeriska värdet för Prioritet.
--metrics – Filsökväg till måttfrågorna. Mått ger sammanfattningsantal av de olika tillstånd som en enhet eller modul kan rapportera tillbaka när konfigurationsinnehållet har tillämpats. Du kan till exempel skapa ett mått för väntande inställningsändringar, ett mått för fel och ett mått för lyckade inställningar.

Övervaka en konfiguration

Använd följande kommando för att visa innehållet i en konfiguration:

az iot hub configuration show --config-id [configuration id] \
  --hub-name [hub name]

--config-id – namnet på konfigurationen som finns i IoT-hubben.
--hub-name – Namnet på den IoT-hubb där konfigurationen finns. Hubben måste finnas i den aktuella prenumerationen. Växla till önskad prenumeration med kommandot az account set -s [subscription name]

Kontrollera konfigurationen i kommandofönstret. Egenskapen metrics visar ett antal för varje mått som utvärderas av varje hubb:

targetedCount – ett systemmått som anger antalet enhetstvillingar eller modultvillingar i IoT Hub som matchar målvillkoret.
appliedCount – Ett systemmått anger antalet enheter eller moduler som har tillämpat målinnehållet.
Ditt anpassade mått – Alla mått som du har definierat är användarmått.

Du kan visa en lista över enhets-ID:n, modul-ID:n eller objekt för vart och ett av måtten med hjälp av följande kommando:

az iot hub configuration show-metric --config-id [configuration id] \
   --metric-id [metric id] --hub-name [hub name] --metric-type [type]

--config-id – namnet på distributionen som finns i IoT-hubben.
--metric-id – namnet på det mått som du vill se listan över enhets-ID:n eller modul-ID:n för, till exempel appliedCount.
--hub-name – Namnet på den IoT-hubb där distributionen finns. Hubben måste finnas i den aktuella prenumerationen. Växla till önskad prenumeration med kommandot az account set -s [subscription name].
--metric-type – Måtttyp kan vara system eller user. Systemmått är targetedCount och appliedCount. Alla andra mått är användarmått.

Ändra en konfiguration

När du ändrar en konfiguration replikeras ändringarna omedelbart till alla målenheter.

Om du uppdaterar målvillkoret sker följande uppdateringar:

Om en tvilling inte uppfyllde det gamla målvillkoret, men uppfyller det nya målvillkoret och den här konfigurationen är den högsta prioriteten för den tvillingen, tillämpas den här konfigurationen.
Om en tvilling som för närvarande kör den här konfigurationen inte längre uppfyller målvillkoret tas inställningarna från konfigurationen bort och tvillingen ändras av nästa konfiguration med högsta prioritet.
Om en tvilling som för närvarande kör den här konfigurationen inte längre uppfyller målvillkoret och inte uppfyller målvillkoret för andra konfigurationer tas inställningarna från konfigurationen bort och inga andra ändringar görs på tvillingen.

Använd följande kommando för att uppdatera en konfiguration:

az iot hub configuration update --config-id [configuration id] \
   --hub-name [hub name] --set [property1.property2='value']

--config-id – namnet på konfigurationen som finns i IoT-hubben.
--hub-name – Namnet på den IoT-hubb där konfigurationen finns. Hubben måste finnas i den aktuella prenumerationen. Växla till önskad prenumeration med kommandot az account set -s [subscription name].
--set – Uppdatera en egenskap i konfigurationen. Du kan uppdatera följande egenskaper:
- targetCondition – till exempel targetCondition=tags.location.state='Oregon'
- Etiketter
- prioritet

Ta bort en konfiguration

När du tar bort en konfiguration får alla enhetstvillingar eller modultvillingar sin näst högsta prioritet. Om tvillingar inte uppfyller målvillkoret för någon annan konfiguration tillämpas inga andra inställningar.

Använd följande kommando för att ta bort en konfiguration:

az iot hub configuration delete --config-id [configuration id] \
   --hub-name [hub name]

--config-id – namnet på konfigurationen som finns i IoT-hubben.
--hub-name – Namnet på den IoT-hubb där konfigurationen finns. Hubben måste finnas i den aktuella prenumerationen. Växla till önskad prenumeration med kommandot az account set -s [subscription name].

Nästa steg

I den här artikeln har du lärt dig hur du konfigurerar och övervakar IoT-enheter i stor skala.

Information om hur du hanterar IoT Hub enhetsidentiteter i grupp finns i Importera och exportera IoT Hub enhetsidentiteter i grupp

Dela via