Sdílet prostřednictvím

Vysvětlení a vyvolání přímých metod ze služby IoT Hub

Přímé metody Hubu IoT umožňují vzdáleně volat na zařízeních z cloudu. Přímé metody se řídí vzorem odezvy požadavku a jsou určené pro komunikaci, která vyžaduje okamžité potvrzení výsledku. Například interaktivní ovládání zařízení, například zapnutí ventilátoru. Tato funkce je užitečná ve scénářích, kdy se průběh okamžité akce liší v závislosti na tom, jestli zařízení dokázalo reagovat.

Poznámka:

Funkce popsané v tomto článku jsou k dispozici pouze na úrovni Standard služby IoT Hub. Další informace o úrovních Basic a Standard/Free IoT Hub najdete v tématu Volba správné úrovně a velikosti služby IoT Hub pro vaše řešení.

Každá metoda zařízení cílí na jedno zařízení. Pokud chcete vyvolat přímé metody na více zařízeních nebo naplánovat metody pro odpojená zařízení, přečtěte si téma Plánování úloh na více zařízeních.

Každý, kdo má oprávnění k připojení služby na IoT Hub, může vyvolat metodu na zařízení.

Pokud máte pochybnosti o používání požadovaných vlastností, přímých metod nebo zpráv typu cloud-zařízení, přečtěte si pokyny ke komunikaci typu Cloud-zařízení .

Životní cyklus metody

Přímé metody jsou implementovány na zařízení a mohou ke správnému vytvoření instance vyžadovat nula nebo více vstupů v datové části metody. Přímou metodu vyvoláte prostřednictvím URI určeného pro služby ({iot hub}/twins/{device id}/methods/). Zařízení přijímá přímé metody prostřednictvím tématu MQTT specifického pro zařízení ($iothub/methods/POST/{method name}/) nebo prostřednictvím odkazů AMQP (IoThub-methodname a IoThub-status vlastností aplikace).

Poznámka:

Při vyvolání přímé metody v zařízení můžou názvy a hodnoty vlastností obsahovat pouze US-ASCII tisknutelné alfanumerické znaky s výjimkou některé z následujících množiny: $ ( ) < > @ , ; : \ " / [ ] ? = { } SP HT

Přímé metody jsou synchronní a buď úspěšné, nebo neúspěšné po uplynutí časového limitu (výchozí 30 sekund; nastavená mezi 5 a 300 sekundy). Přímé metody jsou užitečné v interaktivních scénářích, kdy chcete, aby zařízení fungovalo, pokud je zařízení online a přijímá příkazy. Například zapnutí světla z telefonu. V těchto scénářích chcete vidět okamžitý úspěch nebo selhání, aby cloudová služba mohl reagovat na výsledek co nejdříve. Zařízení může v důsledku metody vrátit text zprávy, ale není to nutné. U volání metod neexistuje žádná záruka na řazení ani žádnou sémantiku souběžnosti.

Přímé metody jsou pouze HTTPS z cloudové strany a MQTT, AMQP, MQTT přes WebSockets nebo AMQP přes WebSockety ze strany zařízení.

Datová část pro žádosti o metody a odpovědi je dokument JSON až 128 kB.

Vyvolání přímé metody z back-endové aplikace

Pokud chcete z back-end aplikace vyvolat přímou metodu, použijte REST API Devices – Invoke Method nebo jeho ekvivalent v některé z sad SDK služby IoT Hub.

Vyvolání metody

Volání přímé metody na zařízení jsou volání HTTPS, která se skládají z následujících položek:

  • Identifikátor URI požadavku specifický pro zařízení spolu s verzí rozhraní API:

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

  • Metoda POST

  • Hlavičky , které obsahují autorizaci, typ obsahu a kódování obsahu.

  • Průhledné tělo JSON v následujícím formátu:

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

Hodnota zadaná jako responseTimeoutInSeconds v požadavku je doba, po kterou musí služba IoT Hub čekat na dokončení provádění přímé metody na zařízení. Nastavte tento časový limit tak, aby byl alespoň tak dlouhý jako očekávaná doba provádění přímé metody zařízení. Pokud není zadaná hodnota časového limitu, použije se výchozí hodnota 30 sekund. Minimální a maximální hodnoty pro responseTimeoutInSeconds jsou 5 a 300 sekund.

Hodnota zadaná connectTimeoutInSeconds v požadavku představuje dobu, po kterou musí služba IoT Hub po vyvolání přímé metody čekat, než se odpojené zařízení znovu připojí online. Výchozí hodnota je 0, což znamená, že zařízení musí být při vyvolání přímé metody již online. Maximální hodnota je connectTimeoutInSeconds 300 sekund.

Příklad

Tento příklad iniciuje požadavek na vyvolání přímé metody na zařízení IoT zaregistrované v Centru Azure IoT.

Začněte tím, že pomocí rozšíření Microsoft Azure IoT pro Azure CLI vytvoříte SharedAccessSignature.

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

Dále nahraďte autorizační hlavičku nově vygenerovaným SharedAccessSignature, pak upravte iothubName, methodNamedeviceIda payload parametry tak, aby odpovídaly vaší implementaci v následujícím příkladu curl příkazu.

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

Spuštěním upraveného příkazu vyvoláte zadanou přímou metodu. Úspěšné požadavky vrátí stavový kód HTTP 200.

Poznámka:

Předchozí příklad ukazuje vyvolání přímé metody na zařízení. Pokud chcete vyvolat přímou metodu v modulu IoT Edge, upravte požadavek adresy URL tak, aby zahrnoval /modules/<moduleName> , jak je znázorněno v následujícím příkladu:

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

Odezva

Back-endová aplikace obdrží odpověď, která se skládá z následujících položek:

  • Stavový kód HTTP:

    • 200 označuje úspěšné provedení přímé metody;
    • 404 označuje, že ID zařízení je neplatné, nebo že zařízení nebylo online během vyvolání přímé metody a poté po celou dobu connectTimeoutInSeconds; použijte doprovodnou chybovou zprávu k pochopení původní příčiny.
    • 504 značí vypršení časového limitu brány způsobeného tím, že zařízení nereaguje na volání přímé metody v rámci responseTimeoutInSeconds.

  • Hlavičky , které obsahují ID požadavku, typ obsahu a kódování obsahu.

  • JSON tělo v následujícím formátu:

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

    Zařízení poskytuje obojí, status a payload, a používá je k reagování pomocí vlastního stavového kódu zařízení a odpovědi metody.

Vyvolání metody pro moduly IoT Edge

Pokud chcete v modulu vyvolat přímou metodu, použijte moduly – Invoke Method REST API nebo jeho ekvivalent v jedné ze sad SDK služby IoT Hub.

moduleId se předá spolu s deviceId v identifikátoru URI požadavku při použití rozhraní REST API nebo jako parametr při použití sady SDK služby. Například https://<iothubName>.azure-devices.net/twins/<deviceId>/modules/<moduleName>/methods?api-version=2021-04-12. Tělo požadavku a odpověď se podobají přímým metodám vyvolaným na zařízení.

Zpracování přímé metody na zařízení

Na zařízení IoT lze přímé metody přijímat přes MQTT, AMQP nebo některý z těchto protokolů přes WebSockets. Sady SDK pro zařízení služby IoT Hub pomáhají přijímat přímé metody na zařízeních a reagovat na ně, aniž byste se museli starat o podrobnosti souvisejícího protokolu.

MQTT

Následující část je určená pro protokol MQTT. Další informace o použití protokolu MQTT přímo se službou IoT Hub najdete v tématu Komunikace se službou IoT Hub pomocí protokolu MQTT.

Vyvolání metody

Zařízení přijímají žádosti o přímé metody v tématu MQTT: $iothub/methods/POST/{method name}/?$rid={request id}. Není ale možné to předem vědět, request id protože ho IoT Hub vygeneruje, takže se přihlaste k odběru $iothub/methods/POST/# a pak vyfiltrujte doručené zprávy na základě názvů metod podporovaných vaším zařízením. (Použijete vygenerovanou request id pro odpověď.)

Tělo, které zařízení přijímá, má následující formát:

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

Požadavky metod jsou QoS 0.

Odezva

Zařízení odesílá odpovědi na $iothub/methods/res/{status}/?$rid={request id}, kde:

  • Vlastnost status je stav spuštění metody zadaný zařízením.

  • Vlastnost $rid je ID požadavku z volání metody přijaté ze služby IoT Hub. ID požadavku je šestnáctková formátovaná hodnota.

Zařízení nastaví tělo a může mít libovolný stav.

AMQP

Následující část je určená pro protokol AMQP. Další informace o použití protokolu AMQP přímo se službou IoT Hub najdete v tématu Komunikace se službou IoT Hub pomocí protokolu AMQP.

Vyvolání metody

Zařízení přijímá žádosti o přímé metody vytvořením odkazu pro přijímání na adrese amqps://{hostname}:5671/devices/{deviceId}/methods/deviceBound.

Zpráva AMQP dorazí na přijímací odkaz, který zprostředkovává požadavek metody. Obsahuje následující části:

  • Vlastnost ID korelace obsahující ID požadavku, které by mělo být předáno zpět s odpovídající odpovědí metody.

  • Vlastnost aplikace s názvem IoThub-methodname, která obsahuje název vyvoláné metody.

  • Text zprávy AMQP obsahující datovou část metody ve formátu JSON.

Odezva

Zařízení vytvoří odesílající odkaz pro vrácení odpovědi metody na adrese amqps://{hostname}:5671/devices/{deviceId}/methods/deviceBound.

Odpověď metody se vrátí na odesílajícím odkazu a je strukturovaná takto:

  • Vlastnost ID korelace, která obsahuje ID požadavku předané ve zprávě požadavku metody.

  • Vlastnost aplikace s názvem IoThub-status, která obsahuje stav metody zadané uživatelem.

  • Text zprávy AMQP obsahující odpověď metody ve formátu JSON.

Další kroky

Teď, když víte, jak používat přímé metody, může vás zajímat následující články příručky pro vývojáře ioT Hubu:

  • Last updated on