Udostępnij za pomocą

Omówienie i wywoływanie metod bezpośrednich z usługi IoT Hub

Metody bezpośrednie usługi IoT Hub umożliwiają zdalne wywoływanie wywołań na urządzeniach z chmury. Metody bezpośrednie są zgodne ze wzorcem żądania-odpowiedzi i są przeznaczone do komunikacji, która wymaga natychmiastowego potwierdzenia ich wyniku. Na przykład interaktywna kontrola urządzenia, taka jak włączanie wentylatora. Ta funkcja jest przydatna w scenariuszach, w których przebieg natychmiastowego działania różni się w zależności od tego, czy urządzenie mogło odpowiedzieć.

Uwaga

Funkcje opisane w tym artykule są dostępne tylko w warstwie Standardowa usługi IoT Hub. Aby uzyskać więcej informacji na temat warstw podstawowej i standardowej/bezpłatnej usługi IoT Hub, zobacz Wybieranie odpowiedniej warstwy i rozmiaru usługi IoT Hub dla rozwiązania.

Każda metoda urządzenia dotyczy jednego urządzenia. Jeśli chcesz wywołać metody bezpośrednie na wielu urządzeniach lub zaplanować metody rozłączenia urządzeń, zobacz Planowanie zadań na wielu urządzeniach.

Każda osoba z uprawnieniami połączenia z usługą w usłudze IoT Hub może wywołać metodę na urządzeniu.

Zapoznaj się ze wskazówkami dotyczącymi komunikacji chmura-urządzenie , jeśli nie ma wątpliwości co do używania żądanych właściwości, metod bezpośrednich lub komunikatów z chmury do urządzenia.

Cykl życia metody

Metody bezpośrednie są implementowane na urządzeniu i mogą wymagać od zera lub większej liczby danych wejściowych w ładunku metody, aby poprawnie utworzyć wystąpienie. Metodę bezpośrednią wywołujesz poprzez identyfikator URI, który kieruje do usługi ({iot hub}/twins/{device id}/methods/). Urządzenie odbiera metody bezpośrednie za pośrednictwem tematu MQTT specyficznego dla urządzenia ($iothub/methods/POST/{method name}/) lub za pośrednictwem linków protokołu AMQP (właściwości aplikacji IoThub-methodname i IoThub-status).

Uwaga

Podczas wywoływania metody bezpośredniej na urządzeniu nazwy właściwości i wartości mogą zawierać tylko drukowalne znaki alfanumeryczne US-ASCII, z wyjątkiem następującego zestawu: $ ( ) < > @ , ; : \ " / [ ] ? = { } SP HT

Metody bezpośrednie są synchroniczne i kończą się powodzeniem lub niepowodzeniem po upływie limitu czasu (domyślnie 30 sekund; można ustawić w zakresie od 5 do 300 sekund). Metody bezpośrednie są przydatne w scenariuszach interaktywnych, w których urządzenie ma działać tylko wtedy, gdy urządzenie jest w trybie online i odbiera polecenia. Na przykład włączenie światła z telefonu. W tych scenariuszach zależy ci na natychmiastowym sukcesie lub niepowodzeniu, żeby usługa w chmurze mogła zareagować na wynik tak szybko, jak to możliwe. Urządzenie może zwrócić treść komunikatu jako wynik działania metody, ale nie jest to wymagane. W przypadku wywołań metod nie ma żadnej gwarancji co do kolejności ani semantyki współbieżności.

Metody bezpośrednie są tylko HTTPS po stronie chmury oraz MQTT, AMQP, MQTT przez WebSocket lub AMQP przez WebSocket po stronie urządzenia.

Ładunek danych dla żądań i odpowiedzi metody może mieć postać dokumentu JSON o rozmiarze do 128 KB.

Wywołaj bezpośrednią metodę z aplikacji back-endu

Aby wywołać metodę bezpośrednią z poziomu aplikacji back-endowej, użyj REST API Devices - Invoke Method lub jego odpowiednika w jednym z zestawów SDK usługi IoT Hub.

Wywołanie metody

Wywołania metody bezpośredniej na urządzeniu to wywołania HTTPS, które składają się z następujących elementów:

  • Identyfikator URI żądania specyficzny dla urządzenia wraz z wersją interfejsu API:

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

  • Metoda POST

  • Nagłówki zawierające autoryzację, typ zawartości i kodowanie zawartości.

  • Przejrzysta treść JSON w następującym formacie:

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

Wartość podana jako responseTimeoutInSeconds w żądaniu to czas oczekiwania usługi IoT Hub na ukończenie wykonania metody bezpośredniej na urządzeniu. Ustaw ten limit czasu na co najmniej tyle czasu, ile wynosi oczekiwany czas wykonywania metody bezpośredniej urządzenia. Jeśli nie podano wartości limitu czasu, zostanie użyta wartość domyślna 30 sekund. Minimalne i maksymalne wartości dla responseTimeoutInSeconds to odpowiednio 5 i 300 sekund.

Wartość określona jako connectTimeoutInSeconds w żądaniu to ilość czasu, jaką usługa IoT Hub musi czekać po wywołaniu metody bezpośredniej, na pojawienie się odłączonego urządzenia w trybie online. Wartość domyślna to 0, co oznacza, że urządzenia muszą być już w trybie online po wywołaniu metody bezpośredniej. Wartość maksymalna wynosi connectTimeoutInSeconds 300 sekund.

Przykład

W tym przykładzie zainicjowano żądanie wywołania metody bezpośredniej na urządzeniu IoT zarejestrowanym w centrum Azure IoT Hub.

Aby rozpocząć, użyj rozszerzenia Microsoft Azure IoT dla Azure CLI, aby utworzyć podpis SharedAccessSignature.

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

Następnie zastąp nagłówek Authorization nowo wygenerowaną wartością SharedAccessSignature, a potem zmodyfikuj parametry iothubName, deviceId, methodName i payload, aby pasowały do implementacji w poniższym przykładowym poleceniu curl.

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

Wykonaj zmodyfikowane polecenie, aby wywołać określoną metodę bezpośrednią. Żądania zakończone powodzeniem zwracają kod stanu HTTP 200.

Uwaga

W poprzednim przykładzie pokazano wywołanie metody bezpośredniej na urządzeniu. Jeśli chcesz wywołać metodę bezpośrednią w module usługi IoT Edge, zmodyfikuj żądanie adresu URL tak, aby zostało uwzględnione /modules/<moduleName> w poniższym przykładzie:

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

Odpowiedź

Aplikacja zaplecza otrzymuje odpowiedź zawierającą następujące elementy:

  • Kod stanu HTTP:

    • 200 wskazuje pomyślne wykonanie metody bezpośredniej;
    • 404 wskazuje, że identyfikator urządzenia jest nieprawidłowy lub że urządzenie nie było w trybie online po wywołaniu metody bezpośredniej i w connectTimeoutInSeconds przyszłości (użyj dołączonego komunikatu o błędzie, aby zrozumieć główną przyczynę);
    • 504 wskazuje limit czasu połączenia z bramą spowodowany tym, że urządzenie nie odpowiada na bezpośrednie wywołanie metody w responseTimeoutInSeconds.

  • Nagłówki zawierające identyfikator żądania, typ zawartości i kodowanie zawartości.

  • Treść JSON w następującym formacie:

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

    Zarówno status, jak i payload są dostarczane przez urządzenie i używane do odpowiedzi z własnym kodem stanu urządzenia oraz odpowiedzią metody.

Wywołanie metody dla modułów IoT Edge

Aby wywołać metodę bezpośrednią w module, użyj REST API Moduły — Wywoływanie Metody lub jego odpowiednika w jednym z zestawów SDK usługi IoT Hub.

moduleId jest przekazywany wraz z deviceId w identyfikatorze URI żądania podczas korzystania z interfejsu API REST lub jako parametr podczas korzystania z SDK usługi. Na przykład https://<iothubName>.azure-devices.net/twins/<deviceId>/modules/<moduleName>/methods?api-version=2021-04-12. Treść żądania i odpowiedź są podobne do metod bezpośrednich wywoływanych na urządzeniu.

Obsługa metody bezpośredniej na urządzeniu

Na urządzeniu IoT metody bezpośrednie można odbierać za pośrednictwem protokołu MQTT, AMQP lub za pośrednictwem jednego z tych protokołów lub WebSocket. Zestawy SDK urządzeń usługi IoT Hub ułatwiają odbieranie metod bezpośrednich na urządzeniach i reagowanie na nie bez konieczności martwienia się o szczegóły protokołu podstawowego.

MQTT

Poniższa sekcja dotyczy protokołu MQTT. Aby dowiedzieć się więcej na temat używania protokołu MQTT bezpośrednio z usługą IoT Hub, zobacz Komunikacja z centrum IoT przy użyciu protokołu MQTT.

Wywołanie metody

Urządzenia odbierają żądania metody bezpośredniej w temacie MQTT: $iothub/methods/POST/{method name}/?$rid={request id}. Jednak nie można go znać z wyprzedzeniem, ponieważ to generuje IoT Hub, dlatego subskrybuj $iothub/methods/POST/# i następnie przefiltruj dostarczone komunikaty w oparciu o nazwy metod obsługiwanych przez urządzenie. (Wygenerowany request id element służy do odpowiadania).

Treść odbierana przez urządzenie ma następujący format:

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

Żądania metod są na poziomie QoS 0.

Odpowiedź

Urządzenie wysyła odpowiedzi do $iothub/methods/res/{status}/?$rid={request id}, gdzie:

  • Właściwość status jest stanem wykonania metody dostarczonym przez urządzenie.

  • Właściwość $rid to identyfikator żądania pochodzący z wywołania metody, które zostało odebrane z usługi IoT Hub. Identyfikator żądania to wartość sformatowana szesnastkowo.

Urządzenie ustawia korpus i może mieć dowolny status.

AMQP (Protokół przesyłania danych asynchronicznych)

Poniższa sekcja dotyczy protokołu AMQP. Aby dowiedzieć się więcej na temat używania protokołu AMQP bezpośrednio z usługą IoT Hub, zobacz Komunikacja z centrum IoT przy użyciu protokołu AMQP.

Wywołanie metody

Urządzenie odbiera żądania bezpośredniej metody, tworząc link odbioru na adresie amqps://{hostname}:5671/devices/{deviceId}/methods/deviceBound.

Komunikat AMQP pojawia się na łączu odbiorczym, które reprezentuje żądanie metody. Zawiera on następujące sekcje:

  • Właściwość identyfikatora korelacji, która zawiera identyfikator żądania, który powinien zostać przekazany z powrotem z odpowiednią odpowiedzią metody.

  • Właściwość aplikacji o nazwie IoThub-methodname, która zawiera nazwę wywoływanej metody.

  • Treść komunikatu protokołu AMQP zawierająca ładunek metody jako kod JSON.

Odpowiedź

Urządzenie tworzy link wysyłający, aby zwrócić odpowiedź metody na adres amqps://{hostname}:5671/devices/{deviceId}/methods/deviceBound.

Odpowiedź metody jest zwracana w linku wysyłającym i jest ustrukturyzowana w następujący sposób:

  • Właściwość identyfikatora korelacji, która zawiera identyfikator żądania przekazany w żądaniu metody.

  • Właściwość aplikacji o nazwie IoThub-status, która zawiera stan metody dostarczonej przez użytkownika.

  • Treść komunikatu protokołu AMQP zawierająca odpowiedź metody jako kod JSON.

Następne kroki

Teraz gdy wiesz, jak używać metod bezpośrednich, możesz zainteresować się następującymi artykułami w przewodniku dewelopera usługi IoT Hub.

  • Last updated on