Automatisch beheer van IoT-apparaat en module met Azure CLI

  • Artikel

Automatisch apparaatbeheer in Azure IoT Hub automatiseert veel van de terugkerende en complexe taken van het beheren van grote apparaatvloten. Met automatisch apparaatbeheer kunt u zich richten op een set apparaten 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 voltooiing en naleving kunt samenvatten, samenvoeging en conflicten kunt afhandelen en configuraties gefaseerd kunt implementeren.

Notitie

De functies die in dit artikel worden beschreven, zijn alleen beschikbaar in de standaardlaag van de IoT Hub. Zie Choose the right IoT Hub tier for your solution (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 bij te werken met de gewenste eigenschappen en een samenvatting te rapporteren die is gebaseerd op gerapporteerde eigenschappen van dubbels. Er wordt een nieuw klasse- en JSON-document geïntroduceerd met de naam een configuratie die uit drie onderdelen bestaat:

  • De doelvoorwaarde definieert het bereik van apparaatdubbels of moduledubbels die moeten worden bijgewerkt. De doelvoorwaarde wordt opgegeven als een query op apparaatdubbeltags en/of gerapporteerde eigenschappen.

  • 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 voor gerapporteerde dubbeleigenschappen. Metrische systeemgegevens zijn de standaard metrische gegevens waarmee de updatestatus van de tweeling 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. Query's voor metrische gegevens worden uitgevoerd telkens wanneer de automatische configuratie wordt uitgevoerd. Er worden maximaal 100 automatische configuraties ondersteund op IoT-hubs van de Standard-laag; tien op IoT-hubs van de gratis laag. Beperkingslimieten zijn ook van toepassing. Zie Quota en beperking voor meer informatie.

CLI-vereisten

  • Een IoT-hub in uw Azure-abonnement.

  • 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 in IoT Hub begrijpen en gebruiken 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 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 die moeten worden ingesteld en gerapporteerde eigenschappen 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 toe te passen op uw apparaat.

Hier volgt een voorbeeld van basisdoelinhoud 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 op in plaats van deviceContent.

{
  "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 voor moduleId in devices.modules. Bijvoorbeeld:

{
  "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 van 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 van maximaal 128 tekens. 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 eigenschappen van de gewenste dubbels.

  • --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]

  • --target-condition : 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 apparaatdubbels en moet deze overeenkomen met de indeling van de expressie. Bijvoorbeeld tags.environment='test' of properties.desired.devicemodel='4000x'. Voor automatische moduleconfiguratie is de voorwaarde gebaseerd op moduledubbeltags of gewenste eigenschappen van moduledubbels. Bijvoorbeeld from devices.modules where tags.environment='test' of from devices.modules where properties.reported.chillerProperties.model='4000x'.

  • --priority : 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 samenvattingen 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 instellingen die in behandeling zijn, 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 die het aantal apparaatdubbels of moduledubbels in IoT Hub aangeeft dat overeenkomt met de doelvoorwaarde.

  • appliedCount : een systeemmetriek geeft het aantal apparaten of modules aan waarop de doelinhoud is toegepast.

  • Uw aangepaste metrische gegevens : alle 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].

  • --metric-type: het metrische type kan of userzijnsystem. 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 heeft voor die dubbel, wordt deze configuratie toegepast.

  • Als een tweeling die momenteel deze configuratie uitvoert, niet meer voldoet aan de doelvoorwaarde, worden de instellingen uit de configuratie verwijderd en wordt de dubbel gewijzigd door de configuratie met de eerstvolgende hoogste prioriteit.

  • Als een tweeling die momenteel deze configuratie uitvoert, niet meer voldoet aan de doelvoorwaarde en niet voldoet aan de doelvoorwaarde van andere configuraties, worden de instellingen van de configuratie verwijderd en worden er geen andere wijzigingen aangebracht in de dubbel.

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: de 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 in de configuratie bijwerken. 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 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: de 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