Directe methoden van IoT Hub begrijpen en aanroepen

  • Artikel

IoT Hub biedt u de mogelijkheid om directe methoden op apparaten aan te roepen vanuit de cloud. De directe methoden omvatten een aanvraag-/antwoordinteractie met een apparaat dat lijkt op een HTTP-aanroep, in die zin dat ze onmiddellijk slagen of mislukken (na een door de gebruiker opgegeven time-out). Deze aanpak is nuttig voor scenario's waarbij het verloop van de onmiddellijke actie verschillend is, afhankelijk van het feit of het apparaat in staat was om te reageren.

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.

Elke apparaatmethode is gericht op één apparaat. Taken plannen op meerdere apparaten laat zien hoe u een manier kunt bieden om directe methoden op meerdere apparaten aan te roepen en hoe u methode-aanroep kunt plannen voor niet-verbonden apparaten.

Iedereen met machtigingen voor serviceverbinding op IoT Hub kan een methode op een apparaat aanroepen.

Directe methoden volgen een aanvraag-antwoordpatroon en zijn bedoeld voor communicatie waarvoor onmiddellijke bevestiging van het resultaat is vereist. Bijvoorbeeld interactieve besturing van het apparaat, zoals het inschakelen van een ventilator.

Raadpleeg De richtlijnen voor cloud-naar-apparaatcommunicatie als u twijfelt tussen het gebruik van de gewenste eigenschappen, directe methoden of cloud-naar-apparaat-berichten.

Levenscyclus van methode

Directe methoden worden geïmplementeerd op het apparaat en vereisen mogelijk nul of meer invoer in de nettolading van de methode om correct te instantiëren. U roept een directe methode aan via een servicegerichte URI ({iot hub}/twins/{device id}/methods/). Een apparaat ontvangt directe methoden via een apparaatspecifiek MQTT-onderwerp ($iothub/methods/POST/{method name}/) of via AMQP-koppelingen (de IoThub-methodname toepassingseigenschappen en IoThub-status ).

Notitie

Wanneer u een directe methode op een apparaat aanroept, kunnen eigenschapsnamen en -waarden alleen us-ASCII-afdrukbare alfanumerieke bevatten, behalve in de volgende set: {'$', '(', ')', '<', '>', '@', ',', ';', ':', '\', '"', '/', '[', ']', '?', '=', '{', '}', SP, HT}

Directe methoden zijn synchroon en slagen of mislukken na de time-outperiode (standaard: 30 seconden, ingesteld tussen 5 en 300 seconden). Directe methoden zijn handig in interactieve scenario's waarin u wilt dat een apparaat reageert als en alleen als het apparaat online is en opdrachten ontvangt. Bijvoorbeeld het inschakelen van een lampje van een telefoon. In deze scenario's wilt u een onmiddellijk succes of mislukking zien, zodat de cloudservice zo snel mogelijk op het resultaat kan reageren. Het apparaat kan een berichttekst retourneren als gevolg van de methode, maar dit is niet vereist voor de methode. Er is geen garantie voor de volgorde of enige gelijktijdigheidssemantiek voor methode-aanroepen.

Directe methoden zijn alleen HTTPS aan de cloudzijde en MQTT, AMQP, MQTT via WebSockets of AMQP via WebSockets aan de apparaatzijde.

De nettolading voor methodeaanvragen en -antwoorden is een JSON-document van maximaal 128 kB.

Een directe methode aanroepen vanuit een back-end-app

Als u een directe methode wilt aanroepen vanuit een back-end-app, gebruikt u de REST API voor apparaatmethode aanroepen of het equivalent daarvan in een van de SDK's van de IoT Hub-service.

Methode-aanroep

Directe methode-aanroepen op een apparaat zijn HTTPS-aanroepen die bestaan uit de volgende items:

  • De aanvraag-URI die specifiek is voor het apparaat, samen met de API-versie:

    https://fully-qualified-iothubname.azure-devices.net/twins/{deviceId}/methods?api-version=2021-04-12

  • De POST-methode

  • Headers die de autorisatie, het inhoudstype en de inhoudscodering bevatten.

  • Een transparante JSON-hoofdtekst in de volgende indeling:

    {
    "connectTimeoutInSeconds": 200,
    "methodName": "reboot",
    "responseTimeoutInSeconds": 200,
    "payload": {
        "input1": "someInput",
        "input2": "anotherInput"
    }
}

De waarde die in de aanvraag wordt opgegevenresponseTimeoutInSeconds, is de hoeveelheid tijd die IoT Hub service moet wachten om een directe methode-uitvoering op een apparaat te voltooien. Stel deze time-out in op ten minste zo lang als de verwachte uitvoeringstijd van een directe methode door een apparaat. Als er geen time-out is opgegeven, wordt de standaardwaarde van 30 seconden gebruikt. De minimum- en maximumwaarden voor responseTimeoutInSeconds zijn respectievelijk 5 en 300 seconden.

De waarde die in de aanvraag wordt opgegevenconnectTimeoutInSeconds, is de hoeveelheid tijd bij het aanroepen van een directe methode waarop IoT Hub service moet wachten totdat een niet-verbonden apparaat online komt. De standaardwaarde is 0, wat betekent dat apparaten al online moeten zijn bij het aanroepen van een directe methode. De maximumwaarde voor connectTimeoutInSeconds is 300 seconden.

Voorbeeld

In dit voorbeeld kunt u veilig een aanvraag initiëren om een directe methode aan te roepen op een IoT-apparaat dat is geregistreerd bij een Azure IoT-hub.

Gebruik eerst de Microsoft Azure IoT-extensie voor Azure CLI om een SharedAccessSignature te maken.

az iot hub generate-sas-token -n <iothubName> --du <duration>

Vervang vervolgens de Authorization-header door uw zojuist gegenereerde SharedAccessSignature en wijzig vervolgens de iothubNameparameters , deviceIdmethodName en payload zodat deze overeenkomen met uw implementatie in de onderstaande voorbeeldopdrachtcurl.

curl -X POST \
  https://<iothubName>.azure-devices.net/twins/<deviceId>/methods?api-version=2021-04-12\
  -H 'Authorization: SharedAccessSignature sr=iothubname.azure-devices.net&sig=x&se=x&skn=iothubowner' \
  -H 'Content-Type: application/json' \
  -d '{
    "methodName": "reboot",
    "responseTimeoutInSeconds": 200,
    "payload": {
        "input1": "someInput",
        "input2": "anotherInput"
    }
}'

Voer de gewijzigde opdracht uit om de opgegeven directe methode aan te roepen. Geslaagde aanvragen retourneren een HTTP 200-statuscode.

Notitie

In het bovenstaande voorbeeld ziet u het aanroepen van een directe methode op een apparaat. Als u een directe methode wilt aanroepen in een IoT Edge-module, moet u de URL-aanvraag wijzigen zoals hieronder wordt weergegeven:

https://<iothubName>.azure-devices.net/twins/<deviceId>/modules/<moduleName>/methods?api-version=2021-04-12

Antwoord

De back-end-app ontvangt een antwoord dat bestaat uit de volgende items:

  • HTTP-statuscode:

    • 200 geeft een geslaagde uitvoering van de directe methode aan;
    • 404 geeft aan dat de apparaat-id ongeldig is of dat het apparaat niet online was bij het aanroepen van een directe methode en voor connectTimeoutInSeconds daarna (gebruik het begeleide foutbericht om de hoofdoorzaak te begrijpen);
    • 504 geeft een time-out van de gateway aan die wordt veroorzaakt doordat het apparaat niet reageert op een directe methode-aanroep binnen responseTimeoutInSeconds.

  • Headers die de aanvraag-id, het inhoudstype en de inhoudscodering bevatten.

  • Een JSON-hoofdtekst in de volgende indeling:

    {
    "status" : 201,
    "payload" : {...}
}

    Zowel status als payload worden geleverd door het apparaat en worden gebruikt om te reageren met de eigen statuscode van het apparaat en het antwoord van de methode.

Methode-aanroep voor IoT Edge-modules

Het aanroepen van directe methoden op een module wordt ondersteund door de REST API van de aanroepmodulemethode of het equivalent ervan in een van de SDK's van de IoT Hub-service.

De moduleId wordt samen met de deviceId doorgegeven in de aanvraag-URI bij gebruik van de REST API of als een parameter bij het gebruik van een service-SDK. Bijvoorbeeld https://<iothubName>.azure-devices.net/twins/<deviceId>/modules/<moduleName>/methods?api-version=2021-04-12. De aanvraagbody en het antwoord zijn vergelijkbaar met die van directe methoden die op het apparaat worden aangeroepen.

Een directe methode op een apparaat verwerken

Op een IoT-apparaat kunnen directe methoden worden ontvangen via MQTT, AMQP of een van deze protocollen via WebSockets. Met de IoT Hub apparaat-SDK's kunt u directe methoden op apparaten ontvangen en erop reageren zonder dat u zich zorgen hoeft te maken over de onderliggende protocoldetails.

MQTT

De volgende sectie is voor het MQTT-protocol. Zie MQTT-protocolondersteuning voor meer informatie over het rechtstreeks gebruiken van het MQTT-protocol met IoT Hub.

Methode-aanroep

Apparaten ontvangen aanvragen voor directe methoden in het MQTT-onderwerp: $iothub/methods/POST/{method name}/?$rid={request id}. De request id wordt echter gegenereerd door IoT Hub en kan niet van tevoren bekend zijn, dus abonneer u op $iothub/methods/POST/# en filter de bezorgde berichten op basis van de methodenamen die worden ondersteund door uw apparaat. (U gebruikt de request id om te reageren.)

De hoofdtekst die het apparaat ontvangt, heeft de volgende indeling:

{
    "input1": "someInput",
    "input2": "anotherInput"
}

Methodeaanvragen zijn QoS 0.

Antwoord

Het apparaat verzendt antwoorden naar $iothub/methods/res/{status}/?$rid={request id}, waarbij:

  • De status eigenschap is de door het apparaat opgegeven status van de methode-uitvoering.

  • De $rid eigenschap is de aanvraag-id van de methode-aanroep die is ontvangen van IoT Hub. De aanvraag-id is een hexadecimale opgemaakte waarde.

De hoofdtekst wordt ingesteld door het apparaat en kan elke status hebben.

AMQP

De volgende sectie is voor het AMQP-protocol. Zie Ondersteuning voor AMQP-protocollen voor meer informatie over het rechtstreeks gebruiken van het AMQP-protocol met IoT Hub.

Methode-aanroep

Het apparaat ontvangt aanvragen voor directe methoden door een ontvangstkoppeling te maken op het adres amqps://{hostname}:5671/devices/{deviceId}/methods/deviceBound.

Het AMQP-bericht komt binnen op de ontvangstkoppeling die de methodeaanvraag vertegenwoordigt. Het bevat de volgende secties:

  • De correlatie-id-eigenschap, die een aanvraag-id bevat die moet worden doorgestuurd met het bijbehorende methodeantwoord.

  • Een toepassingseigenschap met de naam IoThub-methodname, die de naam bevat van de methode die wordt aangeroepen.

  • De AMQP-berichttekst met de nettolading van de methode als JSON.

Antwoord

Het apparaat maakt een verzendende koppeling om het methodeantwoord op het adres amqps://{hostname}:5671/devices/{deviceId}/methods/deviceBoundte retourneren.

Het antwoord van de methode wordt geretourneerd op de verzendende koppeling en is als volgt gestructureerd:

  • De eigenschap correlatie-id, die de aanvraag-id bevat die is doorgegeven in het aanvraagbericht van de methode.

  • Een toepassingseigenschap met de naam IoThub-status, die de door de gebruiker opgegeven methodestatus bevat.

  • De AMQP-berichttekst met het methodeantwoord als JSON.

Aanvullend referentiemateriaal

Andere naslagonderwerpen in de ontwikkelaarshandleiding voor IoT Hub zijn:

Volgende stappen

Nu u hebt geleerd hoe u directe methoden gebruikt, bent u mogelijk geïnteresseerd in het volgende artikel IoT Hub ontwikkelaarshandleiding:

Als u enkele van de concepten die in dit artikel worden beschreven, wilt uitproberen, bent u mogelijk geïnteresseerd in de volgende IoT Hub zelfstudie: