Aan de slag met apparaatbeheer (Python)

Artikel
03/16/2023

Back-end-apps kunnen gebruikmaken van Azure IoT Hub primitieven, zoals apparaatdubbels en directe methoden, om apparaatbeheeracties op apparaten op afstand te starten en te bewaken. In dit artikel wordt beschreven hoe een back-end-app en een apparaat-app kunnen samenwerken om het opnieuw opstarten van een extern apparaat te initiëren en bewaken met behulp van IoT Hub.

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 lagen Basic en Standard/free IoT Hub.

Gebruik een directe methode om acties voor apparaatbeheer (zoals opnieuw opstarten, fabrieksinstellingen en firmware-update) te initiëren vanuit een back-end-app in de cloud. Het apparaat is verantwoordelijk voor:

De methodeaanvraag verwerken die is verzonden vanaf IoT Hub.
De bijbehorende apparaatspecifieke actie op het apparaat initiëren.
Het verstrekken van statusupdates via gerapporteerde eigenschappen aan IoT Hub.

U kunt een back-end-app in de cloud gebruiken om apparaatdubbelquery's uit te voeren om te rapporteren over de voortgang van uw apparaatbeheeracties.

In dit artikel wordt beschreven hoe u het volgende maakt:

dmpatterns_getstarted_device.py: een app voor een gesimuleerd apparaat met een directe methode waarmee het apparaat opnieuw wordt opgestart en de laatste keer dat het apparaat opnieuw wordt opgestart. Directe methoden worden aangeroepen vanuit de cloud.
dmpatterns_getstarted_service.py: een Python-console-app die de directe methode in de gesimuleerde apparaat-app aanroept via uw IoT-hub. Het antwoord en bijgewerkte gerapporteerde eigenschappen worden weergegeven.

Notitie

Zie Azure IoT SDK's voor meer informatie over de SDK-hulpprogramma's die beschikbaar zijn voor het bouwen van zowel apparaat- als back-end-apps.

Vereisten

Een actief Azure-account. (Als u geen account hebt, kunt u binnen een paar minuten een gratis account maken.)
Een IoT-hub. Maak er een met de CLI of de Azure Portal.
Een geregistreerd apparaat. Registreer er een in de Azure Portal.
Python versie 3.7 of hoger wordt aanbevolen. Zorg ervoor dat u de 32-bits of 64-bits installatie gebruikt, zoals vereist door uw configuratie. Zorg ervoor dat u Python toevoegt aan uw platformspecifieke omgevingsvariabele als u hierom wordt gevraagd tijdens de installatie.
Zorg ervoor dat de poort 8883 is geopend in de firewall. Het apparaatvoorbeeld in dit artikel maakt gebruik van het MQTT-protocol, dat communiceert via poort 8883. Deze poort is in sommige netwerkomgevingen van bedrijven en onderwijsinstellingen mogelijk geblokkeerd. Zie Verbinding maken met IoT Hub (MQTT) voor meer informatie en manieren om dit probleem te omzeilen.

Een nieuw apparaat registreren in de IoT-hub

In deze sectie gebruikt u de Azure CLI om een apparaat-id te maken voor dit artikel. Apparaat-id's zijn hoofdlettergevoelig.

Open Azure Cloud Shell.
Voer in Azure Cloud Shell de volgende opdracht uit om de Microsoft Azure IoT-extensie voor Azure CLI te installeren:
```
az extension add --name azure-iot
```
Maak een nieuwe apparaat-id met de naam myDeviceId en haal het apparaat connection string op met de volgende opdrachten:
```
az iot hub device-identity create --device-id myDeviceId --hub-name {Your IoT Hub name} --resource-group {Resource group of the Hub}
az iot hub device-identity connection-string show --device-id myDeviceId --hub-name {Your IoT Hub name} --resource-group {Resource group of the Hub} -o table
```
Belangrijk

De apparaat-ID is mogelijk zichtbaar in de logboeken die worden verzameld voor klantondersteuning en probleemoplossing. Zorg er dus voor dat wordt voorkomen dat gevoelige informatie wordt vermeld.

Noteer het apparaat connection string van het resultaat. Dit apparaat connection string wordt door de apparaat-app gebruikt om verbinding te maken met uw IoT Hub als apparaat.

Een apparaat-app maken met een directe methode

In deze sectie doet u het volgende:

Maak een Python-console-app die reageert op een directe methode die door de cloud wordt aangeroepen.
Een apparaat opnieuw opstarten simuleren.
Gebruik de gerapporteerde eigenschappen om query's van apparaatdubbels in te schakelen om apparaten te identificeren en wanneer ze voor het laatst opnieuw zijn opgestart.

Maak de apparaatcode in Azure Cloud Shell die u eerder hebt gebruikt, of in een andere omgeving met Python.

Voer bij de opdrachtprompt de volgende opdracht uit om het pakket azure-iot-device te installeren:
```
pip install azure-iot-device
```
Maak met behulp van een teksteditor een bestand met de naam dmpatterns_getstarted_device.py in uw werkmap.
Voeg de volgende import instructies toe aan het begin van het bestand dmpatterns_getstarted_device.py .
```
import time
import datetime
from azure.iot.device import IoTHubDeviceClient, MethodResponse
```
Voeg de variabele CONNECTION_STRING toe. Vervang de waarde van de {deviceConnectionString} tijdelijke aanduiding door uw apparaat connection string. U hebt deze connection string eerder gekopieerd in Een nieuw apparaat registreren in de IoT-hub.
```
CONNECTION_STRING = "{deviceConnectionString}"
```

Voeg de volgende functie toe om een client te instantiëren die is geconfigureerd voor directe methoden op het apparaat.

def create_client():
    # Instantiate the client
    client = IoTHubDeviceClient.create_from_connection_string(CONNECTION_STRING)

    # Define the handler for method requests
    def method_request_handler(method_request):
        if method_request.name == "rebootDevice":
            # Act on the method by rebooting the device
            print("Rebooting device")
            time.sleep(20)
            print("Device rebooted")

            # ...and patching the reported properties
            current_time = str(datetime.datetime.now())
            reported_props = {"rebootTime": current_time}
            client.patch_twin_reported_properties(reported_props)
            print( "Device twins updated with latest rebootTime")

            # Create a method response indicating the method request was resolved
            resp_status = 200
            resp_payload = {"Response": "This is the response from the device"}
            method_response = MethodResponse(method_request.request_id, resp_status, resp_payload)

        else:
            # Create a method response indicating the method request was for an unknown method
            resp_status = 404
            resp_payload = {"Response": "Unknown method"}
            method_response = MethodResponse(method_request.request_id, resp_status, resp_payload)

        # Send the method response
        client.send_method_response(method_response)

    try:
        # Attach the handler to the client
        client.on_method_request_received = method_request_handler
    except:
        # In the event of failure, clean up
        client.shutdown()

    return client

Start het voorbeeld van de directe methode en wacht.

def main():
    print ("Starting the IoT Hub Python sample...")
    client = create_client()

    print ("Waiting for commands, press Ctrl-C to exit")
    try:
        # Wait for program exit
        while True:
            time.sleep(1000)
    except KeyboardInterrupt:
        print("IoTHubDeviceClient sample stopped")
    finally:
        # Graceful exit
        print("Shutting down IoT Hub Client")
        client.shutdown()

if __name__ == '__main__':
    main()

Sla het bestand dmpatterns_getstarted_device.py op en sluit het.

Notitie

Om de zaken niet nodeloos ingewikkeld te maken, is in deze handleiding geen beleid voor opnieuw proberen geïmplementeerd. In productiecode moet u beleid voor opnieuw proberen implementeren (zoals een exponentiële uitstel), zoals wordt voorgesteld in het artikel Tijdelijke foutafhandeling.

De IoT-hub ophalen connection string

In dit artikel maakt u een back-endservice die een directe methode op een apparaat aanroept. Als u een directe methode op een apparaat wilt aanroepen via IoT Hub, heeft uw service de machtiging serviceverbinding nodig. Standaard wordt elke IoT Hub gemaakt met een gedeeld toegangsbeleid met de naam service die deze machtiging verleent.

Voer de volgende stappen uit om de IoT Hub connection string voor het servicebeleid op te halen:

Selecteer resourcegroepenin de Azure Portal. Selecteer de resourcegroep waarin uw hub zich bevindt en selecteer vervolgens uw hub in de lijst met resources.
Selecteer In het linkerdeelvenster van uw IoT-hub de optie Beleid voor gedeelde toegang.
Selecteer het servicebeleid in de lijst met beleidsregels.
Kopieer de Primaire connection string en sla de waarde op.

Zie Toegangsbeheer en machtigingen voor meer informatie over IoT Hub beleid en machtigingen voor gedeelde toegang.

Een service-app maken om opnieuw opstarten te activeren

In deze sectie maakt u een Python-console-app waarmee op een apparaat extern opnieuw wordt opgestart met behulp van een directe methode. De app maakt gebruik van apparaatdubbelquery's om de laatste keer dat het apparaat opnieuw is opgestart te detecteren.

Maak de consolecode in Azure Cloud Shell of een andere omgeving met Python.

Voer bij de opdrachtprompt de volgende opdracht uit om het pakket azure-iot-hub te installeren:
```
pip install azure-iot-hub
```
Maak met behulp van een teksteditor een bestand met de naam dmpatterns_getstarted_service.py in uw werkmap.

Voeg de volgende import instructies toe aan het begin van het bestand dmpatterns_getstarted_service.py .

import sys, time

from azure.iot.hub import IoTHubRegistryManager
from azure.iot.hub.models import CloudToDeviceMethod, CloudToDeviceMethodResult, Twin

Voeg de volgende variabeledeclaraties toe. Vervang de waarde van de {IoTHubConnectionString} tijdelijke aanduiding door de IoT-hub-connection string die u eerder hebt gekopieerd in De IoT-hub ophalen connection string. Vervang de waarde van de {deviceId} tijdelijke aanduiding door de apparaat-id die u hebt geregistreerd in Een nieuw apparaat registreren in de IoT-hub.
```
CONNECTION_STRING = "{IoTHubConnectionString}"
DEVICE_ID = "{deviceId}"

METHOD_NAME = "rebootDevice"
METHOD_PAYLOAD = "{\"method_number\":\"42\"}"
TIMEOUT = 60
WAIT_COUNT = 10
```

Voeg de volgende functie toe om de apparaatmethode aan te roepen om het doelapparaat opnieuw op te starten, voer vervolgens een query uit naar de apparaatdubbels en haal de laatste keer dat het apparaat opnieuw wordt opgestart op.

def iothub_devicemethod_sample_run():
    try:
        # Create IoTHubRegistryManager
        registry_manager = IoTHubRegistryManager(CONNECTION_STRING)

        print ( "" )
        print ( "Invoking device to reboot..." )

        # Call the direct method.
        deviceMethod = CloudToDeviceMethod(method_name=METHOD_NAME, payload=METHOD_PAYLOAD)
        response = registry_manager.invoke_device_method(DEVICE_ID, deviceMethod)

        print ( "" )
        print ( "Successfully invoked the device to reboot." )

        print ( "" )
        print ( response.payload )

        while True:
            print ( "" )
            print ( "IoTHubClient waiting for commands, press Ctrl-C to exit" )

            status_counter = 0
            while status_counter <= WAIT_COUNT:
                twin_info = registry_manager.get_twin(DEVICE_ID)

                if twin_info.properties.reported.get("rebootTime") != None :
                    print ("Last reboot time: " + twin_info.properties.reported.get("rebootTime"))
                else:
                    print ("Waiting for device to report last reboot time...")

                time.sleep(5)
                status_counter += 1

    except Exception as ex:
        print ( "" )
        print ( "Unexpected error {0}".format(ex) )
        return
    except KeyboardInterrupt:
        print ( "" )
        print ( "IoTHubDeviceMethod sample stopped" )

if __name__ == '__main__':
    print ( "Starting the IoT Hub Service Client DeviceManagement Python sample..." )
    print ( "    Connection string = {0}".format(CONNECTION_STRING) )
    print ( "    Device ID         = {0}".format(DEVICE_ID) )

    iothub_devicemethod_sample_run()

Sla het bestand dmpatterns_getstarted_service.py op en sluit het.

De apps uitvoeren

U bent nu klaar om de apparaatcode en de servicecode uit te voeren waarmee het apparaat opnieuw wordt opgestart.

Voer bij de opdrachtprompt waar u het apparaat hebt gemaakt de volgende opdracht uit om te luisteren naar de directe methode voor opnieuw opstarten.
```
python dmpatterns_getstarted_device.py
```
Voer bij de opdrachtprompt waar u de service maakt de volgende opdracht uit om extern opnieuw opstarten te activeren en een query uit te voeren voor de apparaatdubbel om de laatste keer opnieuw opstarten te vinden.
```
python dmpatterns_getstarted_service.py
```
U ziet het antwoord van het apparaat op de directe methode in de console.

Hieronder ziet u het antwoord van het apparaat op de directe methode voor opnieuw opstarten:

Hieronder ziet u hoe de service de directe methode voor opnieuw opstarten aanroept en de apparaatdubbel op de status controleert:

De acties voor apparaatbeheer aanpassen en uitbreiden

Uw IoT-oplossingen kunnen de gedefinieerde set apparaatbeheerpatronen uitbreiden of aangepaste patronen inschakelen met behulp van de apparaatdubbel en cloud-naar-apparaat methode primitieven. Andere voorbeelden van acties voor apparaatbeheer zijn fabrieksinstellingen terugzetten, firmware-update, software-update, energiebeheer, netwerk- en connectiviteitsbeheer en gegevensversleuteling.

Onderhoudsvensters voor apparaten

Normaal gesproken configureert u apparaten om acties uit te voeren op een moment dat onderbrekingen en downtime tot een minimum worden beperkt. Apparaatonderhoudsvensters zijn een veelgebruikt patroon om de tijd te definiëren waarop een apparaat de configuratie moet bijwerken. Uw back-endoplossingen kunnen gebruikmaken van de gewenste eigenschappen van de apparaatdubbel om een beleid op uw apparaat te definiëren en activeren dat een onderhoudsvenster mogelijk maakt. Wanneer een apparaat het onderhoudsvensterbeleid ontvangt, kan het de gerapporteerde eigenschap van de apparaatdubbel gebruiken om de status van het beleid te rapporteren. De back-end-app kan vervolgens apparaatdubbelquery's gebruiken om de naleving van apparaten en elk beleid te bevestigen.

Volgende stappen

In dit artikel hebt u een directe methode gebruikt om opnieuw opstarten op afstand op een apparaat te activeren. U hebt de gerapporteerde eigenschappen gebruikt om de laatste keer opnieuw opstarten van het apparaat te rapporteren en de apparaatdubbel opgevraagd om de laatste opstarttijd van het apparaat vanuit de cloud te detecteren.

ToAanaan de slag gaan met IoT Hub- en apparaatbeheerpatronen, zoals end-to-end update op basis van afbeeldingen in Device Update voor Azure IoT Hub artikel met behulp van de Raspberry Pi 3 B+-referentieafbeelding.

Zie Taken plannen en uitzenden voor meer informatie over het uitbreiden van uw IoT-oplossing en het plannen van methode-aanroepen op meerdere apparaten.

Delen via

Aan de slag met apparaatbeheer (Python)

Vereisten

Een nieuw apparaat registreren in de IoT-hub

Een apparaat-app maken met een directe methode

De IoT-hub ophalen connection string

Een service-app maken om opnieuw opstarten te activeren

De apps uitvoeren

De acties voor apparaatbeheer aanpassen en uitbreiden

Onderhoudsvensters voor apparaten

Volgende stappen

Aanvullende resources