Udostępnij za pośrednictwem

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

  • Artykuł

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 usługi IoT Hub dla rozwiązania.

Każda metoda urządzenia jest przeznaczona dla 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ą należy wywołać 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 aplikacji i IoThub-status ).

Uwaga

Podczas wywoływania metody bezpośredniej na urządzeniu nazwy właściwości i wartości mogą zawierać tylko znaki alfanumeryczne z możliwością drukowania US-ASCII, z wyjątkiem dowolnego z 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; można ustawić tabelę z zakresu 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ć natychmiastowy sukces lub niepowodzenie, aby usługa w chmurze mogła działać w wyniku tak szybko, jak to możliwe. Urządzenie może zwrócić treść komunikatu w wyniku metody, ale nie jest wymagane. Nie ma żadnej gwarancji na porządkowanie ani semantyka współbieżności wywołań metod.

Metody bezpośrednie są tylko https po stronie chmury i MQTT, AMQP, MQTT za pośrednictwem obiektów WebSocket lub AMQP za pośrednictwem obiektów WebSocket po stronie urządzenia.

Ładunek żądań i odpowiedzi metody 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 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.

  • 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 oczekiwania usługi IoT Hub na ukończenie wykonania 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 to responseTimeoutInSeconds odpowiednio 5 i 300 sekund.

Wartość podana w connectTimeoutInSeconds żądaniu to czas wywołania metody bezpośredniej, którą usługa IoT Hub musi czekać na odłączone urządzenie do trybu 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 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 , deviceIdmethodName ipayload, 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 usługi IoT Edge, zmodyfikuj żądanie adresu URL w taki sposób, jak /modules/<moduleName> pokazano poniżej:

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

Response

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 następnie connectTimeoutInSeconds (użyj dołączonego komunikatu o błędzie, aby zrozumieć główną przyczynę);
    • 504 wskazuje limit czasu bramy spowodowany tym, że urządzenie nie odpowiada na wywołanie metody bezpośredniej w programie 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 usługi 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 deviceId identyfikatorem w identyfikatorze URI żądania podczas 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ń 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 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 usługę IoT Hub i nie może być znany z wyprzedzeniem, dlatego zasubskrybuj, a następnie przefiltruj $iothub/methods/POST/# dostarczone komunikaty na podstawie nazw metod obsługiwanych przez urządzenie. (Użyjesz polecenia request id , aby odpowiedzieć).

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

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

Żądania metod to QoS 0.

Response

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 odebranego z usługi IoT Hub. Identyfikator żądania to wartość szesnastkowa sformatowana.

Treść jest ustawiana przez urządzenie i może być dowolnym stanem.

AMQP

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 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 pojawia się na linku odbioru, 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 jako kod JSON.

Response

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 protokołu AMQP zawierająca odpowiedź metody jako kod JSON.

Następne kroki

Teraz wiesz już, jak używać metod bezpośrednich, możesz zainteresować się następującym artykułem po przewodniku dewelopera usługi IoT Hub: