Udostępnij za pośrednictwem

Obsługa protokołu MQTT 5 usługi IoT Hub (przestarzała)

  • Artykuł

Wersja: 2.0 api-version: 2020-10-01-preview

Ten dokument definiuje interfejs API płaszczyzny danych usługi IoT Hub za pośrednictwem protokołu MQTT w wersji 5.0. Zobacz Dokumentację interfejsu API, aby uzyskać pełne definicje w tym interfejsie API.

Uwaga

Obsługa protokołu MQTT 5 w usłudze IoT Hub jest przestarzała, a usługa IoT Hub ma ograniczoną obsługę funkcji MQTT. Jeśli twoje rozwiązanie wymaga obsługi protokołu MQTT w wersji 3.1.1 lub 5, zalecamy obsługę protokołu MQTT w usłudze Azure Event Grid. Aby uzyskać więcej informacji, zobacz Porównanie obsługi MQTT w usłudze IoT Hub i usłudze Event Grid.

Wymagania wstępne

  • Utwórz zupełnie nowe centrum IoT z włączonym trybem podglądu. Protokół MQTT 5 jest dostępny tylko w trybie podglądu i nie można przełączyć istniejącego centrum IoT do trybu podglądu. Aby uzyskać więcej informacji, zobacz Włączanie trybu podglądu
  • Wcześniejsza wiedza na temat specyfikacji MQTT 5.

Poziom pomocy technicznej i ograniczenia

Obsługa usługi IoT Hub dla protokołu MQTT 5 jest dostępna w wersji zapoznawczej i jest ograniczona w następujący sposób (komunikacja z klientem za pośrednictwem CONNACK właściwości, chyba że jawnie określono inaczej):

  • Nie są jeszcze obsługiwane oficjalne zestawy SDK urządzeń Azure IoT.
  • Identyfikatory subskrypcji nie są obsługiwane.
  • Subskrypcje udostępnione nie są obsługiwane.
  • RETAIN nie jest obsługiwany.
  • Parametr Maximum QoS ma wartość 1.
  • Maximum Packet Size is 256 KiB (z zastrzeżeniem dalszych ograniczeń na operację).
  • Przypisane identyfikatory klientów nie są obsługiwane.
  • Keep Alive jest ograniczona do 19 min (maksymalne opóźnienie dla sprawdzania aktualności – 28.5 min).
  • Parametr Topic Alias Maximum ma wartość 10.
  • Response Information nie jest obsługiwana; CONNACK nie zwraca Response Information właściwości, nawet jeśli CONNECT zawiera Request Response Information właściwość.
  • Receive Maximum (maksymalna dozwolona liczba dozwolonych nieprzeznaczonych PUBLISH pakietów (w kierunku klient-serwer) z QoS: 1) to 16.
  • Pojedynczy klient nie może mieć więcej niż 50 subskrypcji. Jeśli klient osiągnie limit subskrypcji, SUBACK zwraca 0x97 kod przyczyny (przekroczono limit przydziału) dla subskrypcji.

Cykl życia połączenia

Connection

Aby połączyć klienta z usługą IoT Hub przy użyciu tego interfejsu API, ustanów połączenie na specyfikację MQTT 5. Klient musi wysłać CONNECT pakiet w ciągu 30 sekund po pomyślnym uzgadnianiu protokołu TLS lub serwer zamyka połączenie. Oto przykład CONNECT pakietu:

-> CONNECT
    Protocol_Version: 5
    Clean_Start: 0
    Client_Id: D1
    Authentication_Method: SAS
    Authentication_Data: {SAS bytes}
    api-version: 2020-10-10
    host: abc.azure-devices.net
    sas-at: 1600987795320
    sas-expiry: 1600987195320
    client-agent: artisan;Linux
  • Authentication Method Właściwość jest wymagana i określa, która metoda uwierzytelniania jest używana. Aby uzyskać więcej informacji na temat metody uwierzytelniania, zobacz Authentication (Uwierzytelnianie).
  • Authentication Data Obsługa Authentication Methodwłaściwości zależy od . Jeśli Authentication Method jest ustawiona wartość SAS, Authentication Data wymagana jest wartość i musi zawierać prawidłowy podpis. Aby uzyskać więcej informacji na temat danych uwierzytelniania, zobacz Uwierzytelnianie.
  • api-version Właściwość jest wymagana i musi być ustawiona na wartość wersji interfejsu API podaną w nagłówku tej specyfikacji, aby ta specyfikacja miała zastosowanie.
  • host właściwość definiuje nazwę hosta dzierżawy. Jest to wymagane, chyba że rozszerzenie SNI zostało przedstawione w rekordzie Hello klienta podczas uzgadniania protokołu TLS
  • sas-at definiuje czas połączenia.
  • sas-expiry definiuje czas wygaśnięcia dla podanej sygnatury dostępu współdzielonego.
  • client-agent opcjonalnie komunikuje informacje o kliencie tworzącym połączenie.

Uwaga

Authentication Method i inne właściwości w całej specyfikacji z nazwami wielkich liter są właściwościami pierwszej klasy w MQTT 5 - są one opisane w szczegółach w specyfikacji MQTT 5. api-version i inne właściwości w przypadku kreski to właściwości użytkownika specyficzne dla interfejsu API usługi IoT Hub.

Usługa IoT Hub odpowiada pakietem CONNACK po zakończeniu uwierzytelniania i pobieraniu danych w celu obsługi połączenia. Jeśli połączenie zostało nawiązane pomyślnie, CONNACK wygląda następująco:

<- CONNACK
    Session_Present: 1
    Reason_Code: 0x00
    Session_Expiry_Interval: 0xFFFFFFFF # included only if CONNECT specified value less than 0xFFFFFFFF and more than 0x00
    Receive_Maximum: 16
    Maximum_QoS: 1
    Retain_Available: 0
    Maximum_Packet_Size: 262144
    Topic_Alias_Maximum: 10
    Subscription_Identifiers_Available: 0
    Shared_Subscriptions_Available: 0
    Server_Keep_Alive: 1140 # included only if client did not specify Keep Alive or if it specified a bigger value

Te CONNACK właściwości pakietu są zgodne ze specyfikacją MQTT 5. Odzwierciedlają one możliwości usługi IoT Hub.

Uwierzytelnianie

Właściwość Authentication Method na CONNECT kliencie definiuje rodzaj uwierzytelniania używanego dla tego połączenia:

  • SAS— Sygnatura Authentication Data dostępu współdzielonego jest udostępniana we CONNECTwłaściwości ,
  • X509 — klient korzysta z uwierzytelniania certyfikatu klienta.

Uwierzytelnianie kończy się niepowodzeniem, jeśli metoda uwierzytelniania nie jest zgodna ze skonfigurowaną metodą klienta w usłudze IoT Hub.

Uwaga

Ten interfejs API wymaga Authentication Method ustawienia właściwości w CONNECT pakiecie. Jeśli Authentication Method właściwość nie jest podana, połączenie kończy się niepowodzeniem z odpowiedzią Bad Request .

Uwierzytelnianie nazwy użytkownika/hasła używane w poprzednich wersjach interfejsu API nie jest obsługiwane.

SAS

W przypadku uwierzytelniania opartego na sygnaturze dostępu współdzielonego klient musi podać podpis kontekstu połączenia. Podpis potwierdza autentyczność połączenia MQTT. Podpis musi być oparty na jednym z dwóch kluczy uwierzytelniania w konfiguracji klienta w usłudze IoT Hub. Może też być oparta na jednym z dwóch kluczy dostępu współdzielonego zasad dostępu współdzielonego.

Ciąg do podpisania musi być sformułowany w następujący sposób:

{host name}\n
{Client Id}\n
{sas-policy}\n
{sas-at}\n
{sas-expiry}\n
  • host name pochodzi z rozszerzenia SNI (prezentowanego przez klienta w rekordzie Hello klienta podczas uzgadniania protokołu TLS) lub host właściwości użytkownika w CONNECT pakiecie.
  • Client Id to identyfikator klienta w CONNECT pakiecie.
  • sas-policy — jeśli jest obecny, definiuje zasady dostępu usługi IoT Hub używane do uwierzytelniania. Jest on zakodowany jako właściwość użytkownika w CONNECT pakiecie. Opcjonalnie: pominięcie oznacza, że zamiast tego są używane ustawienia uwierzytelniania w rejestrze urządzeń.
  • sas-at - jeśli jest obecny, określa czas połączenia - bieżący czas. Jest on zakodowany jako właściwość time użytkownika typu w CONNECT pakiecie.
  • sas-expiry definiuje czas wygaśnięcia uwierzytelniania. timeJest to właściwość -typed użytkownika w CONNECT pakiecie. Ta właściwość jest wymagana.

W przypadku parametrów opcjonalnych, jeśli pominięto, pusty ciąg MUSI być używany zamiast ciągu do podpisania.

HMAC-SHA256 służy do wyznaczania wartości skrótu na podstawie jednego z kluczy symetrycznych urządzenia. Wartość skrótu Authentication Data jest następnie ustawiana jako wartość właściwości.

X509

Jeśli Authentication Method właściwość jest ustawiona na X509, usługa IoT Hub uwierzytelnia połączenie na podstawie podanego certyfikatu klienta.

Ponowne uwierzytelnianie

Jeśli jest używane uwierzytelnianie oparte na sygnaturze dostępu współdzielonego, zalecamy używanie tokenów uwierzytelniania krótkotrwałego. Aby zachować uwierzytelnienie połączenia i zapobiec rozłączeniu z powodu wygaśnięcia, klient musi ponownie uwierzytelnić się, wysyłając AUTH pakiet Reason Code: 0x19 za pomocą polecenia (ponowne uwierzytelnianie):

-> AUTH
    Reason_Code: 0x19
    Authentication_Method: SAS
    Authentication_Data: {SAS bytes}
    sas-at: {current time}
    sas-expiry: {SAS expiry time}

Reguły:

  • Authentication Method musi być taka sama jak ta, która jest używana do uwierzytelniania początkowego
  • Jeśli połączenie zostało pierwotnie uwierzytelnione przy użyciu sygnatury dostępu współdzielonego na podstawie zasad dostępu współdzielonego, podpis używany w ponownym uwierzytelnieniu musi być oparty na tych samych zasadach.

Jeśli ponowne uwierzytelnienie powiedzie się, usługa IoT Hub wysyła AUTH pakiet ( Reason Code: 0x00 powodzenie). W przeciwnym razie usługa IoT Hub wysyła DISCONNECT pakiet ( Reason Code: 0x87 nieautoryzowany) i zamyka połączenie.

Odłączenie

Serwer może odłączyć klienta z kilku powodów, w tym:

  • klient błędnie zachowuje się w sposób, który jest niemożliwy do reagowania z negatywnym potwierdzeniem (lub odpowiedzią) bezpośrednio,
  • Serwer nie może zachować stanu aktualnego połączenia,
  • inny klient łączy się z tą samą tożsamością.

Serwer może rozłączyć się z dowolnym kodem przyczyny zdefiniowanym w specyfikacji MQTT 5.0. Istotne wzmianki:

  • 135 (Nieautoryzowane) w przypadku niepowodzenia ponownego uwierzytelniania bieżący token SAS lub zmiany poświadczeń urządzenia.
  • 142 (Sesja przejęta) po otwarciu nowego połączenia z tą samą tożsamością klienta.
  • 159 (Przekroczono szybkość połączenia), gdy szybkość połączenia dla centrum IoT przekracza limit.
  • 131 (Błąd specyficzny dla implementacji) jest używany dla wszelkich błędów niestandardowych zdefiniowanych w tym interfejsie API. status właściwości i reason służą do przekazywania dalszych szczegółów dotyczących przyczyny rozłączenia (zobacz Odpowiedź , aby uzyskać szczegółowe informacje).

Operacje

Wszystkie funkcje tego interfejsu API są wyrażane jako operacje. Oto przykład operacji Wysyłania telemetrii:

-> PUBLISH
    QoS: 1
    Packet_Id: 3
    Topic: $iothub/telemetry
    Payload: Hello

<- PUBACK
    Packet_Id: 3
    Reason_Code: 0

Aby uzyskać pełną specyfikację operacji w tym interfejsie API, zobacz Dokumentacja interfejsu API usługi IoT Hub MQTT 5.

Uwaga

Wszystkie przykłady w tej specyfikacji są wyświetlane z perspektywy klienta. Znak -> oznacza, że klient wysyła pakiet, <- odbierając.

Tematy wiadomości i subskrypcje

Tematy używane w komunikatach operacji w tym interfejsie API zaczynają się od $iothub/. Semantyka brokera MQTT nie ma zastosowania do tych operacji (zobacz "Tematy rozpoczynające się od $", aby uzyskać szczegółowe informacje). Tematy rozpoczynające się od $iothub/ tych, które nie są zdefiniowane w tym interfejsie API, nie są obsługiwane:

  • Wysyłanie komunikatów do niezdefiniowanego tematu powoduje Not Found odpowiedź (zobacz Odpowiedź , aby uzyskać szczegółowe informacje),
  • Subskrybowanie niezdefiniowanego tematu powoduje wyświetlenie SUBACK Reason Code: 0x8F elementu (Filtr tematu jest nieprawidłowy).

W nazwach tematów i nazwach właściwości uwzględniana jest wielkość liter i musi być dokładnie zgodna. Na przykład $iothub/telemetry/ nie jest obsługiwana, gdy $iothub/telemetry jest.

Uwaga

Symbole wieloznaczne w subskrypcjach w obszarze $iothub/.. nie są obsługiwane. Oznacza to, że klient nie może subskrybować $iothub/+ ani $iothub/#. Próba wykonania tej czynności powoduje użycie SUBACK polecenia Reason Code: 0xA2 (subskrypcje wieloznaczne nie są obsługiwane). Obsługiwane są tylko symbole wieloznaczne pojedynczego segmentu (+) zamiast parametrów ścieżki w nazwie tematu dla operacji, które je mają.

Typy interakcji

Wszystkie operacje w tym interfejsie API są oparte na jednym z dwóch typów interakcji:

  • Wiadomość z opcjonalnym potwierdzeniem (MessageAck)
  • Request-Response (ReqRep)

Operacje różnią się również w zależności od kierunku początkowego komunikatu w zamian):

  • Klient-serwer (c2s)
  • Serwer-klient (s2c)

Na przykład funkcja Wyślij telemetrię to operacja typu "Komunikat z potwierdzeniem" typu "Klient-serwer", a metoda Obsługi bezpośredniej to operacja serwer-klient typu Request-Response.

Interakcje z potwierdzeniem wiadomości

Komunikat z opcjonalną interakcją potwierdzenia (MessageAck) jest wyrażany jako wymiana PUBLISH pakietów i PUBACK w MQTT. Potwierdzenie jest opcjonalne, a nadawca może nie żądać go, wysyłając PUBLISH pakiet za pomocą polecenia QoS: 0.

Uwaga

Jeśli właściwości w PUBACK pakiecie muszą zostać obcięte z powodu zadeklarowania Maximum Packet Size przez klienta, usługa IoT Hub zachowa tyle właściwości użytkownika, ile może mieścić się w danym limicie. Właściwości użytkownika wymienione na liście mają większą szansę wysłania niż te wymienione później; Reason String właściwość ma najmniejszy priorytet.

Przykład prostej interakcji z aplikacją MessageAck

Komunikat:

PUBLISH
    QoS: 1
    Packet_Id: 34
    Topic: $iothub/{request.path}
    Payload: <any>

Potwierdzenie (powodzenie):

PUBACK
    Packet_Id: 34
    Reason_Code: 0

Interakcje z odpowiedziami na żądanie

W interakcjach request-response (ReqRep) żądania i odpowiedzi tłumaczą się na PUBLISH pakiety za pomocą QoS: 0polecenia .

Correlation Data Właściwość musi być ustawiona zarówno w obu, jak i jest używana do dopasowania pakietu odpowiedzi do żądania pakietu.

Ten interfejs API używa pojedynczego tematu $iothub/responses odpowiedzi dla wszystkich operacji ReqRep. Subskrybowanie/anulowanie subskrypcji z tego tematu dla operacji klient-serwer nie jest wymagane — serwer zakłada, że wszyscy klienci mają być subskrybowani.

Przykład prostej interakcji reqRep

Żądanie:

PUBLISH
    QoS: 0
    Topic: $iothub/{request.path}
    Correlation_Data: 0x01 0xFA
    Payload: ...

Odpowiedź (powodzenie):

PUBLISH
    QoS: 0
    Topic: $iothub/responses
    Correlation_Data: 0x01 0xFA
    Payload: ...

Interakcje reqRep nie obsługują PUBLISH pakietów jako komunikatów QoS: 1 żądania lub odpowiedzi. Wysyłanie żądań PUBLISH powoduje Bad Request odpowiedź.

Maksymalna długość obsługiwana we Correlation Data właściwości to 16 bajtów. Jeśli Correlation Data właściwość pakietu PUBLISH jest ustawiona na wartość dłuższą niż 16 bajtów, usługa IoT Hub wysyła DISCONNECT Bad Request wynik i zamyka połączenie. To zachowanie dotyczy tylko pakietów wymienianych w tym interfejsie API.

Uwaga

Dane korelacji to dowolna sekwencja bajtów, np. nie ma gwarancji, że ciąg UTF-8.

ReqRep użyj wstępnie zdefiniowanych tematów na potrzeby odpowiedzi; Właściwość Temat odpowiedzi w pakiecie Żądania PUBLISH (jeśli jest ustawiona przez nadawcę) jest ignorowana.

Usługa IoT Hub automatycznie subskrybuje klienta do tematów odpowiedzi dla wszystkich operacji ReqRep typu klient-serwer. Nawet jeśli klient jawnie anuluje subskrypcję z tematu odpowiedzi, usługa IoT Hub automatycznie przywraca subskrypcję. W przypadku interakcji reqRep między serwerem a klientem należy nadal zasubskrybować urządzenie.

Właściwości komunikatu

Właściwości operacji — zdefiniowane przez system lub użytkownika — są wyrażane jako właściwości pakietu w MQTT 5.

W nazwach właściwości użytkownika jest rozróżniana wielkość liter i musi być wpisana dokładnie zgodnie z definicją. Na przykład Trace-ID nie jest obsługiwana, gdy trace-id jest.

Żądania z właściwościami użytkownika poza specyfikacją i bez prefiksu @ powodują błąd.

Właściwości systemu są kodowane jako właściwości pierwszej klasy (na przykład Content Type) lub właściwości użytkownika. Specyfikacja zawiera wyczerpującą listę obsługiwanych właściwości systemu. Wszystkie właściwości pierwszej klasy są ignorowane, chyba że obsługa ich jest jawnie określona w specyfikacji.

Jeśli właściwości zdefiniowane przez użytkownika są dozwolone, ich nazwy muszą być zgodne z formatem @{property name}. Właściwości zdefiniowane przez użytkownika obsługują tylko prawidłowe wartości ciągów UTF-8. na przykład MyProperty1 właściwość o wartości 15 musi być zakodowana jako właściwość User o nazwie @MyProperty i wartości 15.

Jeśli usługa IoT Hub nie rozpoznaje właściwości użytkownika, jest traktowana jako błąd, a usługa IoT Hub odpowiada za pomocą PUBACK polecenia Reason Code: 0x83 (błąd specyficzny dla implementacji) i status: 0100 (nieprawidłowe żądanie). Jeśli potwierdzenie nie zostało żądane (QoS: 0), DISCONNECT pakiet z tym samym błędem jest wysyłany z powrotem i połączenie zostanie przerwane.

Ten interfejs API definiuje następujące typy danych oprócz string:

  • time: liczba milisekund od .1970-01-01T00:00:00.000Z na przykład dla 2020-09-24T22:39:55.320Zelementu 1600987195320 ,
  • u32: niepodpisany 32-bitowy numer całkowity,
  • u64: niepodpisany 64-bitowy numer całkowity,
  • i32: podpisana liczba całkowita 32-bitowa.

Response

Interakcje mogą skutkować różnymi wynikami: Success, Bad Request, Not Foundi innymi. Wyniki różnią się od siebie właściwością status użytkownika. Reason Code w PUBACK pakietach (w przypadku interakcji messageAck) pasuje status w znaczeniu tam, gdzie to możliwe.

Uwaga

Jeśli klient określa Request Problem Information: 0 w pakiecie CONNECT, żadne właściwości użytkownika nie będą wysyłane na PUBACK pakiety zgodne ze specyfikacją MQTT 5, w tym status właściwość. W takim przypadku klient nadal może polegać na Reason Code ustaleniu, czy potwierdzenie jest pozytywne, czy negatywne.

Każda interakcja ma wartość domyślną (lub powodzenie). Ma Reason Code 0 właściwość i status "not set". W przeciwnym razie:

  • W przypadku interakcji PUBACK messageAck pobiera inne Reason Code niż 0x0 (powodzenie). status właściwość może być obecna, aby dokładniej wyjaśnić wynik.
  • W przypadku interakcji reqRep odpowiedź PUBLISH pobiera status zestaw właściwości.
  • Ponieważ nie ma możliwości bezpośredniego reagowania na interakcje QoS: 0 messageAck, DISCONNECT pakiet jest wysyłany zamiast informacji o odpowiedzi, a następnie rozłączanie.

Przykłady:

Nieprawidłowe żądanie (MessageAck):

PUBACK
    Reason_Code: 131
    status: 0100
    reason: Unknown property `test`

Brak autoryzacji (MessageAck):

PUBACK
    Reason_Code: 135
    status: 0101

Brak autoryzacji (ReqRep):

PUBLISH
    QoS: 0
    Topic: $iothub/responses
    Correlation_Data: ...
    status: 0101

W razie potrzeby usługa IoT Hub ustawia następujące właściwości użytkownika:

  • status — rozszerzony kod usługi IoT Hub dla stanu operacji. Ten kod może służyć do rozróżniania wyników.
  • trace-id — identyfikator śledzenia operacji; Usługa IoT Hub może zachować więcej danych diagnostycznych dotyczących operacji, która może być używana do badania wewnętrznego.
  • reason - czytelny dla człowieka komunikat zawierający dalsze informacje o tym, dlaczego operacja zakończyła się w stanie wskazywanym przez status właściwość.

Uwaga

Jeśli klient ustawia Maximum Packet Size właściwość w pakiecie CONNECT z bardzo małą wartością, nie wszystkie właściwości użytkownika mogą być dopasowane i nie będą wyświetlane w pakiecie.

reason jest przeznaczony tylko dla osób i nie powinien być używany w logice klienta. Ten interfejs API umożliwia zmianę komunikatów w dowolnym momencie bez ostrzeżenia ani zmiany wersji.

Jeśli klient wysyła RequestProblemInformation: 0 pakiet CONNECT, właściwości użytkownika nie będą uwzględniane w potwierdzeniach na specyfikację MQTT 5.

Kod stanu

status właściwość zawiera kod stanu operacji. Jest zoptymalizowany pod kątem wydajności odczytu maszynowego. Składa się z dwu bajtów bez znaku liczby całkowitej zakodowanej jako szesnastkowy w ciągu, na przykład 0501. Struktura kodu (mapa bitowa):

7 6 5 4 3 2 1 0 | 7 6 5 4 3 2 1 0
0 0 0 0 0 R T T | C C C C C C C C

Pierwszy bajt jest używany dla flag:

  • bity 0 i 1 wskazują typ wyników:
    • 00 -sukces
    • 01 — błąd klienta
    • 10 — błąd serwera
  • bit 2: 1 wskazuje, że błąd można ponowić próbę
  • Bity od 3 do 7 są zarezerwowane i muszą być ustawione na 0

Drugi bajt zawiera rzeczywisty odrębny kod odpowiedzi. Kody błędów z różnymi flagami mogą mieć tę samą drugą wartość bajtu. Na przykład mogą istnieć 0001kody błędów , , 01010201o 0301 odrębnym znaczeniu.

Na przykład Too Many Requests jest klientem, można ponowić próbę błędu z własnym kodem 1. Jego wartość to 0000 0101 0000 0001 lub 0x0501.

Klienci mogą używać bitów typu, aby określić, czy operacja zakończyła się pomyślnie. Klienci mogą również użyć bitu z możliwością ponawiania prób, aby zdecydować, czy warto ponowić operację.

Zalecenia

Zarządzanie sesją

CONNACK pakiet przenosi Session Present właściwość, aby wskazać, czy serwer przywrócony wcześniej utworzona sesja. Użyj tej właściwości, aby ustalić, czy subskrybować tematy, czy pominąć subskrybowanie, ponieważ subskrypcja została wykonana wcześniej.

Aby polegać na Session Presentprogramie , klient musi śledzić subskrypcje, które zostały wykonane (tj. wysłany pakiet i odebrany SUBACK SUBSCRIBE z kodem przyczyny pomyślnej) lub upewnić się, że subskrybuje wszystkie tematy w ramach jednej SUBSCRIBE/SUBACK wymiany. W przeciwnym razie, jeśli klient wysyła dwa SUBSCRIBE pakiety, a serwer przetwarza tylko jeden z nich pomyślnie, serwer komunikuje się Session Present: 1 , CONNACK gdy tylko część subskrypcji klienta została zaakceptowana.

Aby zapobiec sytuacji, w której starsza wersja klienta nie zasubskrybuje wszystkich tematów, lepiej jest subskrybować bezwarunkowo podczas zmiany zachowania klienta (na przykład w ramach aktualizacji oprogramowania układowego). Ponadto, aby upewnić się, że nie ma przestarzałych subskrypcji (biorąc pod uwagę maksymalną dozwoloną liczbę subskrypcji), jawnie anuluj subskrypcję, które nie są już używane.

Dzielenie na partie

Brak specjalnego formatu wysyłania partii komunikatów. Aby zmniejszyć nakład pracy związany z operacjami intensywnie korzystającymi z zasobów w protokole TLS i sieci, pakiety pakietów (PUBLISH, PUBACK, SUBSCRIBEi tak nie) przed przekazaniem ich do bazowego stosu TLS/TCP. Ponadto klient może ułatwić alias tematu w "partii":

  • Umieść pełną nazwę tematu w pierwszym PUBLISH pakiecie dla połączenia i skojarz alias tematu z nim,
  • Umieść następujące pakiety dla tego samego tematu z pustą nazwą tematu i właściwością aliasu tematu.

Migracja

W tej sekcji wymieniono zmiany w interfejsie API w porównaniu z poprzednią obsługą protokołu MQTT.

  • Protokół transportowy to MQTT 5. Wcześniej — MQTT 3.1.1.
  • Informacje kontekstowe dotyczące uwierzytelniania SAS znajdują się bezpośrednio w CONNECT pakiecie zamiast kodować wraz z podpisem.
  • Metoda uwierzytelniania służy do wskazywania używanej metody uwierzytelniania.
  • Sygnatura dostępu współdzielonego jest umieszczana we właściwości Dane uwierzytelniania. Wcześniej użyto pola Hasło.
  • Tematy dotyczące operacji są różne:
    • Telemetria: $iothub/telemetry zamiast devices/{Client Id}/messages/events,
    • Polecenia: $iothub/commands zamiast devices/{Client Id}/messages/devicebound,
    • Zgłoszono bliźniacze reprezentacje poprawki$iothub/twin/PATCH/properties/reported: $iothub/twin/patch/reported zamiast ,
    • Powiadamianie o zmianie żądanego stanu bliźniaczej $iothub/twin/PATCH/properties/desiredreprezentacji: $iothub/twin/patch/desired zamiast .
  • Subskrypcja tematu odpowiedzi operacji żądań serwera klienta nie jest wymagana.
  • Właściwości użytkownika są używane zamiast właściwości kodowania w segmencie nazwy tematu.
  • Nazwy właściwości są pisane w konwencji nazewnictwa "dash-case" zamiast skrótów ze specjalnym prefiksem. Właściwości zdefiniowane przez użytkownika wymagają teraz prefiksu. Na przykład $.mid wartość to , a myProperty1 teraz message-idstaje się .@myProperty1
  • Właściwość Dane korelacji służy do korelowania komunikatów żądań i odpowiedzi dla operacji żądań-odpowiedzi zamiast właściwości zakodowanych $rid w temacie.
  • iothub-connection-auth-method właściwość nie jest już oznaczana zdarzeniami telemetrii.
  • Polecenia C2D nie są czyszczone w przypadku braku subskrypcji z urządzenia. Pozostają one w kolejce do momentu zasubskrybowaniu urządzenia lub wygaśnięciu.

Przykłady

Wysyłanie danych telemetrycznych

Komunikat:

-> PUBLISH
    QoS: 1
    Packet_Id: 31
    Topic: $iothub/telemetry
    @myProperty1: My String Value # optional
    creation-time: 1600987195320 # optional
    @ No_Rules-ForUser-PROPERTIES: Any UTF-8 string value # optional
    Payload: <data>

Potwierdzenia:

<- PUBACK
    Packet_Id: 31
    Reason_Code: 0

Potwierdzenie alternatywne (ograniczone):

<- PUBACK
    Packet_Id: 31
    Reason_Code: 151
    status: 0501

Wysyłanie stanu bliźniaczej reprezentacji bliźniaczej

Żądanie:

-> PUBLISH
    QoS: 0
    Topic: $iothub/twin/get
    Correlation_Data: 0x01 0xFA
    Payload: <empty>

Odpowiedź (powodzenie):

<- PUBLISH
    QoS: 0
    Topic: $iothub/responses
    Correlation_Data: 0x01 0xFA
    Payload: <twin/desired state>

Odpowiedź (niedozwolona):

<- PUBLISH
    QoS: 0
    Topic: $iothub/responses
    Correlation_Data: 0x01 0xFA
    status: 0102
    reason: Operation not allowed for `B2` SKU
    Payload: <empty>

Obsługa wywołania metody bezpośredniej

Żądanie:

<- PUBLISH
    QoS: 0
    Topic: $iothub/methods/abc
    Correlation_Data: 0x0A 0x10
    Payload: <data>

Odpowiedź (powodzenie):

-> PUBLISH
    QoS: 0
    Topic: $iothub/responses
    Correlation_Data: 0x0A 0x10
    response-code: 200 # user defined response code
    Payload: <data>

Uwaga

status nie jest ustawiona — jest to odpowiedź na powodzenie.

Odpowiedź na urządzenie jest niedostępna:

-> PUBLISH
    QoS: 0
    Topic: $iothub/responses
    Correlation_Data: 0x0A 0x10
    status: 0603

Błąd podczas korzystania z usługi QoS 0, część 1

Żądanie:

-> PUBLISH
    QoS: 0
    Topic: $iothub/twin/gett # misspelled topic name - server won't recognize it as Request-Response interaction
    Correlation_Data: 0x0A 0x10
    Payload: <data>

Reakcja:

<- DISCONNECT
    Reason_Code: 144
    reason: "Unsupported topic: `$iothub/twin/gett`"

Błąd podczas korzystania z usługi QoS 0, część 2

Żądanie:

-> PUBLISH # missing Correlation Data
    QoS: 0
    Topic: $iothub/twin/get
    Payload: <data>

Reakcja:

<- DISCONNECT
    Reason_Code: 131
    status: 0100
    reason: "`Correlation Data` property is missing"

Następne kroki