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

  • Článek

IoT Hub umožňuje vyvolat přímé metody na zařízeních z cloudu. Přímé metody představují interakci typu požadavek-odpověď se zařízením, která je podobná volání HTTP v tom, že je ihned (po uplynutí časového limitu zadaného uživatelem) úspěšná nebo neúspěšná. Tento přístup je užitečný v případě scénářů, kdy se průběh okamžité akce liší podle toho, jestli zařízení bylo schopné reagovat.

Poznámka

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

Každá metoda zařízení cílí na jedno zařízení. Plánování úloh na více zařízeních ukazuje, jak poskytnout způsob, jak vyvolat přímé metody na více zařízeních, a naplánovat vyvolání metody pro odpojená zařízení.

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

Přímé metody se řídí vzorem požadavků a odpovědí 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.

Pokud máte pochybnosti o použití požadovaných vlastností, přímých metod nebo zpráv z cloudu do zařízení, projděte si pokyny ke komunikaci mezi cloudem a zařízením .

Životní cyklus metody

Přímé metody jsou na zařízení implementované a ke správnému vytvoření instance můžou vyžadovat nula nebo více vstupů v datové části metody. Přímou metodu vyvoláte prostřednictvím identifikátoru URI () směřujícího ke službě ({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 vlastnosti aplikace a IoThub-status ).

Poznámka

Při vyvolání přímé metody na zařízení můžou názvy vlastností a hodnoty obsahovat pouze tištěnou alfanumerickou hodnotu US-ASCII, s výjimkou libovolné v následující sadě: {'$', '(', ')', '<', '>', '@', ',', ';', ':', '\', '"', '/', '[', ']', '?', '=', '{', '}', SP, HT}

Přímé metody jsou synchronní a po uplynutí časového limitu buď proběhnou úspěšně, nebo selžou (výchozí nastavení: 30 sekund, nastavitelné mezi 5 a 300 sekundy). Přímé metody jsou užitečné v interaktivních scénářích, kdy chcete, aby zařízení fungovalo pouze v případě, že 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 co nejdříve reagovala na výsledek. Zařízení může v důsledku metody vrátit část textu zprávy, ale není to nutné, aby to metoda udělala. U volání metod není zaručeno řazení ani sémantiku souběžnosti.

Přímé metody jsou pouze HTTPS ze strany cloudu a MQTT, AMQP, MQTT přes WebSocket nebo AMQP přes WebSocket ze strany zařízení.

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

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

Pokud chcete vyvolat přímou metodu z back-endové aplikace, použijte rozhraní REST API pro vyvolání metody zařízení nebo jeho ekvivalent v jedné ze sad SDK služby IoT Hub.

Vyvolání metody

Přímé volání 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 obsahující autorizaci, typ obsahu a kódování obsahu.

  • Transparentní text 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í spuštění přímé metody na zařízení. Nastavte tento časový limit tak, aby byl alespoň tak dlouhý jako očekávaná doba spuštění přímé metody zařízením. Pokud časový limit není zadaný, použije se výchozí hodnota 30 sekund. Minimální a maximální hodnota pro responseTimeoutInSeconds jsou 5 a 300 sekund.

Hodnota zadaná jako connectTimeoutInSeconds v požadavku je doba po vyvolání přímé metody, kterou IoT Hub služba musí čekat, než odpojené zařízení přejde do režimu online. Výchozí hodnota je 0, což znamená, že zařízení už musí být online při vyvolání přímé metody. Maximální hodnota pro connectTimeoutInSeconds je 300 sekund.

Příklad

Tento příklad vám umožní bezpečně zahájit požadavek na vyvolání přímé metody na zařízení IoT zaregistrované ve službě Azure IoT Hub.

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 hlavičku Authorization nově vygenerovaným parametrem SharedAccessSignature a pak upravte iothubNameparametry , deviceIdmethodName a payload 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

Výše uvedený příklad ukazuje vyvolání přímé metody na zařízení. Pokud chcete vyvolat přímou metodu v modulu IoT Edge, budete muset upravit požadavek adresy URL, jak je znázorněno níže:

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

Odpověď

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 po vyvolání přímé metody a pro connectTimeoutInSeconds poté (použijte doprovodnou chybovou zprávu k pochopení původní příčiny);
    • 504 označuje časový limit brány způsobený tím, že zařízení nereaguje na přímé volání metody v rámci responseTimeoutInSeconds.

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

  • Text JSON v následujícím formátu:

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

    Zařízení poskytuje i status a payload slouží k reakci pomocí vlastního stavového kódu zařízení a odpovědi metody.

Vyvolání metody pro moduly IoT Edge

Vyvolání přímých metod v modulu podporuje rozhraní REST API metody Invoke modulu nebo jeho ekvivalent v jedné ze sad SDK služby IoT Hub.

Parametr moduleId se předá společně s identifikátorem deviceId 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. Text požadavku a odpověď jsou podobné jako u přímých metod vyvolaných 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 WebSocket. Sady SDK IoT Hub zařízení vám pomůžou přijímat přímé metody a reagovat na ně na zařízeních, aniž byste si museli dělat starosti s podrobnostmi souvisejícího protokolu.

MQTT

Následující část je určená pro protokol MQTT. Další informace o použití protokolu MQTT přímo s IoT Hub najdete v tématu Podpora 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}. request id Vygeneruje ho ale IoT Hub a není možné ho předem zjistit, takže se přihlaste k $iothub/methods/POST/# odběru a potom vyfiltrujte doručované zprávy na základě názvů metod podporovaných vaším zařízením. (K odpovědi použijete request id příkaz .)

Tělo, které zařízení obdrží, je v následujícím formátu:

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

Požadavky metody jsou QoS 0.

Odpověď

Zařízení odesílá odpovědi na adresu $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 vyvolání metody přijaté z IoT Hub. ID požadavku je šestnáctková formátovaná hodnota.

Tělo je nastaveno zařízením a může být jakýkoli stav.

AMQP

Následující část je určena pro protokol AMQP. Další informace o použití protokolu AMQP přímo s IoT Hub najdete v tématu Podpora protokolu AMQP.

Vyvolání metody

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

Zpráva AMQP přijde na odkaz pro příjem, který představuje požadavek metody. Obsahuje následující oddíly:

  • Vlastnost ID korelace, která obsahuje 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 metody, která je vyvolána.

  • Text zprávy AMQP obsahující datovou část metody jako JSON.

Odpověď

Zařízení vytvoří odesílající odkaz, který vrátí odpověď 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 jako JSON.

Další referenční materiály

Mezi další referenční témata v příručce pro vývojáře IoT Hub patří:

Další kroky

Teď jste se naučili používat přímé metody a mohl by vás zajímat následující článek IoT Hub příručce pro vývojáře:

Pokud si chcete vyzkoušet některé koncepty popsané v tomto článku, mohly by vás zajímat následující IoT Hub kurzu: