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

  • Článek

Přímé metody IoT Hubu umožňují vzdáleně volat volání 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 Služby IoT Hub úrovně Basic a Standard/Free najdete v tématu Volba správné úrovně IoT Hubu 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í pro připojení služby ve službě 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 v zařízení a mohou vyžadovat, aby správně vytvořily instanci nuly nebo více vstupů v datové části metody. Přímou metodu vyvoláte prostřednictvím identifikátoru URI ({iot hub}/twins/{device id}/methods/service-facing). 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 (vlastností 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 tisknutelné alfanumerické znaky US-ASCII 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é v rozmezí 5 až 300 sekund). 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 nevyžaduje se. 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 vyvolat přímou metodu z back-endové aplikace, použijte rozhraní REST API metody Invoke zařízení nebo jeho ekvivalent v jedné ze 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á v responseTimeoutInSeconds 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 aspoň tak dlouho, dokud zařízení očekávanou dobu provádění přímé metody. Pokud časový limit není zadaný, použije se výchozí hodnota 30 sekund. Minimální a maximální hodnoty jsou responseTimeoutInSeconds 5 a 300 sekund.

Hodnota zadaná connectTimeoutInSeconds v požadavku je doba po vyvolání přímé metody, kterou služba IoT Hub musí čekat, až se odpojené zařízení přepojí do režimu 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 deviceIdiothubName, a payload parametry tak, methodName aby odpovídaly vaší implementaci v příkladu curl příkazu níže.

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, upravte požadavek adresy URL tak, aby zahrnoval /modules/<moduleName> , jak je znázorněno níže:

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

Response

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 při vyvolání přímé metody a následně connectTimeoutInSeconds (k pochopení původní příčiny použijte doprovodnou chybovou zprávu);
    • 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.

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

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

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

Vyvolání metody pro moduly IoT Edge

Volání přímých metod v modulu je podporováno rozhraním REST API metody vyvolání modulu nebo jeho ekvivalentem v jedné ze sad SDK služby IoT Hub.

Předává se moduleId 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. Tělo požadavku a odpověď se podobají přímém metodám 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 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 Podpora protokolů 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}. Služba IoT Hub je request id však vygenerovaná a předem ji nelze znát, proto 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 request id možnost odpovědět.)

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

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

Požadavky na metody jsou QoS 0.

Response

Zařízení odesílá odpovědi na $iothub/methods/res/{status}/?$rid={request id}adresu , 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é ze služby IoT Hub. ID požadavku je šestnáctková formátovaná hodnota.

Tělo je nastavené zařízením a může se jednat o jakýkoli 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 Podpora protokolu AMQP.

Vyvolání metody

Zařízení přijímá žádosti přímé metody vytvořením odkazu na 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 se mělo předat 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 ve formátu JSON.

Response

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ď jste se dozvěděli, jak používat přímé metody, může vás zajímat následující článek příručky pro vývojáře ioT Hubu: