Automatisch beheer van IoT-apparaat en module met Azure CLI

Artikel
07/17/2024

Automatisch apparaatbeheer in Azure IoT Hub automatiseert veel van de terugkerende en complexe taken voor het beheren van grote apparaatvloten. Met automatisch apparaatbeheer kunt u een set apparaten instellen op basis van hun eigenschappen, een gewenste configuratie definiëren en vervolgens ioT Hub de apparaten laten bijwerken wanneer ze binnen het bereik komen. Deze update wordt uitgevoerd met behulp van een automatische apparaatconfiguratie of automatische moduleconfiguratie, waarmee u de voltooiing en naleving kunt samenvatten, samenvoeging en conflicten kunt afhandelen en configuraties in een gefaseerde benadering kunt implementeren.

Notitie

De functies die in dit artikel worden beschreven, zijn alleen beschikbaar in de standaardlaag van de IoT Hub. Zie De juiste IoT Hub-laag voor uw oplossing kiezen voor meer informatie over de Basic- en Standard-/gratis IoT Hub-lagen.

Automatisch apparaatbeheer werkt door een set apparaatdubbels of moduledubbels met gewenste eigenschappen bij te werken en een samenvatting te rapporteren die is gebaseerd op gerapporteerde eigenschappen van dubbels. Er wordt een nieuwe klasse en een JSON-document geïntroduceerd dat een configuratie wordt genoemd die drie onderdelen bevat:

De doelvoorwaarde definieert het bereik van apparaatdubbels of moduledubbels die moeten worden bijgewerkt. De doelvoorwaarde wordt opgegeven als een query op tags en/of gerapporteerde eigenschappen van apparaatdubbels.
De doelinhoud definieert de gewenste eigenschappen die moeten worden toegevoegd of bijgewerkt in de doelapparaatdubbels of moduledubbels. De inhoud bevat een pad naar de sectie met gewenste eigenschappen die moeten worden gewijzigd.
De metrische gegevens definiëren de samenvattingsaantallen van verschillende configuratiestatussen, zoals Geslaagd, Wordt uitgevoerd en Fout. Aangepaste metrische gegevens worden opgegeven als query's op gerapporteerde eigenschappen van dubbels. Metrische systeemgegevens zijn de standaardmetrieken waarmee de updatestatus van dubbels wordt gemeten, zoals het aantal dubbels dat is gericht en het aantal tweelingen dat is bijgewerkt.

Automatische configuraties worden voor het eerst uitgevoerd kort nadat de configuratie is gemaakt en vervolgens met intervallen van vijf minuten. Metrische query's worden telkens uitgevoerd wanneer de automatische configuratie wordt uitgevoerd. Er worden maximaal 100 automatische configuraties ondersteund op IoT-hubs in de standard-laag; tien op IoT-hubs in de gratis laag. Beperkingslimieten zijn ook van toepassing. Zie Quota en beperking voor meer informatie.

CLI-vereisten

Een IoT-hub in uw Azure-abonnement. Als u nog geen hub hebt, kunt u de stappen volgen in Een IoT-hub maken.
Azure CLI in uw omgeving. Uw Azure CLI-versie moet minimaal 2.0.70 of hoger zijn. Gebruik az –-version om de versie te valideren. In deze versie worden az-extensie-opdrachten ondersteund en is voor het eerst het Knack-opdrachtframework opgenomen.
De IoT-extensie voor Azure CLI.

Notitie

In dit artikel wordt gebruikgemaakt van de nieuwste versie van de Azure IoT-extensie, azure-iot. De verouderde versie heet azure-cli-iot-ext. Zorg ervoor dat er maar één versie is geïnstalleerd. U kunt de opdracht az extension list gebruiken om de momenteel geïnstalleerde extensies te valideren.

Gebruik az extension remove --name azure-cli-iot-ext om de verouderde versie van de extensie te verwijderen.

Gebruik az extension add --name azure-iot om de nieuwe versie van de extensie toe te voegen.

Gebruik az extension list om te bekijken welke installaties u hebt geïnstalleerd.

Dubbels implementeren

Voor automatische apparaatconfiguraties is het gebruik van apparaatdubbels vereist om de status tussen de cloud en apparaten te synchroniseren. Zie Apparaatdubbels begrijpen en gebruiken in IoT Hub voor meer informatie.

Voor automatische moduleconfiguraties is het gebruik van moduledubbels vereist om de status tussen de cloud en modules te synchroniseren. Zie Moduledubbels begrijpen en gebruiken in IoT Hub voor meer informatie.

Tags gebruiken om dubbels te targeten

Voordat u een configuratie maakt, moet u opgeven welke apparaten of modules u wilt beïnvloeden. Azure IoT Hub identificeert apparaten en gebruikt tags in de apparaatdubbel en identificeert modules met behulp van tags in de moduledubbel. Elk apparaat of elke module kan meerdere tags hebben en u kunt ze definiëren op elke manier die zinvol is voor uw oplossing. Als u bijvoorbeeld apparaten op verschillende locaties beheert, voegt u de volgende tags toe aan een apparaatdubbel:

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

De doelinhoud en metrische gegevens definiëren

De doelinhoud en metrische query's worden opgegeven als JSON-documenten waarin de gewenste eigenschappen van de apparaatdubbel of moduledubbel worden beschreven om eigenschappen in te stellen en gerapporteerd om te meten. Als u een automatische configuratie wilt maken met behulp van Azure CLI, slaat u de doelinhoud en metrische gegevens lokaal op als .txt bestanden. U gebruikt de bestandspaden in een latere sectie wanneer u de opdracht uitvoert om de configuratie op uw apparaat toe te passen.

Hier volgt een eenvoudig voorbeeld van doelinhoud voor een automatische apparaatconfiguratie:

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

Automatische moduleconfiguraties gedragen zich op dezelfde manier, maar u richt moduleContent zich in plaats van deviceContentop .

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

Hier volgen voorbeelden van metrische query's:

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

Metrische query's voor modules zijn ook vergelijkbaar met query's voor apparaten, maar u selecteert hiervoor moduleId devices.modules. Voorbeeld:

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

Een configuratie maken

U kunt maximaal 100 automatische configuraties maken op IoT-hubs in de standard-laag; tien op IoT-hubs in de gratis laag. Zie Quota en beperking voor meer informatie.

U configureert doelapparaten door een configuratie te maken die bestaat uit de doelinhoud en metrische gegevens. Gebruik de volgende opdracht om een configuratie te maken:

   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 : de naam van de configuratie die wordt gemaakt in de IoT-hub. Geef uw configuratie een unieke naam die maximaal 128 tekens lang is. Kleine letters en de volgende speciale tekens zijn toegestaan: -+%_*!'. Spaties zijn niet toegestaan.
--labels : voeg labels toe om uw configuratie bij te houden. Labels zijn naam, waardeparen die uw implementatie beschrijven. Bijvoorbeeld HostPlatform, Linux of Version, 3.0.1
--inhoud : inline-JSON of bestandspad naar de doelinhoud die moet worden ingesteld als dubbele gewenste eigenschappen.
--hub-name : naam van de IoT-hub waarin de configuratie wordt gemaakt. De hub moet zich in het huidige abonnement bevinden. Overschakelen naar het gewenste abonnement met de opdracht az account set -s [subscription name]
--doelvoorwaarde: voer een doelvoorwaarde in om te bepalen op welke apparaten of modules deze configuratie wordt toegepast. Voor automatische apparaatconfiguratie is de voorwaarde gebaseerd op apparaatdubbeltags of gewenste eigenschappen van de apparaatdubbel en moet deze overeenkomen met de expressie-indeling. Bijvoorbeeld tags.environment='test' of properties.desired.devicemodel='4000x'. Voor automatische moduleconfiguratie is de voorwaarde gebaseerd op moduledubbeltags of gewenste eigenschappen van de moduledubbel. Bijvoorbeeld from devices.modules where tags.environment='test' of from devices.modules where properties.reported.chillerProperties.model='4000x'.
--prioriteit : een positief geheel getal. In het geval dat twee of meer configuraties zijn gericht op hetzelfde apparaat of dezelfde module, is de configuratie met de hoogste numerieke waarde voor Prioriteit van toepassing.
-- metrische gegevens: Bestandspad naar de metrische query's. Metrische gegevens bieden samenvattingsaantallen van de verschillende statussen die een apparaat of module kan rapporteren na het toepassen van configuratie-inhoud. U kunt bijvoorbeeld een metrische waarde maken voor wijzigingen in behandeling zijnde instellingen, een metrische waarde voor fouten en een metrische waarde voor geslaagde instellingenwijzigingen.

Een configuratie bewaken

Gebruik de volgende opdracht om de inhoud van een configuratie weer te geven:

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

--config-id : de naam van de configuratie die bestaat in de IoT-hub.
--hub-name : naam van de IoT-hub waarin de configuratie bestaat. De hub moet zich in het huidige abonnement bevinden. Overschakelen naar het gewenste abonnement met de opdracht az account set -s [subscription name]

Controleer de configuratie in het opdrachtvenster. De eigenschap metrische gegevens bevat een telling voor elke metrische waarde die door elke hub wordt geëvalueerd:

targetedCount : een systeemmetriek waarmee het aantal apparaatdubbels of moduledubbels in IoT Hub wordt opgegeven die overeenkomen met de doelvoorwaarde.
appliedCount - Een systeemmetriek geeft het aantal apparaten of modules aan waarop de doelinhoud is toegepast.
Uw aangepaste metrische gegevens : metrische gegevens die u hebt gedefinieerd, zijn metrische gegevens van gebruikers.

U kunt een lijst met apparaat-id's, module-id's of objecten voor elk van de metrische gegevens weergeven met behulp van de volgende opdracht:

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

--config-id : de naam van de implementatie die bestaat in de IoT-hub.
--metric-id : de naam van de metrische waarde waarvoor u de lijst met apparaat-id's of module-id's wilt zien, bijvoorbeeld appliedCount.
--hub-name : naam van de IoT-hub waarin de implementatie bestaat. De hub moet zich in het huidige abonnement bevinden. Schakel over naar het gewenste abonnement met de opdracht az account set -s [subscription name].
--metrische waarde : het type metrische waarde kan of system user. Metrische systeemgegevens zijn targetedCount en appliedCount. Alle andere metrische gegevens zijn metrische gegevens van gebruikers.

Een configuratie wijzigen

Wanneer u een configuratie wijzigt, worden de wijzigingen onmiddellijk gerepliceerd naar alle doelapparaten.

Als u de doelvoorwaarde bijwerkt, worden de volgende updates uitgevoerd:

Als een dubbel niet voldoet aan de oude doelvoorwaarde, maar voldoet aan de nieuwe doelvoorwaarde en deze configuratie de hoogste prioriteit voor die dubbel is, wordt deze configuratie toegepast.
Als een tweeling waarop deze configuratie momenteel wordt uitgevoerd, niet meer voldoet aan de doelvoorwaarde, worden de instellingen van de configuratie verwijderd en wordt de tweeling gewijzigd door de volgende configuratie met de hoogste prioriteit.
Als een tweeling waarop deze configuratie momenteel wordt uitgevoerd niet meer voldoet aan de doelvoorwaarde en niet voldoet aan de doelvoorwaarde van andere configuraties, worden de instellingen uit de configuratie verwijderd en worden er geen andere wijzigingen aangebracht op de tweeling.

Gebruik de volgende opdracht om een configuratie bij te werken:

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

--config-id : de naam van de configuratie die bestaat in de IoT-hub.
--hub-name : naam van de IoT-hub waarin de configuratie bestaat. De hub moet zich in het huidige abonnement bevinden. Schakel over naar het gewenste abonnement met de opdracht az account set -s [subscription name].
--set - Een eigenschap bijwerken in de configuratie. U kunt de volgende eigenschappen bijwerken:
- targetCondition- bijvoorbeeld targetCondition=tags.location.state='Oregon'
- labels
- priority

Een configuratie verwijderen

Wanneer u een configuratie verwijdert, hebben alle apparaatdubbels of moduledubbels hun volgende configuratie met de hoogste prioriteit. Als tweelingen niet voldoen aan de doelvoorwaarde van een andere configuratie, worden er geen andere instellingen toegepast.

Gebruik de volgende opdracht om een configuratie te verwijderen:

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

--config-id : de naam van de configuratie die bestaat in de IoT-hub.
--hub-name : naam van de IoT-hub waarin de configuratie bestaat. De hub moet zich in het huidige abonnement bevinden. Schakel over naar het gewenste abonnement met de opdracht az account set -s [subscription name].

Volgende stappen

In dit artikel hebt u geleerd hoe u IoT-apparaten op schaal configureert en bewaakt.

Zie IoT Hub-apparaatidentiteiten bulksgewijs importeren en exporteren voor meer informatie over het bulksgewijs beheren van IoT Hub-apparaatidentiteiten

Delen via