Förstå och anropa direktmetoder från IoT Hub

  • Artikel

IoT Hub ger dig möjlighet att anropa direktmetoder på enheter från molnet. Direktmetoderna representerar en interaktion med en enhet via förfrågan/svar som liknar ett HTTP-anrop på så sätt att de utförs eller misslyckas omedelbart (efter en tidsgräns som användaren anger). Den här metoden passar bra i scenarier där vad som ska utföras beror på om enheten svarar eller inte.

Anteckning

Funktionerna som beskrivs i den här artikeln är endast tillgängliga på standardnivån för IoT Hub. Mer information om nivåerna grundläggande och standard/kostnadsfri IoT Hub finns i Välj rätt IoT Hub nivå för din lösning.

Varje enhetsmetod riktar sig mot en enda enhet. Schemalägg jobb på flera enheter visar hur du tillhandahåller ett sätt att anropa direktmetoder på flera enheter och schemalägga metodanrop för frånkopplade enheter.

Alla med behörigheter för tjänstanslutning på IoT Hub kan anropa en metod på en enhet.

Direkta metoder följer ett mönster för begärandesvar och är avsedda för kommunikation som kräver omedelbar bekräftelse av resultatet. Till exempel interaktiv kontroll av enheten, till exempel att aktivera en fläkt.

Se vägledningen för kommunikation från moln till enhet om du är osäker på om du vill använda önskade egenskaper, direkta metoder eller meddelanden från molnet till enheten.

Metodlivscykel

Direktmetoder implementeras på enheten och kan kräva noll eller flera indata i metodens nyttolast för att instansieras korrekt. Du anropar en direktmetod via en tjänstriktad URI ({iot hub}/twins/{device id}/methods/). En enhet tar emot direkta metoder via ett enhetsspecifikt MQTT-ämne ($iothub/methods/POST/{method name}/) eller via AMQP-länkar (IoThub-statusIoThub-methodname och programegenskaper).

Anteckning

När du anropar en direktmetod på en enhet kan egenskapsnamn och värden bara innehålla alfanumeriska us-ASCII-utskrivbara, utom i följande uppsättning: {'$', '(', ')', '<', '>', '@', ',', ';', ':', '\', '"', '/', '[', ']', '?', '=', '{', '}', SP, HT}

Direkta metoder är synkrona och lyckas eller misslyckas efter tidsgränsen (standard: 30 sekunder, kan anges mellan 5 och 300 sekunder). Direktmetoder är användbara i interaktiva scenarier där du vill att en enhet ska agera om och endast om enheten är online och tar emot kommandon. Du kan till exempel aktivera en lampa från en telefon. I dessa scenarier vill du se en omedelbar framgång eller ett fel så att molntjänsten kan agera på resultatet så snart som möjligt. Enheten kan returnera en del meddelandetext som ett resultat av metoden, men det krävs inte för att metoden ska göra det. Det finns ingen garanti för beställning eller samtidighetssemantik vid metodanrop.

Direktmetoder är endast HTTPS från molnsidan och MQTT, AMQP, MQTT över WebSockets eller AMQP över WebSockets från enhetssidan.

Nyttolasten för metodbegäranden och svar är ett JSON-dokument på upp till 128 kB.

Anropa en direktmetod från en serverdelsapp

Om du vill anropa en direktmetod från en serverdelsapp använder du REST-API:et Invoke device method eller dess motsvarighet i någon av IoT Hub tjänst-SDK:er.

Metodanrop

Direktmetodanrop på en enhet är HTTPS-anrop som består av följande objekt:

  • Begärande-URI:n som är specifik för enheten tillsammans med API-versionen:

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

  • POST-metoden

  • Rubriker som innehåller auktorisering, innehållstyp och innehållskodning.

  • En transparent JSON-brödtext i följande format:

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

Värdet som anges som responseTimeoutInSeconds i begäran är den tid som IoT Hub tjänst måste vänta för slutförandet av en direkt metodkörning på en enhet. Ange att den här tidsgränsen ska vara minst lika lång som den förväntade körningstiden för en direktmetod av en enhet. Om tidsgränsen inte anges används standardvärdet 30 sekunder. De lägsta och högsta värdena för responseTimeoutInSeconds är 5 respektive 300 sekunder.

Värdet som anges i connectTimeoutInSeconds begäran är hur lång tid vid anrop av en direktmetod som IoT Hub tjänsten måste vänta på att en frånkopplad enhet ska kunna anslutas. Standardvärdet är 0, vilket innebär att enheterna redan måste vara online vid anrop av en direktmetod. Det maximala värdet för connectTimeoutInSeconds är 300 sekunder.

Exempel

Med det här exemplet kan du på ett säkert sätt initiera en begäran om att anropa en direktmetod på en IoT-enhet som är registrerad på en Azure IoT-hubb.

Börja med att använda Microsoft Azure IoT-tillägget för Azure CLI för att skapa en SharedAccessSignature.

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

Ersätt sedan auktoriseringshuvudet med din nyligen genererade SharedAccessSignature och ändra parametrarna iothubName, methodNamedeviceIdoch payload så att de matchar implementeringen i exempelkommandot curl nedan.

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"
    }
}'

Kör det ändrade kommandot för att anropa den angivna direktmetoden. Lyckade begäranden returnerar en HTTP 200-statuskod.

Anteckning

Exemplet ovan visar hur du anropar en direktmetod på en enhet. Om du vill anropa en direktmetod i en IoT Edge-modul måste du ändra URL-begäran enligt nedan:

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

Svarsåtgärder

Serverdelsappen får ett svar som består av följande objekt:

  • HTTP-statuskod:

    • 200 anger en lyckad körning av direktmetoden.
    • 404 anger att enhets-ID:t är ogiltigt eller att enheten inte var online vid anrop av en direktmetod och därefter (använd åtföljt felmeddelande för connectTimeoutInSeconds att förstå rotorsaken);
    • 504 anger gateway-timeout som orsakas av att enheten inte svarar på ett direkt metodanrop inom responseTimeoutInSeconds.

  • Rubriker som innehåller begärande-ID, innehållstyp och innehållskodning.

  • En JSON-brödtext i följande format:

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

    Både status och payload tillhandahålls av enheten och används för att svara med enhetens egen statuskod och metodsvaret.

Metodanrop för IoT Edge moduler

Att anropa direktmetoder i en modul stöds av REST-API:et Invoke-modulmetoden eller dess motsvarighet i någon av IoT Hub tjänst-SDK:er.

moduleId skickas tillsammans med deviceId i begärande-URI:n när du använder REST-API:et eller som en parameter när du använder en tjänst-SDK. Till exempel https://<iothubName>.azure-devices.net/twins/<deviceId>/modules/<moduleName>/methods?api-version=2021-04-12. Begärandetexten och svaret liknar de direkta metoder som anropas på enheten.

Hantera en direktmetod på en enhet

På en IoT-enhet kan direkta metoder tas emot via MQTT, AMQP eller något av dessa protokoll via WebSockets. De IoT Hub enhets-SDK:erna hjälper dig att ta emot och svara på direkta metoder på enheter utan att behöva oroa dig för den underliggande protokollinformationen.

MQTT

Följande avsnitt gäller för MQTT-protokollet. Mer information om hur du använder MQTT-protokollet direkt med IoT Hub finns i MQTT-protokollstöd.

Metodanrop

Enheter tar emot begäranden om direktmetod i MQTT-ämnet: $iothub/methods/POST/{method name}/?$rid={request id}. request id Men genereras av IoT Hub och kan inte vara känd i förväg, så prenumerera på $iothub/methods/POST/# och filtrera sedan de levererade meddelandena baserat på metodnamn som stöds av din enhet. (Du använder request id för att svara.)

Brödtexten som enheten tar emot är i följande format:

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

Metodbegäranden är QoS 0.

Svarsåtgärder

Enheten skickar svar till $iothub/methods/res/{status}/?$rid={request id}, där:

  • Egenskapen status är statusen som tillhandahålls av enheten för metodkörning.

  • Egenskapen $rid är begärande-ID:t från metodanropet som tagits emot från IoT Hub. Begärande-ID:t är ett hexadecimalt formaterat värde.

Brödtexten anges av enheten och kan vara valfri status.

AMQP

Följande avsnitt gäller AMQP-protokollet. Mer information om hur du använder AMQP-protokollet direkt med IoT Hub finns i AMQP-protokollstöd.

Metodanrop

Enheten tar emot begäranden om direktmetod genom att skapa en mottagningslänk på adressen amqps://{hostname}:5671/devices/{deviceId}/methods/deviceBound.

AMQP-meddelandet tas emot på mottagarlänken som representerar metodbegäran. Den innehåller följande avsnitt:

  • Korrelations-ID-egenskapen, som innehåller ett begärande-ID som ska skickas tillbaka med motsvarande metodsvar.

  • En programegenskap med namnet IoThub-methodname, som innehåller namnet på den metod som anropas.

  • AMQP-meddelandetexten som innehåller metodens nyttolast som JSON.

Svarsåtgärder

Enheten skapar en skickande länk för att returnera metodsvaret på adressen amqps://{hostname}:5671/devices/{deviceId}/methods/deviceBound.

Metodens svar returneras på sändningslänken och är strukturerad på följande sätt:

  • Korrelations-ID-egenskapen, som innehåller det begärande-ID som skickades i metodens begärandemeddelande.

  • En programegenskap med namnet IoThub-status, som innehåller användarens angivna metodstatus.

  • AMQP-meddelandetexten som innehåller metodsvaret som JSON.

Ytterligare referensmaterial

Andra referensämnen i IoT Hub utvecklarguiden är:

Nästa steg

Nu när du har lärt dig hur du använder direktmetoder kan du vara intresserad av följande artikel IoT Hub utvecklarguide:

Om du vill prova några av de begrepp som beskrivs i den här artikeln kan du vara intresserad av följande IoT Hub självstudie: