Share via

Directe methoden van IoT Hub begrijpen en aanroepen

  • Artikel

Met directe methoden van IoT Hub kunt u op afstand aanroepen op apparaten vanuit de cloud aanroepen. Directe methoden volgen een aanvraag-antwoordpatroon en zijn bedoeld voor communicatie waarvoor onmiddellijke bevestiging van het resultaat is vereist. Bijvoorbeeld interactieve besturing van een apparaat, zoals het inschakelen van een ventilator. Deze functionaliteit is handig voor scenario's waarbij de directe actie verschilt, afhankelijk van of het apparaat kon 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 Basic- en Standard-/gratis IoT Hub-lagen.

Elke apparaatmethode is gericht op één apparaat. Als u directe methoden op meerdere apparaten wilt aanroepen of methoden wilt plannen voor niet-verbonden apparaten, raadpleegt u Taken plannen op meerdere apparaten.

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

Raadpleeg de communicatierichtlijnen voor cloud-naar-apparaten als u twijfelt over het gebruik van gewenste eigenschappen, directe methoden of berichten over cloud-naar-apparaat.

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 en IoThub-status toepassingseigenschappen).

Notitie

Wanneer u een directe methode op een apparaat aanroept, kunnen eigenschapsnamen en -waarden alleen alfanumeriek 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 licht van een telefoon. In deze scenario's wilt u onmiddellijk een succes of storing zien, zodat de cloudservice zo snel mogelijk kan reageren op het resultaat. Het apparaat kan een berichttekst retourneren als gevolg van de methode, maar dit is niet vereist. Er is geen garantie voor het bestellen of eventuele gelijktijdigheidssemantiek voor methode-aanroepen.

Directe methoden zijn alleen HTTPS van de cloudzijde en MQTT, AMQP, MQTT via WebSockets of AMQP via WebSockets vanaf 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 ervan in een van de SDK's van de IoT Hub-service.

Methode-aanroep

Aanroepen van directe methoden 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 codering van inhoud bevatten.

  • Een transparante JSON-hoofdtekst in de volgende indeling:

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

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

De waarde die is opgegeven zoals connectTimeoutInSeconds in de aanvraag, is de hoeveelheid tijd bij het aanroepen van een directe methode waarvoor de 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 300 seconden.

Opmerking

In dit voorbeeld wordt een aanvraag gestart 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 autorisatieheader door uw zojuist gegenereerde SharedAccessSignature, wijzig vervolgens de iothubName, deviceIdmethodName en payload parameters 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 hoe u een directe methode op een apparaat aanroept. Als u een directe methode wilt aanroepen in een IoT Edge-module, wijzigt u de URL-aanvraag zodat deze wordt opgenomen /modules/<moduleName> zoals hieronder wordt weergegeven:

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

Respons

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

  • HTTP-statuscode:

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

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

  • Een JSON-hoofdtekst in de volgende indeling:

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

    Beide status en 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 voor 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 in de aanvraag-URI doorgegeven wanneer u de REST API of als parameter gebruikt bij het gebruik van een service-SDK. Bijvoorbeeld: https://<iothubName>.azure-devices.net/twins/<deviceId>/modules/<moduleName>/methods?api-version=2021-04-12. De hoofdtekst en het antwoord van de aanvraag 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 SDK's voor IoT Hub-apparaten kunt u directe methoden op apparaten ontvangen en erop reageren zonder dat u zich zorgen hoeft te maken over de details van het onderliggende protocol.

MQTT

De volgende sectie is voor het MQTT-protocol. Zie ondersteuning voor MQTT-protocollen voor meer informatie over het gebruik van het MQTT-protocol rechtstreeks met IoT Hub.

Methode-aanroep

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

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

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

Methodeaanvragen zijn QoS 0.

Respons

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

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

  • De $rid eigenschap is de aanvraag-id van de aanroep van de methode 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 zijn.

AMQP

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

Methode-aanroep

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

Het AMQP-bericht arriveert op de ontvangstkoppeling die de methodeaanvraag vertegenwoordigt. Deze bevat de volgende secties:

  • De eigenschap correlatie-id, 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 hoofdtekst van het AMQP-bericht met de nettolading van de methode als JSON.

Respons

Het apparaat maakt een verzendende koppeling om het antwoord van de methode 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 hoofdtekst van het AMQP-bericht met het antwoord van de methode als JSON.

Volgende stappen

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