Opis i wywoływanie metod bezpośrednich z usługi IoT Hub

  • Artykuł

Usługa IoT Hub umożliwia wywoływanie metod bezpośrednich na urządzeniach z chmury. Metody bezpośrednie reprezentują interakcję typu „żądanie/odpowiedź” z urządzeniem podobną do wywołania HTTP w tym sensie, że powodzenie lub niepowodzenie następuje natychmiast (po osiągnięciu limitu czasu określonego przez użytkownika). Ta metoda przydaje się w scenariuszach, gdzie procedura natychmiastowego działania różni się w zależności od tego, czy urządzenie było w stanie odpowiedzieć.

Uwaga

Funkcje opisane w tym artykule są dostępne tylko w warstwie Standardowa IoT Hub. Aby uzyskać więcej informacji o warstwach podstawowa i Standardowa/Bezpłatna IoT Hub, zobacz Wybieranie odpowiedniej warstwy IoT Hub dla rozwiązania.

Każda metoda urządzenia jest przeznaczona dla jednego urządzenia. Planowanie zadań na wielu urządzeniach pokazuje, jak zapewnić sposób wywoływania metod bezpośrednich na wielu urządzeniach i planowania wywołania metody dla urządzeń odłączonych.

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

Metody bezpośrednie są zgodne ze wzorcem odpowiedzi na żądanie i są przeznaczone do komunikacji, która wymaga natychmiastowego potwierdzenia ich wyniku. Na przykład interaktywna kontrola urządzenia, na przykład włączenie wentylatora.

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 w celu poprawnego utworzenia wystąpienia. Metoda bezpośrednia jest wywoływana za pomocą identyfikatora URI dostępnego dla 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 AMQP ( IoThub-methodname właściwości i IoThub-status aplikacji).

Uwaga

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

Metody bezpośrednie są synchroniczne i kończą się powodzeniem lub niepowodzeniem po upływie limitu czasu (domyślnie: 30 sekund, ustawiana 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 chcesz zobaczyć natychmiastowe powodzenie lub niepowodzenie, aby usługa w chmurze mogła działać na wynik tak szybko, jak to możliwe. Urządzenie może zwrócić treść komunikatu w wyniku metody , ale nie jest wymagane, aby metoda to zrobiła. Nie ma żadnej gwarancji w zakresie porządkowania ani semantyki współbieżności w wywołaniach metod.

Metody bezpośrednie to tylko protokół HTTPS po stronie chmury, a protokoły MQTT, AMQP, MQTT za pośrednictwem obiektów WebSocket lub AMQP za pośrednictwem obiektów WebSocket po stronie urządzenia.

Ładunek dla żądań i odpowiedzi metod jest dokumentem JSON do 128 KB.

Wywoływanie metody bezpośredniej z aplikacji zaplecza

Aby wywołać metodę bezpośrednią z aplikacji zaplecza, użyj interfejsu API REST metody wywoływania urządzenia lub jej odpowiednika w jednym z zestawów SDK usługi IoT Hub.

Wywołanie metody

Wywołania metod bezpośrednich 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.

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

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

Wartość podana w responseTimeoutInSeconds żądaniu to czas, przez który usługa IoT Hub musi czekać na ukończenie wykonywania metody bezpośredniej na urządzeniu. Ustaw ten limit czasu na wartość co najmniej tak długo, jak oczekiwany czas wykonywania metody bezpośredniej przez urządzenie. Jeśli limit czasu nie zostanie podany, zostanie użyta wartość domyślna 30 sekund. Wartości minimalne i maksymalne dla responseTimeoutInSeconds wartości to odpowiednio 5 i 300 sekund.

Wartość podana w connectTimeoutInSeconds żądaniu to czas wywołania metody bezpośredniej, która IoT Hub usługa musi czekać, aż odłączone urządzenie będzie w trybie online. Wartość domyślna to 0, co oznacza, że urządzenia muszą już być w trybie online po wywołaniu metody bezpośredniej. Wartość maksymalna wynosi connectTimeoutInSeconds 300 sekund.

Przykład

W tym przykładzie można bezpiecznie zainicjować żądanie wywołania metody bezpośredniej na urządzeniu IoT zarejestrowanym w centrum Azure IoT.

Aby rozpocząć, użyj rozszerzenia Microsoft Azure IoT dla interfejsu wiersza polecenia platformy Azure , aby utworzyć element SharedAccessSignature.

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

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

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 powyższym przykładzie pokazano wywołanie metody bezpośredniej na urządzeniu. Jeśli chcesz wywołać metodę bezpośrednią w module IoT Edge, musisz zmodyfikować żądanie adresu URL, jak pokazano poniżej:

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

Reakcja

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 później connectTimeoutInSeconds (użyj dołączonego komunikatu o błędzie, aby zrozumieć główną przyczynę);
    • 504 wskazuje przekroczenie limitu czasu bramy spowodowane przez urządzenie, które nie odpowiada na wywołanie metody bezpośredniej w ramach 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 urządzenie, jak i payload są dostarczane przez urządzenie i używane do odpowiadania za pomocą własnego kodu stanu urządzenia i odpowiedzi metody.

Wywołanie metody dla modułów IoT Edge

Wywoływanie metod bezpośrednich w module jest obsługiwane przez interfejs API REST metody invoke modułu lub jego odpowiednik w jednym z zestawów SDK usługi IoT Hub.

Element moduleId jest przekazywany wraz z wartością deviceId w identyfikatorze URI żądania w przypadku korzystania z interfejsu API REST lub jako parametru podczas korzystania z zestawu 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 jednego z tych protokołów za pośrednictwem obiektów WebSocket. Zestawy SDK urządzeń 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 IoT Hub, zobacz Obsługa protokołów MQTT.

Wywołanie metody

Urządzenia odbierają żądania metody bezpośredniej w temacie MQTT: $iothub/methods/POST/{method name}/?$rid={request id}. Jednak element request id jest generowany przez IoT Hub i nie może być znany z wyprzedzeniem, dlatego zasubskrybuj i przefiltruj $iothub/methods/POST/# dostarczone komunikaty na podstawie nazw metod obsługiwanych przez urządzenie. (Użyjesz metody request id , aby odpowiedzieć).

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

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

Żądania metod to QoS 0.

Reakcja

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

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

  • Właściwość $rid jest identyfikatorem żądania z wywołania metody otrzymanego z IoT Hub. Identyfikator żądania to wartość szesnastkowa sformatowana.

Treść jest ustawiana przez urządzenie i może mieć dowolny stan.

AMQP

Poniższa sekcja dotyczy protokołu AMQP. Aby dowiedzieć się więcej na temat używania protokołu AMQP bezpośrednio z IoT Hub, zobacz Obsługa protokołu AMQP.

Wywołanie metody

Urządzenie odbiera żądania metody bezpośredniej przez utworzenie linku odbioru na adresie amqps://{hostname}:5671/devices/{deviceId}/methods/deviceBound.

Komunikat PROTOKOŁU AMQP jest odbierany za pomocą linku odbierania, który reprezentuje żądanie metody. Ten temat zawiera 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 w formacie JSON.

Reakcja

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 zawierająca identyfikator żądania przekazany w komunikacie żądania metody.

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

  • Treść komunikatu amQP zawierająca odpowiedź metody jako kod JSON.

Dodatkowy materiał referencyjny

Inne tematy referencyjne w przewodniku dla deweloperów IoT Hub obejmują:

Następne kroki

Teraz wiesz już, jak używać metod bezpośrednich, możesz zainteresować się następującym IoT Hub przewodniku dla deweloperów:

Jeśli chcesz wypróbować niektóre pojęcia opisane w tym artykule, możesz zainteresować się następującym samouczkiem dotyczącym IoT Hub: