IoT Edge-modules op schaal implementeren en bewaken met behulp van de Azure CLI

Van toepassing op: IoT Edge 1.5

Gebruik de Azure CLI om een automatische implementatie van Azure IoT Edge te maken en implementaties voor veel apparaten tegelijk te beheren. Automatische implementaties voor IoT Edge maken deel uit van de functie voor apparaatbeheer van Azure IoT Hub. Met implementaties kunt u meerdere modules implementeren op meerdere apparaten, de status en status van modules bijhouden en zo nodig wijzigingen aanbrengen.

In dit artikel stelt u de Azure CLI en de IoT-extensie in. Vervolgens implementeert u modules op een set IoT Edge-apparaten en bewaakt u de voortgang met behulp van CLI-opdrachten.

Vereisten

• Een IoT-hub in uw Azure-abonnement.

• Een of meer IoT Edge-apparaten.

  Als u geen IoT Edge-apparaat hebt ingesteld, kunt u er een maken in een virtuele Azure-machine. Volg de stappen in een van deze quickstart-artikelen: Een virtueel Linux-apparaat maken of een virtueel Windows-apparaat maken.

• De Azure CLI in uw omgeving. Uw Azure CLI-versie moet 2.0.70 of hoger zijn. Gebruik az --version om te controleren. In deze versie worden az-extensie-opdrachten ondersteund en is voor het eerst het Knack-opdrachtframework opgenomen.

• De IoT-extensie voor Azure CLI.

Een implementatiemanifest configureren

Een implementatiemanifest is een JSON-document waarin wordt beschreven welke modules moeten worden geïmplementeerd, hoe gegevens stromen tussen de modules en de gewenste eigenschappen van de moduledubbels. Zie Meer informatie over het implementeren van modules en het tot stand brengen van routes in IoT Edge.

Als u modules wilt implementeren met behulp van de Azure CLI, slaat u het implementatiemanifest lokaal op als een .txt-bestand. U gebruikt het bestandspad in de volgende sectie wanneer u de opdracht uitvoert om de configuratie op uw apparaat toe te passen.

Hier volgt een basisimplementatiemanifest met één module als voorbeeld.

{
  "content": {
    "modulesContent": {
      "$edgeAgent": {
        "properties.desired": {
          "schemaVersion": "1.1",
          "runtime": {
            "type": "docker",
            "settings": {
              "minDockerVersion": "v1.25",
              "loggingOptions": "",
              "registryCredentials": {}
            }
          },
          "systemModules": {
            "edgeAgent": {
              "type": "docker",
              "settings": {
                "image": "mcr.microsoft.com/azureiotedge-agent:1.5",
                "createOptions": "{}"
              }
            },
            "edgeHub": {
              "type": "docker",
              "status": "running",
              "restartPolicy": "always",
              "settings": {
                "image": "mcr.microsoft.com/azureiotedge-hub:1.5",
                "createOptions": "{\"HostConfig\":{\"PortBindings\":{\"5671/tcp\":[{\"HostPort\":\"5671\"}],\"8883/tcp\":[{\"HostPort\":\"8883\"}],\"443/tcp\":[{\"HostPort\":\"443\"}]}}}"
              }
            }
          },
          "modules": {
            "SimulatedTemperatureSensor": {
              "version": "1.5",
              "type": "docker",
              "status": "running",
              "restartPolicy": "always",
              "settings": {
                "image": "mcr.microsoft.com/azureiotedge-simulated-temperature-sensor:1.5",
                "createOptions": "{}"
              }
            }
          }
        }
      },
      "$edgeHub": {
        "properties.desired": {
          "schemaVersion": "1.1",
          "routes": {
            "upstream": "FROM /messages/* INTO $upstream"
          },
          "storeAndForwardConfiguration": {
            "timeToLiveSecs": 7200
          }
        }
      },
      "SimulatedTemperatureSensor": {
        "properties.desired": {
          "SendData": true,
          "SendInterval": 5
        }
      }
    }
  }
}

Gelaagde implementatie

Gelaagde implementaties zijn een type automatische implementatie dat u op elkaar kunt stapelen. Zie Informatie over automatische implementaties van IoT Edge voor afzonderlijke apparaten of op schaal voor meer informatie over gelaagde implementaties.

U kunt gelaagde implementaties maken en beheren met de Azure CLI, net als elke automatische implementatie, met slechts enkele verschillen. Nadat u een gelaagde implementatie hebt gemaakt, werkt de Azure CLI voor gelaagde implementaties hetzelfde als voor elke implementatie. Als u een gelaagde implementatie wilt maken, voegt u de --layered vlag toe aan de opdracht maken.

Het tweede verschil is de wijze waarop u het implementatiemanifest maakt. Standaard automatische implementaties moeten de systeemruntimemodules en alle gebruikersmodules bevatten. Gelaagde implementaties kunnen alleen gebruikersmodules bevatten. Gelaagde implementaties hebben ook een standaard automatische implementatie op een apparaat nodig om de vereiste onderdelen van elk IoT Edge-apparaat te leveren, zoals de systeemruntimemodules.

Hier volgt een eenvoudig gelaagd implementatiemanifest met één module als voorbeeld.

{
  "content": {
    "modulesContent": {
      "$edgeAgent": {
        "properties.desired.modules.SimulatedTemperatureSensor": {
          "settings": {
            "image": "mcr.microsoft.com/azureiotedge-simulated-temperature-sensor:1.5",
              "createOptions": "{}"
          },
          "type": "docker",
          "status": "running",
          "restartPolicy": "always",
          "version": "1.5"
        }
      },
      "$edgeHub": {
        "properties.desired.routes.upstream": "FROM /messages/* INTO $upstream"
      },
      "SimulatedTemperatureSensor": {
        "properties.desired": {
          "SendData": true,
          "SendInterval": 5
        }
      }
    }
  }
}

In het vorige voorbeeld ziet u de gelaagde implementatie-instelling properties.desired voor een module. Als deze gelaagde implementatie is gericht op een apparaat waarop dezelfde module al wordt toegepast, worden alle bestaande gewenste eigenschappen overschreven. Als u de gewenste eigenschappen wilt bijwerken in plaats van ze te overschrijven, definieert u een nieuwe subsectie. Voorbeeld:

"SimulatedTemperatureSensor": {
  "properties.desired.layeredProperties": {
    "SendData": true,
    "SendInterval": 5
  }
}

U kunt ook hetzelfde uitdrukken met de volgende syntaxis:

"SimulatedTemperatureSensor": {
  "properties.desired.layeredProperties.SendData" : true,
  "properties.desired.layeredProperties.SendInterval": 5
}

Een gelaagde implementatie maken:

• Voeg de --layered vlag toe aan de azure CLI-opdracht voor maken.
• Neem geen systeemmodules op.
• Gebruik de volledige punt notatie onder $edgeAgent en $edgeHub.

Zie Gelaagde implementatie voor meer informatie over het configureren van moduledubbels in gelaagde implementaties.

Apparaten identificeren met behulp van tags

Voordat u een implementatie maakt, moet u opgeven welke apparaten u wilt beïnvloeden. Azure IoT Edge identificeert apparaten met behulp van tags in de apparaatdubbel.

Elk apparaat kan meerdere tags bevatten die u definieert op elke manier die zinvol is voor uw oplossing. Als u bijvoorbeeld een campus met slimme gebouwen beheert, kunt u de volgende tags toevoegen aan een apparaat:

"tags":{
  "location":{
    "building": "20",
    "floor": "2"
  },
  "roomtype": "conference",
  "environment": "prod"
}

Zie Apparaatdubbels en tags begrijpen en gebruiken in IoT Hub voor meer informatie over apparaatdubbels.

Een implementatie maken

Implementeer modules op doelapparaten door een implementatie te maken met het implementatiemanifest en andere parameters.

Voer de opdracht az iot edge deployment create uit om een implementatie te maken:

az iot edge deployment create --deployment-id <deployment-id> --hub-name <hub-name> --content <file-path> --labels "<labels>" --target-condition "<target-query>" --priority <priority>

Voeg de --layered vlag toe om een gelaagde implementatie te maken.

De az iot edge deployment create opdracht gebruikt de volgende parameters:

• --gelaagd: optionele vlag die de implementatie identificeert als een gelaagde implementatie.
• --deployment-id: naam van de implementatie die is gemaakt in de IoT-hub. Gebruik een unieke naam met maximaal 128 kleine letters. Vermijd spaties en deze ongeldige tekens: & ^ [ ] { } \ | " < > /. Deze parameter is vereist.
• --content: bestandspad naar het JSON-implementatiemanifest. Deze parameter is vereist.
• --hub-name: naam van de IoT-hub waar de implementatie wordt gemaakt. De hub moet zich in het huidige abonnement bevinden. Wijzig uw huidige abonnement door uit te voeren az account set -s <subscription-name>.
• --labels: naam/waardeparen die implementaties beschrijven en bijhouden. Labels gebruiken JSON-opmaak voor namen en waarden. Voorbeeld: {"HostPlatform":"Linux", "Version":"3.0.1"}.
• --target-condition: Voorwaarde die bepaalt welke apparaten zijn gericht op deze implementatie. De voorwaarde is gebaseerd op gerapporteerde eigenschappen van apparaatdubbels of apparaatdubbels en moet overeenkomen met de expressie-indeling. Voorbeeld: tags.environment='test' and properties.reported.devicemodel='4000x'. Als u de doelvoorwaarde niet opgeeft, wordt de implementatie niet toegepast op apparaten.
• --prioriteit: positief geheel getal. Als twee of meer implementaties op hetzelfde apparaat zijn gericht, is de implementatie met de hoogste prioriteit van toepassing.
• --metrics: Metrische gegevens die een query uitvoeren op de edgeHub gerapporteerde eigenschappen om de status van een implementatie bij te houden. Metrische gegevens gebruiken JSON-invoer of een bestandspad. Voorbeeld: '{"queries": {"mymetric": "SELECT deviceId FROM devices WHERE properties.reported.lastDesiredStatus.code = 200"}}'.

Zie IoT Edge-implementaties bewaken om een implementatie met de Azure CLI te bewaken.

Een implementatie wijzigen

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

Als u de doelvoorwaarde bijwerkt, treden de volgende wijzigingen op:

• Als een apparaat niet voldoet aan de oude doelvoorwaarde, maar voldoet aan de nieuwe doelvoorwaarde en deze implementatie de hoogste prioriteit voor dat apparaat is, wordt deze implementatie toegepast op het apparaat.
• Als een apparaat waarop deze implementatie momenteel wordt uitgevoerd, niet meer voldoet aan de doelvoorwaarde, wordt deze implementatie verwijderd en wordt de volgende implementatie met de hoogste prioriteit uitgevoerd.
• Als een apparaat waarop deze implementatie momenteel wordt uitgevoerd, niet meer voldoet aan de doelvoorwaarde en niet voldoet aan de doelvoorwaarde van een andere implementatie, vindt er geen wijziging plaats op het apparaat. Het apparaat blijft de huidige modules in de huidige status uitvoeren, maar wordt niet meer beheerd als onderdeel van deze implementatie. Nadat het apparaat voldoet aan de doelvoorwaarde van een andere implementatie, wordt deze implementatie verwijderd en wordt de nieuwe geïmplementeerd.

U kunt de inhoud van een implementatie niet bijwerken, waaronder de modules en routes die zijn gedefinieerd in het implementatiemanifest. Als u de inhoud van een implementatie wilt bijwerken, maakt u een nieuwe implementatie die is gericht op dezelfde apparaten met een hogere prioriteit. U kunt bepaalde eigenschappen van een bestaande module wijzigen, waaronder de doelvoorwaarde, labels, metrische gegevens en prioriteit.

Gebruik de opdracht az iot edge deployment update om een implementatie bij te werken:

az iot edge deployment update --deployment-id <deployment-id> --hub-name <hub-name> --set <property1.property2='value'>

De opdracht implementatie-update maakt gebruik van de volgende parameters:

• --deployment-id: de naam van de implementatie in de IoT-hub.
• --hub-name: de naam van de IoT-hub waar de implementatie bestaat. De hub moet zich in het huidige abonnement bevinden. Als u wilt overschakelen naar een ander abonnement, voert u het volgende uit az account set -s <subscription-name>.
• --set: Wijzig een eigenschap in de implementatie. U kunt de volgende eigenschappen wijzigen:
  • targetCondition (bijvoorbeeld, targetCondition=tags.location.state='Oregon')
  • labels
  • priority
• --add: Voeg een nieuwe eigenschap toe aan de implementatie, inclusief doelvoorwaarden of labels.
• --remove: Verwijder een bestaande eigenschap, inclusief doelvoorwaarden of labels.

Een implementatie verwijderen

Wanneer u een implementatie verwijdert, gebruiken apparaten hun volgende implementatie met de hoogste prioriteit. Als apparaten niet voldoen aan de doelvoorwaarde van een andere implementatie, worden de modules niet verwijderd wanneer u de implementatie verwijdert.

Voer de opdracht az iot edge deployment delete uit om een implementatie te verwijderen:

az iot edge deployment delete --deployment-id <deployment-id> --hub-name <hub-name>

De deployment delete opdracht gebruikt de volgende parameters:

• --deployment-id. De naam van de implementatie die bestaat in de IoT-hub.
• --hub-name. De 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 behulp van de opdracht az account set -s [subscription name].

Volgende stappen

Meer informatie over het implementeren van modules op IoT Edge-apparaten.