Automatisch beheer van IoT-apparaat en module met Azure CLI

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.

Automatic device management works by updating a set of device twins or module twins with desired properties and reporting a summary that's based on twin reported properties. 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 apparaat-tweelingen of module-tweelingen die bijgewerkt moeten worden. The target condition is specified as a query on device twin tags and/or reported properties.

• Het doelinhoud definieert de gewenste eigenschappen die moeten worden toegevoegd of bijgewerkt in de gerichte apparaat-tweelingen of module-tweelingen. 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. Custom metrics are specified as queries on twin reported properties. Systeemmetriek zijn de standaardmetrieken waarmee de update-status van tweelingen wordt gemeten, zoals het aantal tweelingen dat wordt beoogd en het aantal tweelingen dat succesvol 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. Beperkingen van stroombandbreedte zijn ook van toepassing. Voor meer informatie, zie Quota en Throttling.

Vereisten voor CLI

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

Implement twins

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 je op tweelingen te richten

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

The target content and metric queries are specified as JSON documents that describe the device twin or module twin desired properties to set and reported properties to measure. 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 zich op moduleContent 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 hiervoor moduleIddevices.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. Voor meer informatie, zie Quota en Throttling.

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

• -- content - Inline JSON of bestandspad naar de doelinhoud die moet worden ingesteld als gewenste eigenschappen van de twin.

• -- 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 apparaat-twin-tags of gewenste apparaat-twin-eigenschappen en moet deze overeenkomen met het expressieformaat. Bijvoorbeeld tags.environment='test' of properties.desired.devicemodel='4000x'. For automatic module configuration, the condition is based on module twin tags or module twin desired properties.. 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.

• -- metrics - Filepath to the metric queries. 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 metriek maken voor openstaande instellingenwijzigingen, een metriek voor fouten en een metriek 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].

• -- metrisch type - het metrisch type kan system of user zijn. 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 - for example targetCondition=tags.location.state='Oregon'

  • etiketten

  • priority

Een configuratie verwijderen

Wanneer u een configuratie verwijdert, nemen alle apparaattweelingen of moduletweelingen de configuratie met de eerstvolgende hoogste prioriteit over. 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