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

  • Cikk

Az IoT Hub lehetővé teszi, hogy az eszközökön közvetlen metódusokat hívjon meg a felhőből. A közvetlen metódusok kérés-válasz jellegű kapcsolatot valósítanak meg az eszközzel, amely a HTTP-hívásokhoz hasonló annyiban, hogy vagy sikeres, vagy azonnal meghiúsul (a felhasználó által megadott idő túllépése után). Ez a módszer olyan helyzetekben hasznos, amikor az azonnali művelet végrehajtása eltérő attól függően, hogy az eszköz válaszképes volt-e.

Megjegyzés

A cikkben ismertetett funkciók csak a IoT Hub standard szintjén érhetők el. Az alapszintű és standard/ingyenes IoT Hub szintekkel kapcsolatos további információkért lásd: A megoldáshoz megfelelő IoT Hub szint kiválasztása.

Minden eszközmetódus egyetlen eszközt céloz meg. A feladatok ütemezése több eszközön bemutatja, hogyan hívhat meg közvetlen metódusokat több eszközön, és hogyan ütemezhet metódushívást a leválasztott eszközökhöz.

Bárki, aki szolgáltatáscsatlakozási engedéllyel rendelkezik a IoT Hub meghívhat egy metódust egy eszközö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 az eszköz interaktív vezérlése, például egy ventilátor bekapcsolása.

Ha kétségei vannak a kívánt tulajdonságok, a közvetlen módszerek vagy a felhőből az eszközre irányuló üzenetek használata között, tekintse meg a felhőbő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ív meg egy szolgáltatással elérhető 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 és IoThub-status az IoThub-methodname alkalmazás tulajdonságain) keresztül.

Megjegyzés

Amikor közvetlen metódust hív meg egy eszközön, a tulajdonságnevek és -értékek csak az US-ASCII nyomtatható alfanumerikus elemeket tartalmazhatják, kivéve az alábbi készlet 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értelmezett: 30 másodperc, 5 és 300 másodperc közötti beállítás). A közvetlen metódusok olyan interaktív forgatókönyvekben hasznosak, ahol azt szeretné, hogy az eszköz csak akkor és csak akkor működjön, ha az eszköz online állapotban van, és parancsokat fogad. Kapcsoljon be például egy lámpát egy telefonról. 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 egy üzenettörzset ad vissza a metódus eredményeként, de ehhez nincs szükség rá. A metódushívások megrendelésére és egyidejűségére nincs garancia.

A közvetlen metódusok https-onlyek a felhő oldaláról, az MQTT, az AMQP, a WebSockets MQTT vagy az eszközoldali WebSocketeken keresztüli AMQP.

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 az Eszköz metódusának MEGHÍVÁSa REST API-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 az API-verzióval együtt:

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

  • A POST metódus

  • Az engedélyezést, a tartalomtípust és a 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ő, amelyet IoT Hub szolgáltatásnak várnia kell egy közvetlen metódus végrehajtásának befejezésére az eszközön. Állítsa ezt az időtúllépést legalább addig, amíg az eszköz egy közvetlen metódusának várt végrehajtási ideje. Ha nincs megadva időtúllépés, a rendszer az alapértelmezett 30 másodperces értéket használja. A minimális és maximális értékek responseTimeoutInSeconds 5 és 300 másodperc.

A kérésben megadott connectTimeoutInSeconds érték az a közvetlen metódus meghívásakor eltelt idő, amelyet IoT Hub szolgáltatásnak várnia kell a 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 lehetővé teszi egy közvetlen metódus meghívására irányuló kérés biztonságos kezdeményezését egy Azure IoT Hubban regisztrált IoT-eszközön.

Első lépésként használja az Azure CLI-hez készült Microsoft Azure IoT-bővítményt 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, methodNamedeviceIdés payload paramétert, hogy megfeleljen 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"
    }
}'

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

Megjegyzé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ítania kell az URL-kérést az alábbiak szerint:

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

Reagálás

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álja a mellékelt 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 rendszeren belüli responseTimeoutInSecondsközvetlen metódushívásra.

  • 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 közvetlen metódusok modulon való meghívását a REST API meghívása modulmetódus vagy annak megfelelője támogatja az egyik IoT Hub szolgáltatás SDK-jában.

A moduleId rendszer a deviceId kérelem URI-jával együtt adja át a rest API használatakor vagy paraméterként a 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érés 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 ezek 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 a mögöttes protokoll részletei miatt kellene aggódnia.

MQTT

Az alábbi szakasz az MQTT protokollt ismerteti. Az MQTT protokoll IoT Hub való közvetlen használatáról az MQTT-protokoll támogatásáról szóló cikkben olvashat bővebben.

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}. Azonban a request id IoT Hub hozza létre, és nem ismert 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 következőt fogja használni.)

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

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

A metóduskérelmek a QoS 0.

Reagálás

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 a IoT Hub 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

A következő szakasz az AMQP protokollhoz tartozik. Az AMQP protokoll közvetlenül a IoT Hub való használatáról az AMQP protokoll támogatásáról szóló cikkben olvashat bővebben.

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.

  • A nevű IoThub-methodnamealkalmazástulajdonság, amely a meghívandó metódus nevét tartalmazza.

  • Az AMQP üzenettörzse, amely a metódus hasznos adatait tartalmazza JSON-ként.

Reagálás

Az eszköz létrehoz egy küldő hivatkozást, amely visszaadja a metódus válaszát a címen 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.

  • A nevű IoThub-statusalkalmazástulajdonság, amely tartalmazza a felhasználó által megadott metódus állapotát.

  • Az AMQP üzenettörzse, amely a metódus válaszát tartalmazza JSON-ként.

További referenciaanyag

A IoT Hub fejlesztői útmutató további referenciatémakörök a következők:

Következő lépések

Most, hogy megismerte a közvetlen metódusok használatát, a következő IoT Hub fejlesztői útmutatót ismertető cikk érdekelheti:

Ha ki szeretné próbálni a cikkben ismertetett fogalmakat, az alábbi IoT Hub oktatóanyag érdekelheti: