Dela via

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

Med IoT Hub-direktmetoder kan du fjärranropa anrop på enheter från molnet. Direkta metoder följer ett mönster för begäran-svar och är avsedda för kommunikation som kräver omedelbar bekräftelse av resultatet. Till exempel interaktiv kontroll av en enhet, till exempel att aktivera en fläkt. Den här funktionen är användbar för scenarier där åtgärdens gång skiljer sig åt beroende på om enheten kunde svara.

Anmärkning

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

Varje enhetsmetod riktar sig till en enda enhet. Om du vill anropa direktmetoder på flera enheter eller schemalägga metoder för frånkopplade enheter läser du Schemalägg jobb på flera enheter.

Alla med tjänstanslutningsbehörigheter på IoT Hub kan anropa en metod på en enhet.

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 moln till enhet.

Metodlivscykel

Direktmetoder implementeras på enheten och kan kräva noll eller fler indata i metodens nyttolast för att instansiera korrekt. Du anropar en direktmetod via en tjänstinriktad 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-methodname och IoThub-status programegenskaper).

Anmärkning

När du anropar en direktmetod på en enhet kan egenskapsnamn och värden endast innehålla utskrivbara alfanumeriska tecken från US-ASCII, förutom de 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 bara om enheten är online och tar emot kommandon. Du kan till exempel slå på 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. Det finns ingen garanti för ordningen eller samtidighetssemantik vid metodanrop.

Direktmetoder är ENDAST HTTPS från molnsidan och MQTT, AMQP, MQTT över WebSockets eller AMQP via 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 back-end-applikation

Om du vill anropa en direktmetod från en serverdelsapp använder du REST API :et Devices – Invoke Method eller dess motsvarighet i någon av IoT Hub-tjänstens 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änsten måste invänta för slutförandet av en direkt metodkörning på en enhet. Ställ in denna tidsgräns så att den är minst så lång som den förväntade körningstiden för en direktmetod av enheten. Om ett timeout-värde inte anges används standardvärdet 30 sekunder. Minimi- och maxvärdena för responseTimeoutInSeconds är 5 respektive 300 sekunder.

Värdet som anges i connectTimeoutInSeconds begäran är den tid vid anrop av en direktmetod som IoT Hub-tjänsten måste vänta på för 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

I det här exemplet initieras 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 sedan parametrarna iothubName, deviceId, methodNameoch payload så att de matchar implementeringen i följande exempelkommando 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"
    }
}'

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

Anmärkning

I föregående exempel visas hur du anropar en direktmetod på en enhet. Om du vill anropa en direktmetod i en IoT Edge-modul ändrar du URL-begäran så att den inkluderas /modules/<moduleName> enligt följande exempel:

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

Svar

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

  • HTTP-statuskod:

    • 200 anger ett lyckat genomförande av direktmetoden.
    • 404 anger att antingen enhets-ID är ogiltigt eller att enheten inte var online vid anrop av en direktmetod och därefter för connectTimeoutInSeconds (använd det medföljande felmeddelandet för att förstå rotorsaken);
    • 504 anger gatewayens 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

Om du vill anropa en direktmetod i en modul använder du REST API:et Modules – Invoke Method eller dess motsvarighet i någon av IoT Hub-tjänstens 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 direkt metod på en enhet

På en IoT-enhet kan direkta metoder tas emot via MQTT, AMQP eller något av dessa protokoll via WebSockets. IoT Hub-enhetens SDK:er 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 Kommunicera med en IoT-hubb med MQTT-protokollet.

Metodanrop

Enheter tar emot förfrågningar om direktmetoder i MQTT-ämnet: $iothub/methods/POST/{method name}/?$rid={request id}. Det går dock inte att känna till request id i förväg eftersom IoT Hub genererar det, så prenumerera på $iothub/methods/POST/# och filtrera sedan de levererade meddelandena baserat på metodnamn som stöds av enheten. (Du använder den genererade request id för att svara.)

Enhetens mottagna innehåll är i följande format:

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

Metodbegäranden är QoS 0.

Svar

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

  • Egenskapen status är enhetens status för utförande av metoden.

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

Enheten sätter kroppen och kan ha vilken status som helst.

AMQP

Följande avsnitt är för AMQP-protokollet. Mer information om hur du använder AMQP-protokollet direkt med IoT Hub finns i Kommunicera med din IoT-hubb med hjälp av AMQP-protokollet.

Metodanrop

Enheten tar emot begäranden om direktmetoder 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.

Svar

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

Metodens svar returneras på den sändande lä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 den angivna metodstatusen för användaren.

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

Nästa steg

Nu när du vet hur du använder direkta metoder kan du vara intresserad av följande artiklar i utvecklarguiden för IoT Hub: