Dokumentacja interfejsu API MQTT 5 płaszczyzny danych usługi IoT Hub (przestarzała)

Ten dokument definiuje operacje dostępne w wersji 2.0 (api-version: 2020-10-01-preview) interfejsu API płaszczyzny danych usługi IoT Hub.

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.

Operacje

Uzyskiwanie reprezentacji bliźniaczej

Uzyskiwanie stanu bliźniaczej reprezentacji

Żądanie

Nazwa tematu: $iothub/twin/get

Właściwości: brak

Ładunek: pusty

Odpowiedź na powodzenie

Właściwości: brak

Ładunek: bliźniacze reprezentacje

Odpowiedzi alternatywne

Stan	Nazwa/nazwisko	opis
0100	Nieprawidłowe żądanie	Komunikat operacji jest źle sformułowany i nie można go przetworzyć.
0101	Brak autoryzacji	Klient nie ma autoryzacji do wykonania operacji.
0102	Niedozwolone	Operacja nie jest dozwolona.
0501	Ograniczono	Szybkość żądań jest zbyt wysoka na jednostkę SKU
0502	Przekroczono limit przydziału	przekroczono dzienny limit przydziału na bieżącą jednostkę SKU
0601	Błąd serwera	wewnętrzny błąd serwera
0602	Timeout	upłynął limit czasu operacji przed jego ukończeniem
0603	Serwer zajęty	serwer zajęty

Przykład przykładowy kod przykładowy

-> PUBLISH
    QoS: 0
    Topic: $iothub/twin/get
<- PUBLISH
    QoS: 0
    Topic: $iothub/responses

Zgłoszono bliźniacze reprezentacje poprawki

Zgłoszony stan bliźniaczej reprezentacji poprawki

Żądanie

Nazwa tematu: $iothub/twin/patch/reported

Właściwości:

Nazwisko	Type	Wymagania	opis
if-version	u64	nie

Ładunek: TwinState

Odpowiedź na powodzenie

Właściwości:

Nazwisko	Type	Wymagania	Opis
version	u64	tak	Wersja zgłoszonego stanu po zastosowaniu poprawki

Ładunek: pusty

Odpowiedzi alternatywne

Stan	Nazwa/nazwisko	opis
0104	Warunek wstępny nie powiódł się	warunek wstępny nie został spełniony, co spowodowało anulowanie żądania
0100	Nieprawidłowe żądanie	Komunikat operacji jest źle sformułowany i nie można go przetworzyć.
0101	Brak autoryzacji	Klient nie ma autoryzacji do wykonania operacji.
0102	Niedozwolone	Operacja nie jest dozwolona.
0501	Ograniczono	Szybkość żądań jest zbyt wysoka na jednostkę SKU
0502	Przekroczono limit przydziału	przekroczono dzienny limit przydziału na bieżącą jednostkę SKU
0601	Błąd serwera	wewnętrzny błąd serwera
0602	Timeout	upłynął limit czasu operacji przed jego ukończeniem
0603	Serwer zajęty	serwer zajęty

Przykład przykładowy kod przykładowy

-> PUBLISH
    QoS: 0
    Topic: $iothub/twin/patch/reported
    [if-version: <u64>]
<- PUBLISH
    QoS: 0
    Topic: $iothub/responses

Odbieranie poleceń

Odbieranie i obsługa poleceń

Komunikat

Nazwa tematu: $iothub/commands

Właściwości:

Nazwisko	Type	Wymagania	opis
sekwencja-nie	u64	tak	Numer sekwencji komunikatu
enqueued-time	time	tak	Znacznik czasu wprowadzenia komunikatu do systemu
liczba dostaw	u32	tak	Liczba prób dostarczenia komunikatów
czas tworzenia	time	nie	Sygnatura czasowa utworzenia wiadomości (dostarczona przez nadawcę)
message-id	string	nie	Tożsamość wiadomości (dostarczana przez nadawcę)
identyfikator użytkownika	string	nie	Tożsamość użytkownika (dostarczana przez nadawcę)
identyfikator korelacji	string	nie	Tożsamość korelacji (dostarczana przez nadawcę)
Typ zawartości	string	nie	określa typ zawartości ładunku
kodowanie zawartości	string	nie	określa kodowanie zawartości ładunku

Ładunek: dowolna sekwencja bajtów

Potwierdzenie powodzenia

Wskazuje, że polecenie zostało zaakceptowane do obsługi przez klienta

Właściwości: brak

Ładunek: pusty

Potwierdzenia alternatywne

Kod przyczyny	Stan	Nazwa/nazwisko	opis
131	0603	Abandon	Wskazuje, że polecenie nie zostanie w tej chwili przetworzone i powinno zostać ponownie wyświetlone w przyszłości.
131	0100	Odrzuć	Wskazuje, że klient odrzucił polecenie i nie powinien być ponownie podejmowana próba.

Przykład przykładowy kod przykładowy

-> SUBSCRIBE
    - Topic: $iothub/commands
      QoS: 1
<- PUBLISH
    QoS: 1
    Topic: $iothub/commands
    sequence-no: <u64>enqueued-time: <time>delivery-count: <u32>[creation-time: <time>][message-id: <string>][user-id: <string>][correlation-id: <string>][Content Type: <string>][content-encoding: <string>]
    Payload: ...

-> PUBACK

Odbieranie metod bezpośrednich

Odbieranie i obsługa wywołań metody bezpośredniej

Żądanie

Nazwa tematu: $iothub/methods/{name}

Właściwości: brak

Ładunek: dowolna sekwencja bajtów

Odpowiedź na powodzenie

Właściwości:

Nazwisko	Type	Wymagania	opis
kod odpowiedzi	u32	tak

Ładunek: dowolna sekwencja bajtów

Odpowiedzi alternatywne

Stan	Nazwa/nazwisko	opis
06A0	Niedostępny	Wskazuje, że klient nie jest osiągalny za pośrednictwem tego połączenia.

Przykład przykładowy kod przykładowy

-> SUBSCRIBE
    - Topic: methods/{name}
      QoS: 0
<- SUBACK
<- PUBLISH
    QoS: 0
    Topic: $iothub/methods/{name}
-> PUBLISH
    QoS: 0
    Topic: $iothub/responses

Odbieranie zmian żądanego stanu bliźniaczej reprezentacji

Otrzymywanie aktualizacji żądanego stanu bliźniaczej reprezentacji

Komunikat

Nazwa tematu: $iothub/twin/patch/desired

Właściwości:

Nazwisko	Type	Wymagania	Opis
version	u64	tak	Wersja żądanego stanu pasująca do tej aktualizacji

Ładunek: TwinState

Przykład przykładowy kod przykładowy

-> SUBSCRIBE
    - Topic: $iothub/twin/patch/desired
      QoS: 0
<- PUBLISH
    QoS: 0
    Topic: $iothub/twin/patch/desired
    version: <u64>
    Payload: ...

Wysyłanie danych telemetrycznych

Opublikuj komunikat do kanału telemetrii — usługa Event Hubs domyślnie lub inny punkt końcowy za pośrednictwem konfiguracji routingu.

Komunikat

Nazwa tematu: $iothub/telemetry

Właściwości:

Nazwisko	Type	Wymagania	opis
Typ zawartości	string	nie	przekłada się na content-type właściwość system na wysłaną wiadomość
kodowanie zawartości	string	nie	przekłada się na content-encoding właściwość system na wysłaną wiadomość
message-id	string	nie	przekłada się na message-id właściwość system na wysłaną wiadomość
identyfikator użytkownika	string	nie	przekłada się na user-id właściwość system na wysłaną wiadomość
identyfikator korelacji	string	nie	przekłada się na correlation-id właściwość system na wysłaną wiadomość
czas tworzenia	time	nie	przekłada się na iothub-creation-time-utc właściwość w wiadomości opublikowanej

Napiwek

Format musi mieć format creation-time UTC bez informacji o strefie czasowej. Na przykład jest prawidłowy, 2021-04-21T11:30:16Z 2021-04-21T11:30:16-07:00 jest nieprawidłowy.

Ładunek: dowolna sekwencja bajtów

Potwierdzenie powodzenia

Komunikat został pomyślnie opublikowany w kanale telemetrii

Właściwości: brak

Ładunek: pusty

Potwierdzenia alternatywne

Kod przyczyny	Stan	Nazwa/nazwisko	opis
131	0100	Nieprawidłowe żądanie	Komunikat operacji jest źle sformułowany i nie można go przetworzyć.
135	0101	Brak autoryzacji	Klient nie ma autoryzacji do wykonania operacji.
131	0102	Niedozwolone	Operacja nie jest dozwolona.
131	0601	Błąd serwera	wewnętrzny błąd serwera
151	0501	Ograniczono	Szybkość żądań jest zbyt wysoka na jednostkę SKU
151	0502	Przekroczono limit przydziału	przekroczono dzienny limit przydziału na bieżącą jednostkę SKU
131	0602	Timeout	upłynął limit czasu operacji przed jego ukończeniem
131	0603	Serwer zajęty	serwer zajęty

Przykład przykładowy kod przykładowy

-> PUBLISH
    QoS: 1
    Topic: $iothub/telemetry
    [Content Type: <string>]
    [content-encoding: <string>]
    [message-id: <string>]
    [user-id: <string>]
    [correlation-id: <string>]
    [creation-time: <time>]

<- PUBACK

Odpowiedzi

Nieprawidłowe żądanie

Komunikat operacji jest źle sformułowany i nie można go przetworzyć.

Kod przyczyny: 131

Stan: 0100

Właściwości:

Nazwisko	Type	Wymagania	opis
reason	string	nie	zawiera informacje o tym, co konkretnie nie jest prawidłowe dotyczące komunikatu

Ładunek: pusty

Konflikt

Operacja jest w konflikcie z inną bieżącą operacją.

Kod przyczyny: 131

Stan: 0103

Właściwości:

Nazwisko	Type	Wymagania	opis
trace-id	string	nie	identyfikator śledzenia korelacji z inną diagnostyką błędu
reason	string	nie	zawiera informacje o tym, co konkretnie nie jest prawidłowe dotyczące komunikatu

Ładunek: pusty

Niedozwolone

Operacja nie jest dozwolona.

Kod przyczyny: 131

Stan: 0102

Właściwości:

Nazwisko	Type	Wymagania	opis
reason	string	nie	zawiera informacje o tym, co konkretnie nie jest prawidłowe dotyczące komunikatu

Ładunek: pusty

Brak autoryzacji

Klient nie ma autoryzacji do wykonania operacji.

Kod przyczyny: 135

Stan: 0101

Właściwości:

Nazwisko	Type	Wymagania	opis
trace-id	string	nie	identyfikator śledzenia korelacji z inną diagnostyką błędu

Ładunek: pusty

Nie znaleziono

żądany zasób nie istnieje

Kod przyczyny: 131

Stan: 0504

Właściwości:

Nazwisko	Type	Wymagania	opis
reason	string	nie	zawiera informacje o tym, co konkretnie nie jest prawidłowe dotyczące komunikatu

Ładunek: pusty

Niezmodyfikowane

Zasób nie został zmodyfikowany na podstawie podanego warunku wstępnego.

Kod przyczyny: 0

Stan: 0001

Właściwości: brak

Ładunek: pusty

Warunek wstępny nie powiódł się

Warunek wstępny nie został spełniony, co spowodowało anulowanie żądania

Kod przyczyny: 131

Stan: 0104

Właściwości: brak

Ładunek: pusty

Przekroczono limit przydziału

przekroczono dzienny limit przydziału na bieżącą jednostkę SKU

Kod przyczyny: 151

Stan: 0502

Właściwości: brak

Ładunek: pusty

Zasób wyczerpany

zasób nie ma pojemności do ukończenia operacji

Kod przyczyny: 131

Stan: 0503

Właściwości:

Nazwisko	Type	Wymagania	opis
reason	string	nie	zawiera informacje o tym, co konkretnie nie jest prawidłowe dotyczące komunikatu

Ładunek: pusty

Serwer zajęty

serwer zajęty

Kod przyczyny: 131

Stan: 0603

Właściwości:

Nazwisko	Type	Wymagania	opis
trace-id	string	nie	identyfikator śledzenia korelacji z inną diagnostyką błędu

Ładunek: pusty

Błąd serwera

wewnętrzny błąd serwera

Kod przyczyny: 131

Stan: 0601

Właściwości:

Nazwisko	Type	Wymagania	opis
trace-id	string	nie	identyfikator śledzenia korelacji z inną diagnostyką błędu

Ładunek: pusty

Element docelowy nie powiódł się

Element docelowy odpowiedział, ale odpowiedź była nieprawidłowa lub nieprawidłowo sformułowana

Kod przyczyny: 131

Stan: 06A2

Właściwości:

Nazwisko	Type	Wymagania	opis
reason	string	nie	zawiera informacje o tym, co konkretnie nie jest prawidłowe dotyczące komunikatu

Ładunek: pusty

Limit czasu docelowego

Przekroczono limit czasu oczekiwania na ukończenie żądania przez element docelowy

Kod przyczyny: 131

Stan: 06A1

Właściwości:

Nazwisko	Type	Wymagania	opis
trace-id	string	nie	identyfikator śledzenia korelacji z inną diagnostyką błędu
reason	string	nie	zawiera informacje o tym, co konkretnie nie jest prawidłowe dotyczące komunikatu

Ładunek: pusty

Element docelowy jest niedostępny

Element docelowy jest niemożliwy do ukończenia żądania

Kod przyczyny: 131

Stan: 06A0

Właściwości: brak

Ładunek: pusty

Ograniczono

Szybkość żądań jest zbyt wysoka na jednostkę SKU

Kod przyczyny: 151

Stan: 0501

Właściwości: brak

Ładunek: pusty

Timeout

upłynął limit czasu operacji przed jego ukończeniem

Kod przyczyny: 131

Stan: 0602

Właściwości:

Nazwisko	Type	Wymagania	opis
trace-id	string	nie	identyfikator śledzenia korelacji z inną diagnostyką błędu

Ładunek: pusty