Share via

Directe methoden van IoT Hub begrijpen en aanroepen

Directe methoden van IoT Hub stellen u in staat om op afstand oproepen te doen naar apparaten vanuit de cloud. 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.

Opmerking

De functies die in dit artikel worden beschreven, zijn alleen beschikbaar in de standaardlaag van de IoT Hub. Zie De juiste IoT Hub-laag en -grootte kiezen voor uw oplossing 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 geen of meerdere invoeren in de payload van de methode om correct te instantieren. 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).

Opmerking

Wanneer u een directe methode op een apparaat aanroept, kunnen eigenschapsnamen en -waarden alleen US-ASCII afdrukbare alfanumeriek bevatten, met uitzondering van een willekeurige waarde in de volgende set: $ ( ) < > @ , ; : \ " / [ ] ? = { } SP HT

Directe methoden zijn synchroon en slagen of mislukken na de time-outperiode (standaard 30 seconden; kan worden 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 retourneert mogelijk een berichttekst als gevolg van de methode, maar dit is niet vereist. Er is geen garantie op de volgorde of enige concurrentiesemantiek bij 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 Devices - Invoke Method REST API of het equivalent ervan in een van de IoT Hub-service-SDK's.

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 als responseTimeoutInSeconds in 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-outwaarde wordt opgegeven, wordt de standaardwaarde van 30 seconden gebruikt. De minimum- en maximumwaarden voor responseTimeoutInSeconds zijn 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.

Voorbeeld

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 en wijzig de parameters iothubName, deviceId, methodName, en payload zodat ze overeenkomen met uw implementatie in de volgende voorbeeldopdracht curl.

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.

Opmerking

In het vorige 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> in het volgende voorbeeld:

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

Reactie

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 tijdens het aanroepen van een directe methode en daarna gedurende connectTimeoutInSeconds (gebruik het bijbehorende foutbericht om de hoofdoorzaak te begrijpen);
    • 504 geeft een 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" : {...}
}

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

Methode-aanroep voor IoT Edge-modules

Als u een directe methode voor een module wilt aanroepen, gebruikt u de Modules - Invoke Method REST API of het equivalent ervan in een van de Sdk's van de IoT Hub-service.

De moduleId wordt doorgegeven samen met de deviceId in de aanvraag-URI 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 Communiceren met een IoT-hub met behulp van het MQTT-protocol 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 kan echter niet van tevoren bekend zijn omdat IoT Hub deze genereert, 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 gegenereerde request id functie om te reageren.)

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

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

Methodeaanvragen zijn QoS 0.

Reactie

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

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

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

Het apparaat stelt het lichaam in en kan elke status aannemen.

AMQP (Advanced Message Queuing Protocol)

De volgende sectie is voor het AMQP-protocol. Zie Communiceren met uw IoT-hub met behulp van het AMQP-protocol 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 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 verzoek-id bevat dat met het overeenkomstige methodeantwoord moet worden teruggestuurd.

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

  • De AMQP-berichtinhoud met de payload van de methode als JSON.

Reactie

Het apparaat maakt een verzendlink om het methode-antwoord naar adres amqps://{hostname}:5671/devices/{deviceId}/methods/deviceBoundterug te sturen.

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 weet hoe u directe methoden gebruikt, bent u mogelijk geïnteresseerd in de volgende artikelen met ontwikkelaarshandleiding voor IoT Hub: