Protokół połączeń hybrydowych usługi Azure Relay
Usługa Azure Relay jest jednym z kluczowych filarów możliwości platformy Azure Service Bus. Nowa funkcja połączeń hybrydowych usługi Relay to bezpieczna ewolucja protokołu open-protocol oparta na protokołach HTTP i WebSocket. Zastępuje ona poprzednią, równie nazwaną funkcję BizTalk Services , która została zbudowana na zastrzeżonym fundamencie protokołu. Integracja połączeń hybrydowych z usługami aplikacja systemu Azure nadal działa zgodnie z rzeczywistym działaniem.
Połączenia hybrydowe umożliwiają dwukierunkową, żądaną i binarną komunikację strumieniową oraz prosty przepływ datagramu między dwiema aplikacjami sieciowymi. Obie strony mogą znajdować się za sieciami dostępu do sieci lub za zaporami.
W tym artykule opisano interakcje po stronie klienta z przekaźnikiem połączeń hybrydowych na potrzeby łączenia klientów w rolach odbiornika i nadawcy. Opisuje również sposób akceptowania nowych połączeń i żądań przez odbiorniki.
Model interakcji
Przekaźnik połączeń hybrydowych łączy dwie strony, zapewniając punkt spotkania w chmurze platformy Azure, z którym strony mogą odnajdywać i łączyć się z własną siecią. Punkt spotkania nosi nazwę "Połączenie hybrydowe" w tej i innej dokumentacji, w interfejsach API, a także w witrynie Azure Portal. Punkt końcowy usługi Połączenia hybrydowe jest określany jako "usługa" w pozostałej części tego artykułu.
Usługa umożliwia przekazywanie połączeń web socket i żądań i odpowiedzi HTTP(S).
Model interakcji opiera się na nomenklaturze ustanowionej przez wiele innych interfejsów API sieci. Istnieje odbiornik, który najpierw wskazuje gotowość do obsługi połączeń przychodzących, a następnie akceptuje je po nadejściu. Po drugiej stronie klient łączy się z odbiornikiem, spodziewając się, że połączenie zostanie zaakceptowane w celu ustanowienia dwukierunkowej ścieżki komunikacji. "Połącz", "Nasłuchiwanie" i "Akceptuj" są tymi samymi terminami, które można znaleźć w większości interfejsów API gniazd.
Każdy model komunikacji przekazywanej ma jedną ze stron nawiązywanie połączeń wychodzących w kierunku punktu końcowego usługi. Sprawia to, że "odbiornik" jest również "klientem" w potocznym użyciu, a także może powodować inne przeciążenia terminologii. Dokładna terminologia używana w związku z tym dla połączeń hybrydowych jest następująca:
Programy po obu stronach połączenia są nazywane "klientami", ponieważ są klientami usługi. Klient, który czeka i akceptuje połączenia, jest "odbiornikiem" lub mówi się, że jest w "roli odbiornika". Klient, który inicjuje nowe połączenie z odbiornikiem za pośrednictwem usługi, jest nazywany "nadawcą" lub znajduje się w "roli nadawcy".
Interakcje odbiornika
Odbiornik ma pięć interakcji z usługą; wszystkie szczegóły przewodu zostały opisane w dalszej części tego artykułu w sekcji referencyjnej.
Komunikaty nasłuchiwania, akceptowania i żądania są odbierane z usługi. Operacje Odnów i Ping są wysyłane przez odbiornik.
Nasłuchiwanie komunikatu
Aby wskazać gotowość do usługi, którą odbiornik jest gotowy do akceptowania połączeń, tworzy wychodzące połączenie protokołu WebSocket. Uzgadnianie połączenia prowadzi nazwę połączenia hybrydowego skonfigurowanego w przestrzeni nazw usługi Relay oraz token zabezpieczający, który nadaje "Nasłuchiwanie" bezpośrednio na tej nazwie.
Po zaakceptowaniu przez usługę protokołu WebSocket rejestracja zostanie ukończona, a ustanowiony zestaw WebSocket jest utrzymywany jako "kanał kontrolny" umożliwiający włączenie wszystkich kolejnych interakcji. Usługa umożliwia maksymalnie 25 współbieżnych odbiorników dla jednego połączenia hybrydowego. Należy określić limit przydziału dla elementów AppHook.
W przypadku połączeń hybrydowych, jeśli istnieją co najmniej dwa aktywne odbiorniki, połączenia przychodzące są równoważona w ich kolejności losowej; Próba sprawiedliwego rozkładu jest podejmowana z najlepszym wysiłkiem.
Zaakceptuj wiadomość
Gdy nadawca otworzy nowe połączenie w usłudze, usługa wybierze i powiadomi jeden z aktywnych odbiorników w połączeniu hybrydowym. To powiadomienie jest wysyłane do odbiornika za pośrednictwem otwartego kanału sterowania jako komunikat JSON. Komunikat zawiera adres URL punktu końcowego protokołu WebSocket, z którym odbiornik musi nawiązać połączenie w celu zaakceptowania połączenia.
Adres URL może i musi być używany bezpośrednio przez odbiornik bez dodatkowej pracy. Zakodowane informacje są ważne tylko przez krótki okres czasu, o ile nadawca chce poczekać na nawiązanie połączenia. Maksymalna wartość do założyć to 30 sekund. Adres URL może być używany tylko w przypadku jednej pomyślnej próby nawiązania połączenia. Po nawiązaniu połączenia protokołu WebSocket z adresem URL spotkania wszystkie dalsze działania w tym obiekcie WebSocket są przekazywane z adresu i do nadawcy. To zachowanie odbywa się bez żadnej interwencji ani interpretacji przez usługę.
Komunikat żądania
Oprócz połączeń protokołu WebSocket odbiornik może również odbierać ramki żądań HTTP od nadawcy, jeśli ta funkcja jest jawnie włączona w połączeniu hybrydowym.
Odbiorniki dołączane do połączeń hybrydowych z obsługą protokołu HTTP MUSZĄ obsługiwać request gest. Odbiornik, który nie obsługuje request i w związku z tym powoduje powtarzające się błędy przekroczenia limitu czasu, podczas gdy połączenie może zostać zablokowane przez usługę w przyszłości.
Metadane nagłówka ramki HTTP są tłumaczone na kod JSON w celu prostszej obsługi przez platformę odbiornika, ponieważ biblioteki analizowania nagłówków HTTP są rzadsze niż analizatory JSON. Metadane HTTP, które są istotne tylko dla relacji między nadawcą i bramą HTTP przekaźnika, w tym informacje o autoryzacji, nie są przekazywane. Treść żądań HTTP jest w przezroczysty sposób transferowana jako binarne ramki protokołu WebSocket.
Odbiornik może odpowiadać na żądania HTTP przy użyciu równoważnego gestu odpowiedzi.
Przepływ żądania/odpowiedzi domyślnie używa kanału sterowania, ale może być "uaktualniony" do odrębnego spotkania protokołu WebSocket zawsze, gdy jest to wymagane. Różne połączenia protokołu WebSocket zwiększają przepływność każdej konwersacji klienta, ale obciążają odbiornik większymi połączeniami, które muszą być obsługiwane, co może nie być pożądane w przypadku lekkich klientów.
W kanale kontrolnym treść żądania i odpowiedzi jest ograniczona do maksymalnie 64 kB rozmiaru. Metadane nagłówka HTTP są ograniczone do łącznej liczby 32 kB. Jeśli żądanie lub odpowiedź przekroczy ten próg, odbiornik MUSI uaktualnić do spotkania WebSocket przy użyciu gestu równoważnego obsłudze akceptowania.
W przypadku żądań usługa decyduje, czy żądać żądań za pośrednictwem kanału sterowania. Obejmuje to, ale nie może być ograniczone do przypadków, gdy żądanie przekracza 64 kB (nagłówki i treść) wprost lub jeśli żądanie jest wysyłane z "fragmentowaną" kodowaniem transferu, a usługa ma powód, aby oczekiwać, że żądanie przekroczy 64 kB lub odczytanie żądania nie jest natychmiastowe. Jeśli usługa zdecyduje się dostarczyć żądanie w ramach spotkania, przekazuje tylko adres spotkania do odbiornika. Następnie odbiornik MUSI ustanowić spotkanie WebSocket i usługa natychmiast dostarcza pełne żądanie, w tym treść nad spotkaniem WebSocket. Odpowiedź MUSI również używać rendezvous WebSocket.
W przypadku żądań, które docierają do kanału sterowania, odbiornik decyduje, czy odpowiedzieć za pośrednictwem kanału sterowania, czy za pośrednictwem spotkania. Usługa MUSI zawierać adres spotkania z każdym żądaniem kierowanym przez kanał kontrolny. Ten adres jest prawidłowy tylko w przypadku uaktualniania z bieżącego żądania.
Jeśli odbiornik zdecyduje się uaktualnić, łączy się i natychmiast dostarcza odpowiedź za pośrednictwem ustalonego gniazda spotkania.
Po ustanowieniu spotkania protokołu WebSocket odbiornik POWINIEN obsługiwać go w celu dalszej obsługi żądań i odpowiedzi od tego samego klienta. Usługa obsługuje protokół WebSocket tak długo, jak połączenie gniazda HTTPS z nadawcą jest utrwalane i kieruje wszystkie kolejne żądania od tego nadawcy za pośrednictwem obsługiwanego protokołu WebSocket. Jeśli odbiornik zdecyduje się usunąć spotkanie protokołu WebSocket z boku, usługa również przerywa połączenie z nadawcą, niezależnie od tego, czy kolejne żądanie może już być w toku.
Odnawianie operacji
Token zabezpieczający, który musi być używany do rejestrowania odbiornika i obsługi kanału kontroli może wygasnąć, gdy odbiornik jest aktywny. Wygaśnięcie tokenu nie ma wpływu na trwające połączenia, ale powoduje, że kanał kontroli zostanie porzucony przez usługę lub wkrótce po wygaśnięciu. Operacja "odnów" to komunikat JSON, który odbiornik może wysłać w celu zastąpienia tokenu skojarzonego z kanałem sterowania, dzięki czemu kanał kontrolny może być utrzymywany przez dłuższy czas.
Operacja ping
Jeśli kanał kontrolny pozostaje bezczynny przez długi czas, pośrednicy w drodze, tacy jak moduły równoważenia obciążenia lub sieci, mogą usunąć połączenie TCP. Operacja "ping" pozwala uniknąć tego, wysyłając niewielką ilość danych w kanale, która przypomina wszystkim na trasie sieciowej, że połączenie ma być aktywne, a także służy jako "test na żywo" dla odbiornika. Jeśli polecenie ping zakończy się niepowodzeniem, kanał kontrolny powinien być traktowany jako bezużyteczny, a odbiornik powinien ponownie nawiązać połączenie.
Interakcja nadawcy
Nadawca ma dwie interakcje z usługą: łączy gniazdo sieci Web lub wysyła żądania za pośrednictwem protokołu HTTPS. Żądania nie mogą być wysyłane za pośrednictwem gniazda internetowego z roli nadawcy.
Operacja nawiązywania połączenia
Operacja "połącz" otwiera protokół WebSocket w usłudze, podając nazwę połączenia hybrydowego i (opcjonalnie, ale domyślnie wymagany) token zabezpieczający przyznający uprawnienie "Wyślij" w ciągu zapytania. Następnie usługa wchodzi w interakcję z odbiornikiem w sposób opisany wcześniej, a odbiornik tworzy połączenie spotkania, które jest przyłączone do tego protokołu WebSocket. Po zaakceptowaniu protokołu WebSocket wszystkie dalsze interakcje w tym zestawie WebSocket są połączonego odbiornika.
Operacja żądania
W przypadku połączeń hybrydowych, dla których włączono tę funkcję, nadawca może wysyłać w dużej mierze nieograniczone żądania HTTP do odbiorników.
Z wyjątkiem tokenu dostępu przekaźnika, który jest osadzony w ciągu zapytania lub w nagłówku HTTP żądania, przekaźnik jest w pełni niewidoczny dla wszystkich operacji HTTP na adres przekaźnika i wszystkich sufiksów ścieżki adresu przekaźnika, pozostawiając odbiornik w pełni kontrolę nad kompleksową autoryzacją, a nawet funkcjami rozszerzenia HTTP, takimi jak CORS.
Autoryzacja nadawcy z punktem końcowym przekaźnika jest domyślnie włączona, ale jest opcjonalna. Właściciel połączenia hybrydowego może zezwolić anonimowym nadawcom. Usługa przechwytuje, sprawdza i usuwa informacje o autoryzacji w następujący sposób:
- Jeśli ciąg zapytania zawiera
sb-hc-tokenwyrażenie, wyrażenie zawsze zostanie usunięte z ciągu zapytania. Zostanie on oceniony, jeśli autoryzacja usługi Relay jest włączona. - Jeśli nagłówki żądania zawierają
ServiceBusAuthorizationnagłówek, wyrażenie nagłówka zawsze zostanie usunięte z kolekcji nagłówków. Zostanie on oceniony, jeśli autoryzacja usługi Relay jest włączona. - Tylko wtedy, gdy autoryzacja usługi Relay jest włączona, a nagłówki żądania zawierają
Authorizationnagłówek, a żadne z poprzednich wyrażeń nie jest obecne, nagłówek zostanie oceniony i pozbawiony. W przeciwnym razie elementAuthorizationjest zawsze przekazywany zgodnie z rzeczywistymi wartościami.
Jeśli nie ma aktywnego odbiornika, usługa zwróci kod błędu 502 "Zła brama". Jeśli usługa nie obsługuje żądania, usługa zwróci limit czasu bramy 504 po 60 sekundach.
Podsumowanie interakcji
Wynikiem tego modelu interakcji jest to, że klient nadawcy wychodzi z uzgadniania z "czystym" zestawem WebSocket, który jest połączony z odbiornikiem i nie wymaga dalszych preambułów ani przygotowań. Ten model umożliwia praktycznie dowolną istniejącą implementację klienta protokołu WebSocket w celu łatwości korzystania z usługi połączeń hybrydowych przez podanie poprawnie skonstruowanego adresu URL w warstwie klienta protokołu WebSocket.
Rendezvous connection WebSocket, który odbiornik uzyskuje za pośrednictwem interakcji akceptowania jest również czysty i może być przekazywany do dowolnej istniejącej implementacji serwera WebSocket z minimalną dodatkową abstrakcją, która odróżnia operacje "akceptuj" na odbiornikach sieci lokalnej ich struktury i zdalnych połączeń hybrydowych "akceptuj".
Model żądania/odpowiedzi HTTP daje nadawcy w dużej mierze nieograniczony obszar powierzchni protokołu HTTP z opcjonalną warstwą autoryzacji. Odbiornik pobiera wstępnie przeanalizowaną sekcję nagłówka żądania HTTP, która może zostać przekształcona z powrotem w podrzędne żądanie HTTP lub obsłużona w taki sposób, z ramkami binarnymi niosącymi treść HTTP. Odpowiedzi używają tego samego formatu. Interakcje z mniej niż 64 KB treści żądania i odpowiedzi można obsłużyć za pośrednictwem jednego gniazda sieci Web, który jest współużytkowany dla wszystkich nadawców. Większe żądania i odpowiedzi można obsłużyć przy użyciu modelu spotkania.
Dokumentacja protokołu
W tej sekcji opisano szczegóły interakcji z protokołem opisanych wcześniej.
Wszystkie połączenia protokołu WebSocket są wykonywane na porcie 443 jako uaktualnienie z protokołu HTTPS 1.1, który jest często abstrakcjonowany przez niektóre struktury lub interfejs API protokołu WebSocket. Opis w tym miejscu jest neutralny dla implementacji bez sugerowania określonej struktury.
Protokół odbiornika
Protokół odbiornika składa się z dwóch gestów połączenia i trzech operacji komunikatów.
Połączenie kanału sterowania odbiornikiem
Kanał sterowania jest otwierany przy użyciu tworzenia połączenia protokołu WebSocket z:
wss://{namespace-address}/$hc/{path}?sb-hc-action=...[&sb-hc-id=...]&sb-hc-token=...
Jest namespace-address to w pełni kwalifikowana nazwa domeny przestrzeni nazw usługi Azure Relay, która hostuje połączenie hybrydowe, zazwyczaj w postaci {myname}.servicebus.windows.net.
Opcje parametrów ciągu zapytania są następujące.
| Parametr | Wymagania | opis |
|---|---|---|
sb-hc-action |
Tak | W przypadku roli odbiornika parametr musi mieć wartość sb-hc-action=listen |
{path} |
Tak | Ścieżka przestrzeni nazw zakodowana w adresie URL wstępnie skonfigurowanego połączenia hybrydowego w celu zarejestrowania tego odbiornika. To wyrażenie jest dołączane do stałej $hc/ części ścieżki. |
sb-hc-token |
Tak* | Odbiornik musi podać prawidłowy token dostępu współdzielonego usługi Service Bus zakodowany w adresie URL dla przestrzeni nazw lub połączenia hybrydowego, który nadaje prawo nasłuchiwania . |
sb-hc-id |
Nie. | Ten opcjonalny identyfikator dostarczony przez klienta umożliwia kompleksowe śledzenie diagnostyczne. |
Jeśli połączenie protokołu WebSocket nie powiedzie się z powodu niezarejestrowania ścieżki połączenia hybrydowego lub nieprawidłowego lub brakującego tokenu lub innego błędu, opinia o błędzie jest dostarczana przy użyciu zwykłego modelu opinii o stanie HTTP 1.1. Opis stanu zawiera identyfikator śledzenia błędów, który można przekazać pomoc techniczna platformy Azure personelowi:
| Kod | Błąd | opis |
|---|---|---|
| 404 | Nie znaleziono | Ścieżka połączenia hybrydowego jest nieprawidłowa lub podstawowy adres URL jest źle sformułowany. |
| 401 | Brak autoryzacji | Brak tokenu zabezpieczającego lub jest on nieprawidłowo sformułowany lub nieprawidłowy. |
| 403 | Dostęp zabroniony | Token zabezpieczający nie jest prawidłowy dla tej ścieżki dla tej akcji. |
| 500 | Błąd wewnętrzny | Wystąpił problem w usłudze. |
Jeśli połączenie protokołu WebSocket jest celowo zamykane przez usługę po jej początkowym skonfigurowaniu, przyczyna takiej czynności jest przekazywana przy użyciu odpowiedniego kodu błędu protokołu WebSocket wraz z opisowym komunikatem o błędzie zawierającym również identyfikator śledzenia. Usługa nie zamknie kanału sterowania bez napotkania warunku błędu. Każde czyste zamknięcie jest kontrolowane przez klienta.
| Stan programu WS | opis |
|---|---|
| 1001 | Ścieżka połączenia hybrydowego została usunięta lub wyłączona. |
| 1008 | Token zabezpieczający wygasł, dlatego zasady autoryzacji są naruszane. |
| 1011 | Wystąpił problem w usłudze. |
Zaakceptuj uścisk dłoni
Powiadomienie "accept" jest wysyłane przez usługę do odbiornika za pośrednictwem wcześniej ustanowionego kanału sterowania jako komunikat JSON w ramce tekstowej protokołu WebSocket. Nie ma odpowiedzi na tę wiadomość.
Komunikat zawiera obiekt JSON o nazwie accept, który definiuje następujące właściwości w tej chwili:
- address — parametry adresu URL, które mają być używane do ustanawiania protokołu WebSocket w usłudze w celu akceptowania połączenia przychodzącego.
- id — unikatowy identyfikator dla tego połączenia. Jeśli identyfikator został dostarczony przez klienta nadawcy, jest to wartość podana przez nadawcę, w przeciwnym razie jest to wartość wygenerowana przez system.
- connectHeaders — wszystkie nagłówki HTTP, które zostały dostarczone do punktu końcowego przekaźnika przez nadawcę, który zawiera również sec-WebSocket-Protocol i sec-WebSocket-Extensions nagłówki.
{
"accept" : {
"address" : "wss://dc-node.servicebus.windows.net:443/$hc/{path}?...",
"id" : "4cb542c3-047a-4d40-a19f-bdc66441e736",
"connectHeaders" : {
"Host" : "...",
"Sec-WebSocket-Protocol" : "...",
"Sec-WebSocket-Extensions" : "..."
}
}
}
Adres URL podany w komunikacie JSON jest używany przez odbiornik do ustanowienia protokołu WebSocket do akceptowania lub odrzucania gniazda nadawcy.
Akceptowanie gniazda
Aby zaakceptować, odbiornik ustanawia połączenie protokołu WebSocket z podanym adresem.
Jeśli komunikat "accept" zawiera Sec-WebSocket-Protocol nagłówek, oczekuje się, że odbiornik akceptuje tylko protokół WebSocket, jeśli obsługuje ten protokół. Ponadto ustawia nagłówek jako ustanowiony element WebSocket.
To samo dotyczy nagłówka Sec-WebSocket-Extensions . Jeśli platforma obsługuje rozszerzenie, powinna ustawić nagłówek na odpowiedź po stronie serwera wymaganego Sec-WebSocket-Extensions uzgadniania rozszerzenia.
Adres URL musi być używany jako do ustanawiania gniazda akceptowania, ale zawiera następujące parametry:
| Parametr | Wymagania | opis |
|---|---|---|
sb-hc-action |
Tak | Aby zaakceptować gniazdo, parametr musi być sb-hc-action=accept |
{path} |
Tak | (zobacz następujący akapit) |
sb-hc-id |
Nie. | Zobacz poprzedni opis identyfikatora. |
{path} to ścieżka przestrzeni nazw zakodowana w adresie URL wstępnie skonfigurowanego połączenia hybrydowego, na którym ma zostać zarejestrowany ten odbiornik. To wyrażenie jest dołączane do stałej $hc/ części ścieżki.
Wyrażenie path może zostać rozszerzone sufiksem i wyrażeniem ciągu zapytania, które jest zgodne z zarejestrowaną nazwą po oddzielającym ukośniku.
Ten parametr umożliwia klientowi nadawcy przekazywanie argumentów wysyłania do odbiornika akceptującego, gdy nie jest możliwe dołączenie nagłówków HTTP. Oczekuje się, że struktura odbiornika analizuje część stałej ścieżki i zarejestrowaną nazwę ze ścieżki i sprawia, że reszta, prawdopodobnie bez żadnych argumentów ciągu zapytania poprzedzonych prefiksem przez sb-aplikację, aby zdecydować, czy zaakceptować połączenie.
Aby uzyskać więcej informacji, zobacz następującą sekcję "Protokół nadawcy".
Jeśli wystąpi błąd, usługa może odpowiedzieć w następujący sposób:
| Kod | Błąd | opis |
|---|---|---|
| 403 | Dostęp zabroniony | Adres URL jest nieprawidłowy. |
| 500 | Błąd wewnętrzny | Wystąpił problem w usłudze |
Po nawiązaniu połączenia serwer zamyka zestaw WebSocket po zamknięciu protokołu WebSocket nadawcy lub o następującym stanie:
| Stan programu WS | opis |
|---|---|
| 1001 | Klient nadawcy zamyka połączenie. |
| 1001 | Ścieżka połączenia hybrydowego została usunięta lub wyłączona. |
| 1008 | Token zabezpieczający wygasł, dlatego zasady autoryzacji są naruszane. |
| 1011 | Wystąpił problem w usłudze. |
Odrzucanie gniazda
Odrzucenie gniazda po sprawdzeniu komunikatu accept wymaga podobnego uzgadniania, tak aby kod stanu i opis stanu komunikujący przyczynę odrzucenia mogły wrócić do nadawcy.
Wybór projektu protokołu polega na użyciu uzgadniania protokołu WebSocket (który został zaprojektowany tak, aby zakończył się zdefiniowanym stanem błędu), aby implementacje klienta odbiornika mogły nadal polegać na kliencie Protokołu WebSocket i nie muszą korzystać z dodatkowego, nago klienta HTTP.
Aby odrzucić gniazdo, klient przyjmuje identyfikator URI adresu z komunikatu accept i dołącza do niego dwa parametry ciągu zapytania w następujący sposób:
| Param | Wymagania | opis |
|---|---|---|
| sb-hc-statusCode | Tak | Numeryczny kod stanu HTTP. |
| sb-hc-statusDescription | Tak | Czytelny powód odrzucenia przez człowieka. |
Wynikowy identyfikator URI jest następnie używany do ustanowienia połączenia protokołu WebSocket.
Po poprawnym zakończeniu tego uzgadniania celowo kończy się niepowodzeniem z kodem błędu HTTP 410, ponieważ nie ustalono protokołu WebSocket. Jeśli coś pójdzie nie tak, następujące kody opisują błąd:
| Kod | Błąd | opis |
|---|---|---|
| 403 | Dostęp zabroniony | Adres URL jest nieprawidłowy. |
| 500 | Błąd wewnętrzny | Wystąpił problem w usłudze. |
Komunikat żądania
Komunikat request jest wysyłany przez usługę do odbiornika za pośrednictwem kanału sterowania. Ten sam komunikat jest również wysyłany za pośrednictwem spotkania WebSocket po ustanowieniu.
Element request składa się z dwóch części: nagłówka i ramek treści binarnych.
Jeśli nie ma treści, ramki ciała zostaną pominięte. Właściwość logiczna body wskazuje, czy treść znajduje się w komunikacie żądania.
W przypadku żądania z treścią żądania struktura może wyglądać następująco:
----- Web Socket text frame ----
{
"request" :
{
"body" : true,
...
}
}
----- Web Socket binary frame ----
FEFEFEFEFEFEFEFEFEFEF...
----- Web Socket binary frame ----
FEFEFEFEFEFEFEFEFEFEF...
----- Web Socket binary frame -FIN
FEFEFEFEFEFEFEFEFEFEF...
----------------------------------
Odbiornik MUSI obsługiwać odbieranie treści żądania podzielonej na wiele ramek binarnych (zobacz fragmenty protokołu WebSocket). Żądanie kończy się po odebraniu ramki binarnej z ustawioną flagą FIN.
W przypadku żądania bez treści istnieje tylko jedna ramka tekstowa.
----- Web Socket text frame ----
{
"request" :
{
"body" : false,
...
}
}
----------------------------------
Zawartość JSON dla elementu request jest następująca:
address — ciąg identyfikatora URI. Jest to adres spotkania, który ma być używany dla tego żądania. Jeśli żądanie przychodzące jest większe niż 64 kB, pozostała część tego komunikatu jest pozostawiona pusta, a klient MUSI zainicjować uzgadnianie zgodne
acceptz operacją opisaną poniżej. Następnie usługa umieści pełną wrequestustalonym gniazdie sieci Web. Jeśli odpowiedź może przekroczyć 64 kB, odbiornik MUSI również zainicjować uzgadnianie, a następnie przenieść odpowiedź za pośrednictwem ustanowionego gniazda sieci Web.id — ciąg. Unikatowy identyfikator tego żądania.
requestHeaders — ten obiekt zawiera wszystkie nagłówki HTTP, które zostały dostarczone do punktu końcowego przez nadawcę, z wyjątkiem informacji o autoryzacji, jak wyjaśniono powyżej, i nagłówki, które ściśle odnoszą się do połączenia z bramą. W szczególności wszystkie nagłówki zdefiniowane lub zarezerwowane w RFC7230, z wyjątkiem
Via, są rozłożone i nie są przekazywane:Connection(RFC7230, sekcja 6.1)Content-Length(RFC7230, sekcja 3.3.2)Host(RFC7230, sekcja 5.4)TE(RFC7230, sekcja 4.3)Trailer(RFC7230, sekcja 4.4)Transfer-Encoding(RFC7230, sekcja 3.3.1)Upgrade(RFC7230, sekcja 6.7)Close(RFC7230, sekcja 8.1)
requestTarget — ciąg. Ta właściwość zawiera "Element docelowy żądania" (RFC7230, sekcja 5.3) żądania. Zawiera fragment ciągu zapytania, który jest pozbawiony wszystkich
sb-hc-prefiksów parametrów.method — ciąg. Jest to metoda żądania na RFC7231 sekcji 4. Metoda
CONNECTNIE MOŻE być używana.body — wartość logiczna. Wskazuje, czy następuje jedna lub więcej ramek treści binarnych.
{
"request" : {
"address" : "wss://dc-node.servicebus.windows.net:443/$hc/{path}?...",
"id" : "42c34cb5-7a04-4d40-a19f-bdc66441e736",
"requestTarget" : "/abc/def?myarg=value&otherarg=...",
"method" : "GET",
"requestHeaders" : {
"Host" : "...",
"Content-Type" : "...",
"User-Agent" : "..."
},
"body" : true
}
}
Odpowiadanie na żądania
Odbiorca MUSI odpowiedzieć. Powtarzające się niepowodzenie odpowiadania na żądania przy zachowaniu połączenia może spowodować zablokowanie odbiornika.
Odpowiedzi mogą być wysyłane w dowolnej kolejności, ale każde żądanie musi odpowiadać w ciągu 60 sekund lub dostawa zostanie zgłoszona jako niepowodzenie. 60-sekundowy termin jest liczone do momentu response odebrania ramki przez usługę. Ciągła odpowiedź z wieloma ramkami binarnymi nie może stać się bezczynna przez ponad 60 sekund lub została zakończona.
Jeśli żądanie zostanie odebrane za pośrednictwem kanału sterowania, odpowiedź MUSI zostać wysłana na kanale kontrolnym, z którego żądanie zostało odebrane lub musi zostać wysłana za pośrednictwem kanału spotkania.
Odpowiedź to obiekt JSON o nazwie response. Reguły obsługi zawartości treści są dokładnie podobne do komunikatu request i oparte na body właściwości.
- requestId — ciąg. WYMAGANE.
idWartość właściwości odpowiedzi komunikaturequest. - statusCode — liczba. WYMAGANE. numeryczny kod stanu HTTP wskazujący wynik powiadomienia. Wszystkie kody stanu RFC7231, sekcja 6 są dozwolone, z wyjątkiem 502 "Zła brama" i 504 — limit czasu bramy.
- statusDescription — ciąg. FAKULTATYWNY. Fraza przyczyny stanu HTTP na RFC7230, sekcja 3.1.2
- responseHeaders — nagłówki HTTP do ustawienia w zewnętrznej odpowiedzi HTTP.
Podobnie jak w przypadku ,
requestRFC7230 zdefiniowane nagłówki NIE MOGĄ być używane. - body — wartość logiczna. Wskazuje, czy ramki treści binarnych są zgodne.
----- Web Socket text frame ----
{
"response" : {
"requestId" : "42c34cb5-7a04-4d40-a19f-bdc66441e736",
"statusCode" : "200",
"responseHeaders" : {
"Content-Type" : "application/json",
"Content-Encoding" : "gzip"
}
"body" : true
}
}
----- Web Socket binary frame -FIN
{ "hey" : "mydata" }
----------------------------------
Odpowiadanie za pośrednictwem spotkania
W przypadku odpowiedzi przekraczających 64 kB odpowiedź MUSI zostać dostarczona za pośrednictwem gniazda spotkania. Ponadto, jeśli żądanie przekracza 64 kB, a request tylko zawiera pole adresu, należy ustanowić gniazdo spotkania w celu uzyskania request. Po ustanowieniu gniazda rendezvous odpowiedzi na odpowiedniego klienta i kolejne żądania od tego odpowiedniego klienta MUSZĄ być dostarczane przez gniazdo rendezvous, gdy będzie się powtarzać.
Adres address URL w elemecie request musi być używany jako do ustanawiania gniazda rendezvous, ale zawiera następujące parametry:
| Parametr | Wymagania | opis |
|---|---|---|
sb-hc-action |
Tak | Aby zaakceptować gniazdo, parametr musi być sb-hc-action=request |
Jeśli wystąpi błąd, usługa może odpowiedzieć w następujący sposób:
| Kod | Błąd | Opis |
|---|---|---|
| 400 | Nieprawidłowe żądanie | Nierozpoznana akcja lub adres URL są nieprawidłowe. |
| 403 | Dostęp zabroniony | Adres URL wygasł. |
| 500 | Błąd wewnętrzny | Wystąpił problem w usłudze |
Po nawiązaniu połączenia serwer zamyka protokół WebSocket po zamknięciu gniazda HTTP klienta lub o następującym stanie:
| Stan programu WS | opis |
|---|---|
| 1001 | Klient nadawcy zamyka połączenie. |
| 1001 | Ścieżka połączenia hybrydowego została usunięta lub wyłączona. |
| 1008 | Token zabezpieczający wygasł, dlatego zasady autoryzacji są naruszane. |
| 1011 | Wystąpił problem w usłudze. |
Odnawianie tokenu odbiornika
Gdy token odbiornika wkrótce wygaśnie, może go zastąpić, wysyłając komunikat ramki tekstowej do usługi za pośrednictwem ustanowionego kanału sterowania. Komunikat zawiera obiekt JSON o nazwie renewToken, który definiuje w tej chwili następującą właściwość:
- token — prawidłowy token dostępu współużytkowanego usługi Service Bus zakodowany w adresie URL dla przestrzeni nazw lub połączenia hybrydowego , który nadaje prawo nasłuchiwania .
{
"renewToken": {
"token":
"SharedAccessSignature sr=http%3a%2f%2fcontoso.servicebus.windows.net%2fhyco%2f&sig=XXXXXXXXXX%3d&se=1471633754&skn=SasKeyName"
}
}
Jeśli sprawdzanie poprawności tokenu zakończy się niepowodzeniem, odmowa dostępu i usługa w chmurze zamknie kanał kontroli WebSocket z powodu błędu. W przeciwnym razie nie ma odpowiedzi.
| Stan programu WS | opis |
|---|---|
| 1008 | Token zabezpieczający wygasł, dlatego zasady autoryzacji są naruszane. |
Protokół Web Socket Connect
Protokół nadawcy jest w rzeczywistości identyczny z sposobem ustanowienia odbiornika. Celem jest maksymalna przejrzystość kompleksowego protokołu WebSocket. Adres, z który ma nawiązać połączenie, jest taki sam jak w przypadku odbiornika, ale "akcja" różni się, a token wymaga innego uprawnienia:
wss://{namespace-address}/$hc/{path}?sb-hc-action=...&sb-hc-id=...&sb-hc-token=...
Przestrzeń nazw to w pełni kwalifikowana nazwa domeny przestrzeni nazw usługi Azure Relay, która hostuje połączenie hybrydowe, zazwyczaj w postaci {myname}.servicebus.windows.net.
Żądanie może zawierać dowolne dodatkowe nagłówki HTTP, w tym zdefiniowane przez aplikację. Wszystkie dostarczone nagłówki przepływają do odbiornika i można je znaleźć w connectHeader obiekcie akceptowania komunikatu sterującego.
Opcje parametrów ciągu zapytania są następujące:
| Param | Wymagany? | opis |
|---|---|---|
sb-hc-action |
Tak | W przypadku roli nadawcy parametr musi mieć wartość sb-hc-action=connect. |
{path} |
Tak | (zobacz następujący akapit) |
sb-hc-token |
Tak* | Odbiornik musi podać prawidłowy token dostępu współdzielonego usługi Service Bus zakodowany w adresie URL dla przestrzeni nazw lub połączenia hybrydowego, który nadaje prawo wysyłania. |
sb-hc-id |
Nie. | Opcjonalny identyfikator, który umożliwia kompleksowe śledzenie diagnostyczne i jest udostępniany odbiornikowi podczas uzgadniania. |
Jest {path} to ścieżka przestrzeni nazw zakodowana w adresie URL wstępnie skonfigurowanego połączenia hybrydowego, na którym ma zostać zarejestrowany ten odbiornik. Wyrażenie path można rozszerzyć za pomocą sufiksu i wyrażenia ciągu zapytania w celu dalszej komunikacji. Jeśli połączenie hybrydowe jest zarejestrowane w ścieżce hyco, path wyrażenie może być hyco/suffix?param=value&... zgodne z parametrami ciągu zapytania zdefiniowanymi tutaj. Pełne wyrażenie może być następujące:
wss://{namespace-address}/$hc/hyco/suffix?param=value&sb-hc-action=...[&sb-hc-id=...&]sb-hc-token=...
Wyrażenie path jest przekazywane do odbiornika w identyfikatorze URI adresu zawartego w komunikacie kontrolnym "accept".
Jeśli połączenie protokołu WebSocket nie powiedzie się z powodu niezarejestrowania ścieżki połączenia hybrydowego, nieprawidłowego lub brakującego tokenu lub innego błędu, opinia o błędzie jest dostarczana przy użyciu zwykłego modelu opinii o stanie HTTP 1.1. Opis stanu zawiera identyfikator śledzenia błędów, który można przekazać pomoc techniczna platformy Azure personelowi:
| Kod | Błąd | opis |
|---|---|---|
| 404 | Nie znaleziono | Ścieżka połączenia hybrydowego jest nieprawidłowa lub podstawowy adres URL jest źle sformułowany. |
| 401 | Brak autoryzacji | Brak tokenu zabezpieczającego lub jest on nieprawidłowo sformułowany lub nieprawidłowy. |
| 403 | Dostęp zabroniony | Token zabezpieczający nie jest prawidłowy dla tej ścieżki i dla tej akcji. |
| 500 | Błąd wewnętrzny | Wystąpił problem w usłudze. |
Jeśli połączenie protokołu WebSocket jest celowo zamykane przez usługę po jej początkowym skonfigurowaniu, przyczyna tego działania jest przekazywana przy użyciu odpowiedniego kodu błędu protokołu WebSocket wraz z opisowym komunikatem o błędzie zawierającym również identyfikator śledzenia.
| Stan programu WS | opis |
|---|---|
| 1000 | Odbiornik zamyka gniazdo. |
| 1001 | Ścieżka połączenia hybrydowego została usunięta lub wyłączona. |
| 1008 | Token zabezpieczający wygasł, więc zasady autoryzacji są naruszane. |
| 1011 | Wystąpił problem w usłudze. |
Protokół żądania HTTP
Protokół żądania HTTP umożliwia dowolne żądania HTTP, z wyjątkiem uaktualnień protokołu. Żądania HTTP są wskazywane na zwykły adres środowiska uruchomieniowego jednostki bez $hc prefiksu, który jest używany dla klientów protokołu WebSocket połączeń hybrydowych.
https://{namespace-address}/{path}?sb-hc-token=...
Przestrzeń nazw to w pełni kwalifikowana nazwa domeny przestrzeni nazw usługi Azure Relay, która hostuje połączenie hybrydowe, zazwyczaj w postaci {myname}.servicebus.windows.net.
Żądanie może zawierać dowolne dodatkowe nagłówki HTTP, w tym zdefiniowane przez aplikację. Wszystkie dostarczone nagłówki, z wyjątkiem tych bezpośrednio zdefiniowanych w RFC7230 (zobacz Komunikat żądania) przepływ do odbiornika i można go znaleźć w requestHeader obiekcie komunikatu żądania .
Opcje parametrów ciągu zapytania są następujące:
| Param | Wymagany? | opis |
|---|---|---|
sb-hc-token |
Tak* | Odbiornik musi podać prawidłowy token dostępu współdzielonego usługi Service Bus zakodowany w adresie URL dla przestrzeni nazw lub połączenia hybrydowego, który nadaje prawo wysyłania. |
Token może być również przenoszony w nagłówku ServiceBusAuthorization http lub Authorization . Token można pominąć, jeśli połączenie hybrydowe jest skonfigurowane do zezwalania na żądania anonimowe.
Ponieważ usługa skutecznie działa jako serwer proxy, nawet jeśli nie jako prawdziwy serwer proxy HTTP, dodaje Via nagłówek lub dodaje adnotację do istniejącego Via nagłówka zgodnego z RFC7230, sekcja 5.7.1.
Usługa dodaje nazwę hosta przestrzeni nazw usługi Relay do Via.
| Kod | Wiadomość | opis |
|---|---|---|
| 200 | OK | Żądanie zostało obsłużone przez co najmniej jeden odbiornik. |
| 202 | Zaakceptowano | Żądanie zostało zaakceptowane przez co najmniej jeden odbiornik. |
Jeśli wystąpi błąd, usługa może odpowiedzieć w następujący sposób. Niezależnie od tego, czy odpowiedź pochodzi z usługi, czy z odbiornika, można zidentyfikować za pośrednictwem obecności nagłówka Via . Jeśli nagłówek jest obecny, odpowiedź pochodzi z odbiornika.
| Kod | Błąd | opis |
|---|---|---|
| 404 | Nie znaleziono | Ścieżka połączenia hybrydowego jest nieprawidłowa lub podstawowy adres URL jest źle sformułowany. |
| 401 | Brak autoryzacji | Brak tokenu zabezpieczającego lub jest on nieprawidłowo sformułowany lub nieprawidłowy. |
| 403 | Dostęp zabroniony | Token zabezpieczający nie jest prawidłowy dla tej ścieżki i dla tej akcji. |
| 500 | Błąd wewnętrzny | Wystąpił problem w usłudze. |
| 503 | Nieprawidłowa brama | Nie można kierować żądania do żadnego odbiornika. |
| 504 | Limit czasu bramy | Żądanie zostało skierowane do odbiornika, ale odbiornik nie potwierdził potwierdzenia w wymaganym czasie. |