Share via

Közvetlen metódusok megismerése és meghívása az IoT Hubból

  • Cikk

Az IoT Hub közvetlen metódusai lehetővé teszik a hívások távoli meghívását a felhőből származó eszközökön. A közvetlen metódusok egy kérés-válasz mintát követnek, és olyan kommunikációra szolgálnak, amelyek azonnali megerősítést igényelnek az eredményükről. Például egy eszköz interaktív vezérlése, például egy ventilátor bekapcsolása. Ez a funkció olyan helyzetekben hasznos, ahol az azonnali művelet menete eltér attól függően, hogy az eszköz képes volt-e válaszolni.

Feljegyzés

A cikkben ismertetett funkciók csak az IoT Hub standard szintjén érhetők el. Az alapszintű és standard/ingyenes IoT Hub-szintekről további információt a megoldáshoz megfelelő IoT Hub-szint kiválasztása című témakörben talál.

Minden eszközmetódus egyetlen eszközt céloz meg. Ha több eszközön szeretne közvetlen metódusokat meghívni, vagy a leválasztott eszközökhöz ütemezni szeretné a metódusokat, olvassa el a Feladatok ütemezése több eszközön című témakört.

Az IoT Hub szolgáltatáscsatlakozási engedélyeivel rendelkezők meghívhatnak egy metódust egy eszközön.

Ha kétségei vannak a kívánt tulajdonságok, a közvetlen metódusok vagy a felhőből az eszközre irányuló üzenetek használata között, tekintse meg a felhőről eszközre irányuló kommunikációs útmutatót .

Metódus életciklusa

A közvetlen metódusok implementálva vannak az eszközön, és a helyes példányosításhoz nulla vagy több bemenetre lehet szükség a metódus hasznos adataiban. Közvetlen metódust hívhat meg egy szolgáltatásoldali URI-n ({iot hub}/twins/{device id}/methods/). Az eszközök közvetlen metódusokat kapnak egy eszközspecifikus MQTT-témakörön ($iothub/methods/POST/{method name}/) vagy AMQP-hivatkozásokon (az IoThub-methodnameIoThub-status alkalmazás tulajdonságain) keresztül.

Feljegyzés

Ha közvetlen metódust hív meg egy eszközön, a tulajdonságnevek és -értékek csak US-ASCII nyomtatható alfanumerikus elemeket tartalmazhatnak, kivéve az alábbi csoportok bármelyikét: $ ( ) < > @ , ; : \ " / [ ] ? = { } SP HT

A közvetlen metódusok szinkronok, és az időtúllépési időszak után sikeresek vagy sikertelenek (alapértelmezés szerint 30 másodperc; 5 és 300 másodperc közötti beállítás). A közvetlen metódusok olyan interaktív helyzetekben hasznosak, ahol azt szeretné, hogy az eszköz akkor és csak akkor működjön, ha az eszköz online állapotban van, és parancsokat fogad. Például bekapcsolja a telefon fényét. Ezekben a forgatókönyvekben azonnali sikert vagy hibát szeretne látni, hogy a felhőszolgáltatás a lehető leghamarabb reagáljon az eredményre. Előfordulhat, hogy az eszköz a metódus eredményeként egy üzenettörzset ad vissza, de nem szükséges. A metódushívások megrendelésére és egyidejűségére nincs garancia.

A közvetlen metódusok csak a felhőből származó HTTPS- és MQTT-, AMQP-, MQTT-alapú websocketeken keresztüli, vagy AMQP-ként használhatók az eszközoldali WebSocketeken keresztül.

A metóduskérések és válaszok hasznos adata egy legfeljebb 128 KB-os JSON-dokumentum.

Közvetlen metódus meghívása háttéralkalmazásból

Ha közvetlen metódust szeretne meghívni egy háttéralkalmazásból, használja a REST API meghívási eszközmetódusát vagy annak megfelelőjét az IoT Hub szolgáltatás SDK-k egyikében.

Metódushívás

Az eszközön a közvetlen metódushívások OLYAN HTTPS-hívások, amelyek a következő elemekből állnak:

  • Az eszközre vonatkozó kérés URI-ja és az API-verzió:

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

  • A POST metódus

  • Az engedélyezést, tartalomtípust és tartalomkódolást tartalmazó fejlécek .

  • Transzparens JSON-törzs a következő formátumban:

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

A kérelemben megadott responseTimeoutInSeconds érték az az idő, amíg az IoT Hub szolgáltatásnak várnia kell egy közvetlen metódus végrehajtására az eszközön. Állítsa be ezt az időtúllépést legalább addig, amíg az eszköz egy közvetlen metódus várható végrehajtási idejét nem számítja ki. Ha nincs megadva időtúllépés, a rendszer az alapértelmezett 30 másodperces értéket használja. A minimális és a maximális érték responseTimeoutInSeconds 5 és 300 másodperc.

A kérelemben megadott connectTimeoutInSeconds érték az az idő, amikor az IoT Hub szolgáltatásnak várnia kell egy leválasztott eszköz online állapotba helyezésére. Az alapértelmezett érték 0, ami azt jelenti, hogy az eszközöknek már online állapotban kell lenniük egy közvetlen metódus meghívásakor. A maximális érték connectTimeoutInSeconds 300 másodperc.

Példa

Ez a példa egy közvetlen metódus meghívására irányuló kérést kezdeményez egy Azure IoT Hubon regisztrált IoT-eszközön.

Első lépésként használja az Azure CLI Microsoft Azure IoT-bővítményét a SharedAccessSignature létrehozásához.

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

Ezután cserélje le az Engedélyezés fejlécet az újonnan létrehozott SharedAccessSignature-ra, majd módosítsa a iothubName, deviceIdés payload paramétereket úgy, methodName hogy azok megfeleljenek az alábbi példaparancs curl implementációjának.

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

Hajtsa végre a módosított parancsot a megadott közvetlen metódus meghívásához. A sikeres kérelmek egy HTTP 200 állapotkódot adnak vissza.

Feljegyzés

A fenti példa egy közvetlen metódus meghívását mutatja be egy eszközön. Ha közvetlen metódust szeretne meghívni egy IoT Edge-modulban, módosítsa az URL-kérést úgy, hogy az az alábbiak szerint szerepeljen /modules/<moduleName> :

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

Válasz

A háttéralkalmazás a következő elemekből álló választ kapja:

  • HTTP-állapotkód:

    • a 200 a közvetlen módszer sikeres végrehajtását jelzi;
    • A 404 azt jelzi, hogy bármelyik eszközazonosító érvénytelen, vagy hogy az eszköz nem volt online egy közvetlen módszer meghívásakor és connectTimeoutInSeconds azt követően (a kiváltó ok megértéséhez használjon kísérő hibaüzenetet);
    • Az 504 azt jelzi, hogy az átjáró időtúllépését az okozza, hogy az eszköz nem válaszol a belső közvetlen metódushívásra responseTimeoutInSeconds.

  • A kérelemazonosítót, a tartalomtípust és a tartalomkódolást tartalmazó fejlécek .

  • JSON-törzs a következő formátumban:

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

    payload Mindkettőt status az eszköz biztosítja, és az eszköz saját állapotkódjával és a metódus válaszával válaszol.

Metódushívás IoT Edge-modulokhoz

A modul közvetlen metódusainak meghívását a REST API meghívási metódusa vagy annak megfelelője támogatja az IoT Hub szolgáltatás SDK-k egyikében.

A moduleId rendszer a deviceId kérelem URI-jával együtt adja át a REST API használatakor vagy paraméterként szolgáltatás SDK használatakor. Például: https://<iothubName>.azure-devices.net/twins/<deviceId>/modules/<moduleName>/methods?api-version=2021-04-12. A kérelem törzse és válasza hasonló az eszközön meghívott közvetlen metódusokhoz.

Közvetlen metódus kezelése egy eszközön

IoT-eszközön közvetlen metódusok fogadhatók MQTT- vagy AMQP-protokollon keresztül, vagy ezen protokollok bármelyike websocketeken keresztül. Az IoT Hub eszközoldali SDK-k segítenek a közvetlen metódusok fogadásában és megválaszolásában az eszközökön anélkül, hogy aggódnia kellene az alapul szolgáló protokoll részletei miatt.

MQTT

Az alábbi szakasz az MQTT protokollt ismerteti. Az MQTT protokoll IoT Hubbal való közvetlen használatáról további információt az MQTT protokoll támogatásával kapcsolatban talál.

Metódushívás

Az eszközök közvetlen metóduskéréseket kapnak az MQTT témakörében: $iothub/methods/POST/{method name}/?$rid={request id}. Az request id IoT Hub által létrehozott üzenetek azonban nem ismertek előre, ezért iratkozzon fel $iothub/methods/POST/# , majd szűrje a kézbesített üzeneteket az eszköz által támogatott metódusnevek alapján. (A válaszhoz a request id választ fogja használni.)

Az eszköz által kapott törzs a következő formátumban van:

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

A metóduskérések A QoS 0.

Válasz

Az eszköz a következő helyre $iothub/methods/res/{status}/?$rid={request id}küld válaszokat:

  • A status tulajdonság a metódus végrehajtásának eszköz által megadott állapota.

  • A $rid tulajdonság az IoT Hubtól kapott metódushívás kérésazonosítója. A kérelem azonosítója hexadecimális formátumú érték.

A törzset az eszköz állítja be, és bármilyen állapotú lehet.

AMQP

Az alábbi szakasz az AMQP protokollt ismerteti. Az AMQP protokoll IoT Hubbal való közvetlen használatáról további információt az AMQP protokoll támogatásával kapcsolatban talál.

Metódushívás

Az eszköz közvetlen metóduskéréseket fogad egy fogadási hivatkozás létrehozásával a címen amqps://{hostname}:5671/devices/{deviceId}/methods/deviceBound.

Az AMQP üzenet a metóduskérést jelképező fogadási hivatkozásra érkezik. A következő szakaszokat tartalmazza:

  • A korrelációs azonosító tulajdonság, amely egy kérésazonosítót tartalmaz, amelyet vissza kell adni a megfelelő metódus válaszával.

  • Egy alkalmazástulajdonság neve IoThub-methodname, amely a meghívandó metódus nevét tartalmazza.

  • A metódus hasznos adatait JSON-ként tartalmazó AMQP-üzenet törzse.

Válasz

Az eszköz létrehoz egy küldési hivatkozást, amely visszaadja a metódus válaszát a címben amqps://{hostname}:5671/devices/{deviceId}/methods/deviceBound.

A metódus válasza a küldő hivatkozáson lesz visszaadva, és a következőképpen van strukturálva:

  • A korrelációs azonosító tulajdonság, amely a metódus kérésüzenetében átadott kérelemazonosítót tartalmazza.

  • Egy alkalmazástulajdonság neve IoThub-status, amely a felhasználó által megadott metódusállapotot tartalmazza.

  • A metódusválaszt JSON-ként tartalmazó AMQP-üzenet törzse.

Következő lépések

Most, hogy megismerte a közvetlen módszerek használatát, az alábbi IoT Hub fejlesztői útmutatót ismertető cikk érdekelheti: