Megosztás a következőn keresztül:

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

Az IoT Hub közvetlen metódusok 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.

Megjegyzés

A cikkben ismertetett funkciók csak az IoT Hub standard szintjén érhetők el. Az alapszintű és standard/ingyenes IoT Hub-szintekkel kapcsolatban további információkért lásd Válassza ki a megoldása számára megfelelő IoT Hub-szintet és -méretet.

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 szeretne metódusokat ütemezni, tekintse meg Feladatok ütemezése több eszközöncímű témakört.

Bárki, aki rendelkezik az IoT Hubon szolgáltatáshoz tartozó engedélyekkel, meghívhat egy metódust az eszközön.

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

Metódus életciklusa

Direct methods are implemented on the device and might require zero or more inputs in the method payload to correctly instantiate. Ön egy közvetlen metódust hív meg egy szolgáltatáshoz tartozó URI-n keresztül ({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 keresztül (a IoThub-methodname és IoThub-status alkalmazástulajdonságokon keresztül).

Megjegyzés

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

A közvetlen módszerek szinkron módon működnek, és az időtúllépési időintervallum után vagy sikeresek, vagy sikertelenek (alapértelmezettként 30 másodperc, 5 és 300 másodperc között beállítható). 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. There's no guarantee on ordering or any concurrency semantics on method calls.

A közvetlen módszerek a felhő oldalon csak HTTPS-en keresztül érhetők el, míg az eszköz oldaláról MQTT-t, AMQP-t, MQTT-t WebSocketeken, vagy AMQP-t WebSocketeken keresztül lehet használni.

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 Eszközök – Metódus meghívása REST API-t vagy annak megfelelőjét az IoT Hub szolgáltatás SDK-k egyikében.

Method invocation

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

  • The request URI specific to the device along with the API version:

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

  • The POST method

  • fejlécek, amelyek tartalmazzák az engedélyezést, a tartalomtípust és a tartalomkódolást.

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

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

A kérelemben responseTimeoutInSeconds megadott é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 olyan hosszúra, mint egy eszköz közvetlen metódusának várható végrehajtási ideje. Ha nincs megadva időtúllépési érték, a rendszer az alapértelmezett 30 másodperces értéket használja. A responseTimeoutInSeconds minimális és maximális értéke 5 és 300 másodperc.

A kérelemben connectTimeoutInSeconds megadott érték egy közvetlen módszer meghívásakor megadott idő, amelyet az IoT Hub szolgáltatásnak várnia kell a leválasztott eszköz online állapotba helyezéséhez. 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 connectTimeoutInSeconds maximális értéke 300 másodperc.

Example

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, methodNameés payload paramétereket az alábbi példa curl parancs implementációjának megfelelően.

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.

Megjegyzés

Az előző 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 /modules/<moduleName> szerepeljen az alábbi példában látható módon:

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 az eszközazonosító érvénytelen, vagy hogy az eszköz nem volt online egy közvetlen módszer meghívásakor és az azt követő connectTimeoutInSeconds időszak alatt (a hiba okának megértéséhez használja a mellékelt hibaüzenetet);
    • 504 indicates gateway time-out caused by device not responding to a direct method call within responseTimeoutInSeconds.

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

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

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

    Mind a status, mind a payload az eszköz által biztosítottak, és az eszköz saját állapotkódjával valamint a módszer válaszával válaszolnak.

Metódushívás IoT Edge-modulokhoz

Ha közvetlen metódust szeretne meghívni egy modulon, használja a Modul – Metódus meghívása REST API-t vagy annak megfelelőjét az egyik IoT Hub szolgáltatás SDK-jában.

A moduleId és a deviceId együtt továbbítódik a kérelem URI-jában, amikor a REST API-t használják, vagy paraméterként, amikor szolgáltatás SDK-t használnak. Például: https://<iothubName>.azure-devices.net/twins/<deviceId>/modules/<moduleName>/methods?api-version=2021-04-12. The request body and response is similar to that of direct methods invoked on the device.

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öz 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. Ha többet szeretne megtudni az MQTT protokoll közvetlen IoT Hubbal való használatáról, olvassa el Kommunikáció egy IoT Hubbal az MQTT protokollhasználatával.

Method invocation

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}. A request id azonban nem ismerhető előre, mert az IoT Hub létrehozza azt, ezért iratkozzon fel a $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 létrehozott request id-t kell használnia.)

Az eszköz által kapott adatok a következő formátumban vannak:

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

A metóduskérések QoS 0 értékűek.

Válasz

Az eszköz válaszokat küld $iothub/methods/res/{status}/?$rid={request id}-ra, ahol:

  • 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.

The device sets the body and can be any status.

AMQP

Az alábbi szakasz az AMQP protokollt ismerteti. Ha többet szeretne megtudni az AMQP protokoll közvetlen IoT Hubbal való használatáról, olvassa el Kommunikáció az IoT Hubbal az AMQP Protokollhasználatával.

Method invocation

Az eszköz közvetlen módszerkérelmeket fogad egy fogadó link 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 IoThub-methodnamenevű alkalmazástulajdonság, amely a meghívandó metódus nevét tartalmazza.

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

Válasz

The device creates a sending link to return the method response on address 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 IoThub-statusnevű alkalmazástulajdonság, 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 már ismeri a közvetlen módszerek használatát, az alábbi IoT Hub fejlesztői útmutatókban olvashat:

  • Last updated on