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

  • Artikel

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.

Kommentar

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å 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 behörigheter för tjänstanslutning 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 molnet till enheten.

Metodlivscykel

Direkta metoder 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 egenskaperna och IoThub-status programmet).

Kommentar

När du anropar en direktmetod på en enhet kan egenskapsnamn och värden endast innehålla alfanumeriskt tal som kan skrivas ut med US-ASCII, förutom något 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 beställning 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 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ä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 i responseTimeoutInSeconds begäran är den tid som IoT Hub-tjänsten måste vänta på att en direkt metodkörning på en enhet ska slutföras. Ange att tidsgränsen ska vara minst så länge 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. 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, deviceIdmethodName och 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.

Kommentar

Exemplet ovan visar 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 nedan:

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

Response

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

  • 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 (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 module method eller dess motsvarighet i någon av IoT Hub-tjänst-SDK:erna.

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. 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. 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 MQTT-protokollstöd.

Metodanrop

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

Response

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 är för 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 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.

Response

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 metodens status.

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

Nästa steg

Nu när du har lärt dig hur du använder direkta metoder kan du vara intresserad av följande artikel i utvecklarguiden för IoT Hub: