Directe methoden van IoT Hub begrijpen en aanroepen

IoT Hub biedt u de mogelijkheid om directe methoden aan te roepen op apparaten vanuit de cloud. Directe methoden vertegenwoordigen een interactie tussen aanvraag en antwoord met een apparaat dat vergelijkbaar is met een HTTP-aanroep in 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. Raadpleeg How to choose the right IoT Hub tier (De juiste IoT Hub-prijscategorie kiezen) voor meer informatie over de Basic- en Standard/gratis-prijscategorieën van IoT Hub.

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

Iedereen met service connect-machtigingen 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 interactief beheer van het apparaat, zoals het in-/uitschakelen van een ventilator.

Raadpleeg Richtlijnen voor communicatie tussen cloud en apparaat als u twijfelt over het gebruik van gewenste eigenschappen, directe methoden of cloud-naar-apparaat-berichten.

Levenscyclus van methoden

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

Notitie

Wanneer u een directe methode op een apparaat aanroept, kunnen eigenschapsnamen en -waarden alleen alfanumerieke us-ASCII-afdrukbare waarden bevatten, met uitzondering van een 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 werkt als en alleen als het apparaat online is en opdrachten ontvangt. Bijvoorbeeld het in-/uitschakelen van een lampje vanaf een telefoon. In deze scenario's wilt u onmiddellijk een succes of fout zien, zodat de cloudservice zo snel mogelijk op het resultaat kan reageren. Het apparaat kan een berichtbericht retourneren als gevolg van de methode , maar dit is niet vereist voor de methode. Er is geen garantie op volgorde of gelijktijdigheidssemantiek voor methodeaanroepen.

Directe methoden zijn alleen HTTPS vanuit de cloud 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

Roep nu een directe methode aan vanuit een back-end-app.

Methode aanroepen

Aanroepen van directe methoden op een apparaat zijn HTTPS-aanroepen die uit de volgende items zijn:

  • 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=2018-06-30
    
  • De POST-methode

  • Headers die de autorisatie, aanvraag-id, inhoudstype en inhoudscoderen bevatten.

  • Een transparante JSON-body in de volgende indeling:

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

De waarde die is opgegeven als in de aanvraag is de hoeveelheid tijd die IoT Hub service moet wachten op voltooiing van de uitvoering van een directe methode responseTimeoutInSeconds op een apparaat. 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 30 seconden gebruikt. De minimum- en maximumwaarden responseTimeoutInSeconds voor zijn respectievelijk 5 en 300 seconden.

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

Voorbeeld

In dit voorbeeld kunt u een aanvraag voor het aanroepen van een directe methode veilig initiëren op een IoT-apparaat dat is geregistreerd bij een Azure IoT Hub.

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

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

Vervang vervolgens de autorisatie-header door de zojuist gegenereerde SharedAccessSignature en wijzig vervolgens de parameters , en om te voldoen aan uw implementatie in de iothubName deviceId methodName payload curl onderstaande voorbeeldopdracht.

curl -X POST \
  https://<iothubName>.azure-devices.net/twins/<deviceId>/methods?api-version=2018-06-30 \
  -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 wordt het aanroepen van een directe methode op een apparaat gedemonstreerd. 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=2018-06-30

Antwoord

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 na het aanroepen van een directe methode en daarna (gebruik het begeleide foutbericht om de hoofdoorzaak te connectTimeoutInSeconds begrijpen);
    • 504 geeft de time-out van de gateway aan die wordt veroorzaakt doordat het apparaat niet reageert op een aanroep van de directe methode in responseTimeoutInSeconds .
  • Headers die de ETag, aanvraag-id, inhoudstype en inhoudscoderen bevatten.

  • Een JSON-body in de volgende indeling:

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

    Zowel als worden geleverd door het apparaat en gebruikt om te reageren met de eigen status body statuscode en/of beschrijving van het apparaat.

Methode aanroepen voor IoT Edge modules

Het aanroepen van directe methoden met behulp van een module-id wordt ondersteund in de C# SDK van de IoT-serviceclient.

Gebruik hiervoor de methode en ServiceClient.InvokeDeviceMethodAsync() geef de en door als deviceId moduleId parameters.

Een directe methode op een apparaat verwerken

Laten we eens kijken hoe u een directe methode op een IoT-apparaat kunt afhandelen.

MQTT

De volgende sectie is voor het MQTT-protocol.

Methode aanroepen

Apparaten ontvangen aanvragen voor directe methoden in het MQTT-onderwerp: $iothub/methods/POST/{method name}/?$rid={request id} . Het aantal abonnementen per apparaat is beperkt tot 5. Daarom is het raadzaam om u niet afzonderlijk te abonneren op elke directe methode. In plaats daarvan kunt u zich abonneren op $iothub/methods/POST/# en vervolgens de bezorgde berichten filteren op basis van de gewenste methodenamen.

De body 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 uitvoering van de methode.

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

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

AMQP

De volgende sectie is voor het AMQP-protocol.

Methode aanroepen

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

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

  • De eigenschap correlatie-id, die een aanvraag-id bevat die moet worden door gegeven met het bijbehorende methode-antwoord.

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

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

Antwoord

Het apparaat maakt een verzendende koppeling om het antwoord van de methode op adres te amqps://{hostname}:5671/devices/{deviceId}/methods/deviceBound 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 toepassings-eigenschap met IoThub-status de naam , die de door de gebruiker opgegeven methodestatus bevat.

  • De AMQP-bericht-body met het antwoord van de methode als JSON.

Aanvullend referentiemateriaal

Andere naslagonderwerpen in de IoT Hub ontwikkelaarshandleiding zijn onder andere:

  • IoT Hub eindpunten worden de verschillende eindpunten beschreven die elke IoT-hub blootstelt voor run-time- en beheerbewerkingen.

  • Beperking en quota beschrijven de quota die van toepassing zijn en het beperkingsgedrag dat u kunt verwachten wanneer u IoT Hub.

  • SDK's voor Azure IoT-apparaten en -service bevat de verschillende taal-SDK's die u kunt gebruiken bij het ontwikkelen van apparaat- en service-apps die communiceren met IoT Hub.

  • IoT Hub querytaal voor apparaattweeling, taken en berichtroutering wordt de IoT Hub-querytaal beschreven die u kunt gebruiken om informatie op te halen uit IoT Hub over uw apparaattweelingen en taken.

  • IoT Hub ondersteuning voor MQTT biedt meer informatie over IoT Hub ondersteuning voor het MQTT-protocol.

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 een aantal concepten wilt uitproberen die in dit artikel worden beschreven, bent u mogelijk geïnteresseerd in de volgende IoT Hub zelfstudie: