Protokol Azure Relay Hybrid Připojení ions
Azure Relay je jedním z klíčových pilířů schopností platformy Azure Service Bus. Nová funkce hybridních Připojení ionů služby Relay je bezpečný vývoj open-protocol založený na HTTP a WebSockets. Nahrazuje bývalou funkci služby BizTalk Services, která byla vytvořená na základě proprietárního základu protokolu. Integrace hybridních Připojení ionů do Aplikace Azure Services bude i nadále fungovat tak, jak je.
Hybridní Připojení iony umožňují obousměrnou komunikaci, odezvu na požadavky a binární stream a jednoduchý tok datagramu mezi dvěma síťovými aplikacemi. Obě strany můžou být za překladem adres (NAT) nebo branami firewall.
Tento článek popisuje interakce na straně klienta s předáváním hybridních Připojení ionů pro připojení klientů v rolích naslouchacího procesu a odesílatele. Popisuje také, jak naslouchací procesy přijímají nová připojení a požadavky.
Model interakce
Hybridní Připojení iony propojí dvě strany tím, že poskytují bod setkání v cloudu Azure, který strany mohou zjišťovat a připojovat se z pohledu své vlastní sítě. Bod setkání se v této a další dokumentaci, v rozhraních API a také na webu Azure Portal nazývá "Hybridní Připojení ion". Koncový bod služby Hybrid Připojení ions se označuje jako "služba" pro zbytek tohoto článku.
Služba umožňuje předávat připojení webových soketů a požadavky a odpovědi HTTP(S).
Model interakce se spoléhá na nomenklaturu vytvořenou mnoha dalšími síťovými rozhraními API. Existuje naslouchací proces, který nejprve označuje připravenost na zpracování příchozích připojení a následně je přijme při jejich příchodu. Na druhé straně se klient připojí k naslouchacímu procesu a očekává, že připojení bude přijato k navázání obousměrné komunikační cesty. "Připojení", "Listen" a "Accept" jsou stejné termíny, které najdete ve většině rozhraní API soketů.
Každý předávaný komunikační model má některou stranu, která provádí odchozí připojení ke koncovému bodu služby. Díky tomu je "naslouchací proces" také "klient" v hovorovém použití a může také způsobit další přetížení terminologie. Přesná terminologie používaná pro hybridní Připojení iony je následující:
Programy na obou stranách připojení se nazývají "klienti", protože jsou klienty služby. Klient, který čeká na připojení a přijímá připojení, je "naslouchací proces", nebo se říká, že je v roli naslouchacího procesu. Klient, který zahájí nové připojení k naslouchacímu procesu prostřednictvím služby, se nazývá "odesílatel", nebo je v roli odesílatele.
Interakce naslouchacího procesu
Naslouchací proces má pět interakcí se službou; Všechny podrobnosti o drátu jsou popsány dále v tomto článku v referenční části.
Zprávy Naslouchání, Přijetí a Vyžádání se přijímají ze služby. Operace Prodlužování a Ping se odesílají naslouchacím procesem.
Naslouchací zpráva
Chcete-li označit připravenost na službu, že naslouchací proces je připraven přijímat připojení, vytvoří odchozí připojení WebSocket. Handshake připojení nese název hybridního Připojení ion nakonfigurovaného pro obor názvů služby Relay a token zabezpečení, který u tohoto názvu uděluje právo "Listen".
Při přijetí protokolu WebSocket službou se registrace dokončí a zavedený webSocket se zachová jako "řídicí kanál" pro povolení všech následných interakcí. Služba umožňuje až 25 souběžných naslouchacích procesů pro jednu hybridní Připojení ion. Je třeba určit kvótu pro apphooky.
U hybridních Připojení ionů platí, že pokud existují dva nebo více aktivních naslouchacích procesů, jsou příchozí připojení vyvážená v náhodném pořadí. Spravedlivé rozdělení se snažíme s maximálním úsilím.
Přijmout zprávu
Když odesílatel otevře nové připojení ve službě, služba zvolí a upozorní jednoho z aktivních naslouchacích procesů v hybridním Připojení ionu. Toto oznámení se odešle naslouchacímu procesu přes otevřený řídicí kanál jako zpráva JSON. Zpráva obsahuje adresu URL koncového bodu WebSocket, ke kterému se musí naslouchací proces připojit pro přijetí připojení.
Adresa URL může a musí být použita přímo naslouchacím procesem bez další práce. Zakódované informace jsou platné pouze na krátkou dobu, a to v podstatě tak dlouho, dokud odesílatel bude ochotný počkat na vytvoření připojení na konci. Maximální hodnota, která se předpokládá, je 30 sekund. Adresu URL je možné použít pouze pro jeden úspěšný pokus o připojení. Jakmile se vytvoří připojení WebSocket s adresou URL rendezvous, veškeré další aktivity na tomto webSocketu se předávají odesílateli a odesílateli. K tomuto chování dochází bez zásahu nebo interpretace služby.
Žádost o zprávu
Kromě připojení WebSocket může naslouchací proces také přijímat rámce požadavků HTTP od odesílatele, pokud je tato funkce explicitně povolena v hybridním Připojení ionu.
Naslouchací procesy, které se připojují k hybridním Připojení ionům s podporou PROTOKOLU HTTP, musí toto gesto zpracovatrequest. Naslouchací proces, který nezpracuje request , a proto způsobí opakované chyby časového limitu při připojování, může služba v budoucnu zablokovat.
Metadata hlavičky rámce HTTP se překládají do formátu JSON pro jednodušší zpracování architekturou naslouchacího procesu, protože knihovny parsování hlaviček HTTP jsou vzácné než analyzátory JSON. Metadata HTTP, která jsou relevantní jenom pro vztah mezi odesílatelem a bránou HTTP služby Relay, včetně autorizačních informací, se nepřeposílat. Těla požadavků HTTP se transparentně přenesou jako binární rámce WebSocket.
Naslouchací proces může reagovat na požadavky HTTP pomocí ekvivalentního gesta odpovědi.
Tok požadavku a odpovědi používá ve výchozím nastavení řídicí kanál, ale může být "upgradován" na odlišnou schůzku WebSocket, kdykoli je to potřeba. Jedinečná připojení WebSocket zlepšují propustnost pro každou konverzaci klientů, ale zatěžují naslouchací proces více připojeními, která je potřeba zpracovat, což nemusí být pro jednoduché klienty požadované.
V řídicím kanálu jsou tělo žádosti a odpovědi omezené na maximálně 64 kB. Metadata hlaviček HTTP jsou omezena na celkem 32 kB. Pokud požadavek nebo odpověď překročí tuto prahovou hodnotu, naslouchací proces musí upgradovat na rendezvous WebSocket pomocí gesta ekvivalentního zpracování přijmout.
U žádostí se služba rozhodne, jestli se mají směrovat žádosti přes řídicí kanál. To zahrnuje, ale nemusí být omezené na případy, kdy požadavek přesahuje 64 kB (hlavičky plus tělo) přímo, nebo pokud je požadavek odeslán s kódováním přenosu "blokovaným" a služba má důvod očekávat, že požadavek překročí 64 kB nebo čtení požadavku není okamžité. Pokud se služba rozhodne doručit žádost přes schůzku, předá pouze adresu setkání naslouchacímu procesu. Naslouchací proces pak musí vytvořit rendezvous WebSocket a služba okamžitě doručí úplné žádosti včetně těl přes rendezvous WebSocket. Odpověď MUSÍ také použít rendezvous WebSocket.
U žádostí, které přicházejí přes řídicí kanál, se naslouchací proces rozhodne, zda má odpovědět přes řídicí kanál nebo prostřednictvím setkání. Služba MUSÍ obsahovat adresu rendezvous s každou žádostí směrovanou přes řídicí kanál. Tato adresa je platná pouze pro upgrade z aktuálního požadavku.
Pokud se naslouchací proces rozhodne upgradovat, připojí se a okamžitě doručí odpověď přes zavedenou soketu rendezvous.
Jakmile se vytvoří redezvous WebSocket, naslouchací proces by ho měl udržovat pro další zpracování požadavků a odpovědí od stejného klienta. Služba bude udržovat protokol WebSocket tak dlouho, dokud se připojení soketu HTTPS s odesílatelem zachová a bude směrovat všechny následné požadavky od daného odesílatele přes udržovanou webSocket. Pokud se naslouchací proces rozhodne vypustit redezvous WebSocket ze své strany, služba také zahodí připojení k odesílateli bez ohledu na to, jestli už může probíhat následná žádost.
Operace prodloužení platnosti
Token zabezpečení, který se musí použít k registraci naslouchacího procesu a údržbě řídicího kanálu, může vypršet, když je naslouchací proces aktivní. Vypršení platnosti tokenu nemá vliv na probíhající připojení, ale způsobí, že řídicí kanál se službou v okamžiku vypršení platnosti nebo brzy po vypršení platnosti zahodí. Operace prodlužování je zpráva JSON, že naslouchací proces může odeslat a nahradit token přidružený k řídicímu kanálu, aby bylo možné řídicí kanál udržovat po delší období.
Operace ping
Pokud řídicí kanál zůstane dlouho nečinný, zprostředkovatelé na cestě, jako jsou nástroje pro vyrovnávání zatížení nebo překlad adres (NAT), můžou připojení TCP hodit. Operace ping tomu zabrání odesláním malého množství dat v kanálu, který všem na síťové trase připomíná, že připojení je živé, a slouží také jako "živý" test pro naslouchací proces. Pokud příkaz ping selže, měl by být řídicí kanál považován za nepoužitelný a naslouchací proces by se měl znovu připojit.
Interakce odesílatele
Odesílatel má se službou dvě interakce: připojuje webový soket nebo odesílá požadavky prostřednictvím protokolu HTTPS. Požadavky nelze odeslat prostřednictvím webového soketu z role odesílatele.
operace Připojení
Operace "connect" otevře ve službě webSocket a poskytne název hybridního Připojení ionu a (volitelně, ale ve výchozím nastavení to vyžaduje) token zabezpečení, který v řetězci dotazu uděluje oprávnění Odeslat. Služba pak interaguje s naslouchacím procesem způsobem popsaným výše a naslouchací proces vytvoří spojení setkání, které je připojeno k tomuto webSocketu. Po přijetí protokolu WebSocket jsou všechny další interakce s webSocket s připojeným naslouchacím procesem.
Operace požadavku
U hybridních Připojení ionů, pro které byla funkce povolena, může odesílatel odesílat do značné míry neomezené požadavky HTTP na naslouchací procesy.
S výjimkou přístupového tokenu relay, který je buď vložený do řetězce dotazu nebo v hlavičce HTTP požadavku, je Relay plně transparentní pro všechny operace HTTP na adrese relay a všechny přípony cesty adresy Relay, takže naslouchací proces plně pod kontrolou kompletní autorizace a dokonce i funkce rozšíření HTTP, jako je CORS.
Autorizace odesílatele pomocí koncového bodu relay je ve výchozím nastavení zapnutá, ale je volitelná. Vlastník hybridní Připojení ion se může rozhodnout povolit anonymní odesílatele. Služba zachytí, zkontroluje a odebere autorizační informace následujícím způsobem:
- Pokud řetězec dotazu obsahuje
sb-hc-tokenvýraz, výraz se vždy odstraní z řetězce dotazu. Vyhodnotí se, pokud je zapnutá autorizace relay. - Pokud hlavičky požadavku obsahují hlavičku
ServiceBusAuthorization, výraz záhlaví bude vždy odebrán z kolekce hlaviček. Vyhodnotí se, pokud je zapnutá autorizace relay. - Pouze pokud je zapnutá autorizace relay a hlavičky požadavku obsahují hlavičku
Authorizationa žádná z předchozích výrazů není k dispozici, hlavička se vyhodnotí a odstraní. Jinak se vždyAuthorizationpředává tak, jak je.
Pokud neexistuje žádný aktivní naslouchací proces, služba vrátí kód chyby 502 Chybná brána. Pokud se služba nezvládá žádost, služba vrátí po 60 sekundách 504 vypršení časového limitu brány.
Souhrn interakce
Výsledkem tohoto modelu interakce je, že klient odesílatele přichází z metody handshake s "čistým" webSocket, který je připojen k naslouchacímu procesu a který nepotřebuje žádné další prevence ani přípravu. Tento model umožňuje prakticky jakoukoli existující implementaci klienta WebSocket snadno využít služby Hybrid Připojení ions tak, že do své klientské vrstvy WebSocket zadá správně vytvořenou adresu URL.
Redezvous connection WebSocket, který naslouchací proces získá prostřednictvím akceptační interakce, je také čistý a lze jej předat jakékoli stávající implementaci serveru WebSocket s některými minimálními extra abstrakcemi, které rozlišují mezi operacemi "accept" v naslouchacích procesech jejich architektury a hybridními Připojení iony vzdálené operace "přijmout".
Model požadavků a odpovědí HTTP dává odesílateli z velké části neomezenou plochu protokolu HTTP s volitelnou autorizační vrstvou. Naslouchací proces získá předem analyzovaný oddíl hlavičky požadavku HTTP, který se dá převést zpět na podřízený požadavek HTTP nebo zpracovat tak, jak je, s binárními snímky, které obsahují tělo HTTP. Odpovědi používají stejný formát. Interakce s méně než 64 kB požadavku a textu odpovědi je možné zpracovat prostřednictvím jednoho webového soketu, který je sdílený pro všechny odesílatele. Větší požadavky a odpovědi je možné zpracovat pomocí modelu rendezvous.
Referenční informace k protokolu
Tato část popisuje podrobnosti o interakcích protokolu popsaných dříve.
Všechna připojení WebSocket se provádí na portu 443 jako upgrade z HTTPS 1.1, který je často abstrahován některými rozhraními WebSocket nebo rozhraním API. Popis, který zde je, je zachován neutrální implementace, aniž by navrhoval konkrétní architekturu.
Protokol naslouchacího procesu
Protokol naslouchacího procesu se skládá ze dvou gest připojení a tří operací se zprávami.
Připojení kanálu řízení naslouchacího procesu
Řídicí kanál se otevře s vytvořením připojení WebSocket k:
wss://{namespace-address}/$hc/{path}?sb-hc-action=...[&sb-hc-id=...]&sb-hc-token=...
Jedná se namespace-address o plně kvalifikovaný název domény oboru názvů Služby Azure Relay, který hostuje hybridní Připojení ion, obvykle formuláře {myname}.servicebus.windows.net.
Možnosti parametru řetězce dotazu jsou následující.
| Parametr | Požadováno | Popis |
|---|---|---|
sb-hc-action |
Ano | Pro roli naslouchacího procesu musí být parametr sb-hc-action=listen |
{path} |
Ano | Cesta oboru názvů zakódovaná adresou URL předkonfigurovaného hybridního Připojení ion pro registraci tohoto naslouchacího procesu. Tento výraz se připojí k části s pevnou $hc/ cestou. |
sb-hc-token |
Ano* | Naslouchací proces musí poskytnout platný sdílený přístupový token služby Service Bus kódovaný adresou URL pro obor názvů nebo hybridní Připojení ion, který uděluje právo naslouchat. |
sb-hc-id |
No | Toto volitelné ID zadané klientem umožňuje komplexní diagnostické trasování. |
Pokud se připojení WebSocket nezdaří kvůli nezaregistrované cestě hybridního Připojení nebo kvůli neplatnému nebo chybějícímu tokenu nebo jiné chybě, poskytne se zpětná vazba k chybě pomocí běžného modelu zpětné vazby stavu HTTP 1.1. Popis stavu obsahuje ID sledování chyb, které je možné sdělit podpora Azure pracovníkům:
| Kód | Chyba | Popis |
|---|---|---|
| 404 | Nenalezeno | Cesta hybridního Připojení ionu je neplatná nebo je poškozená základní adresa URL. |
| 401 | Neautorizováno | Token zabezpečení chybí nebo je poškozený nebo neplatný. |
| 403 | Zakázáno | Token zabezpečení není pro tuto cestu pro tuto akci platný. |
| 500 | Vnitřní chyba | Ve službě se něco nepovedlo. |
Pokud je připojení WebSocket záměrně vypnuto službou po jeho počátečním nastavení, je důvod, proč k tomu slouží odpovídající kód chyby protokolu WebSocket, spolu s popisnou chybovou zprávou, která obsahuje také ID sledování. Služba nevypíná řídicí kanál, aniž by došlo k chybovému stavu. Veškeré čisté vypnutí je řízeno klientem.
| Stav WS | Popis |
|---|---|
| 1001 | Cesta hybridního Připojení ionu byla odstraněna nebo zakázána. |
| 1008 | Platnost tokenu zabezpečení vypršela, proto je porušena zásada autorizace. |
| 1011 | Ve službě se něco nepovedlo. |
Přijmout metodu handshake
Oznámení "přijmout" odešle služba naslouchacímu procesu přes dříve vytvořený řídicí kanál jako zprávu JSON v textovém rámečku WebSocket. Na tuto zprávu neexistuje odpověď.
Zpráva obsahuje objekt JSON s názvem "accept", který v tuto chvíli definuje následující vlastnosti:
- address – řetězec adresy URL, který se má použít k navázání protokolu WebSocket do služby pro přijetí příchozího připojení.
- ID – jedinečný identifikátor pro toto připojení. Pokud id zadal klient odesílatele, jedná se o zadanou hodnotu odesílatele, jinak se jedná o hodnotu vygenerovanou systémem.
- connectHeaders – všechny hlavičky HTTP, které odesílatel zadal do koncového bodu přenosu, včetně sec-WebSocket-Protocol a hlavičky Sec-WebSocket-Extensions.
{
"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" : "..."
}
}
}
Adresa URL zadaná ve zprávě JSON slouží naslouchacímu procesu k vytvoření protokolu WebSocket pro přijetí nebo odmítnutí soketu odesílatele.
Přijetí soketu
Pokud ho chcete přijmout, naslouchací proces vytvoří připojení WebSocket k zadané adrese.
Pokud zpráva "accept" obsahuje hlavičku Sec-WebSocket-Protocol , očekává se, že naslouchací proces přijme pouze WebSocket, pokud podporuje tento protokol. Kromě toho nastaví hlavičku při vytvoření protokolu WebSocket.
Totéž platí pro Sec-WebSocket-Extensions záhlaví. Pokud architektura podporuje rozšíření, měla by hlavičku nastavit na odpověď na straně serveru požadované Sec-WebSocket-Extensions metody handshake pro rozšíření.
Adresa URL musí být použita tak, jak je určena k vytvoření soketu accept, ale obsahuje následující parametry:
| Parametr | Požadováno | Popis |
|---|---|---|
sb-hc-action |
Ano | Pro přijetí soketu musí být parametr sb-hc-action=accept |
{path} |
Ano | (viz následující odstavec) |
sb-hc-id |
No | Viz předchozí popis ID. |
{path}je cesta oboru názvů zakódovaná adresou URL předkonfigurovaného hybridního Připojení ionu, na kterém se má tento naslouchací proces zaregistrovat. Tento výraz se připojí k části s pevnou $hc/ cestou.
Výraz path může být rozšířen příponou a výrazem řetězce dotazu, který následuje za registrovaným názvem za oddělovačem lomítka.
Tento parametr umožňuje klientovi odesílatele předat argumenty odeslání přijímajícímu naslouchacímu procesu, pokud není možné zahrnout hlavičky HTTP. Očekávání spočívá v tom, že architektura naslouchacího procesu parsuje část s pevnou cestou a registrovaný název z cesty a vytvoří zbytek, pravděpodobně bez jakýchkoli argumentů řetězce dotazu s předponou sb-, dostupnou pro aplikaci pro rozhodování, jestli se má připojení přijmout.
Další informace najdete v následující části Protokol odesílatele.
Pokud dojde k chybě, může služba odpovědět následujícím způsobem:
| Kód | Chyba | Popis |
|---|---|---|
| 403 | Zakázáno | Adresa URL není platná. |
| 500 | Vnitřní chyba | Ve službě se něco nepovedlo |
Po navázání připojení server webSocket vypne, když se odesílatel WebSocket vypne nebo má následující stav:
| Stav WS | Popis |
|---|---|
| 1001 | Klient odesílatele vypne připojení. |
| 1001 | Cesta hybridního Připojení ionu byla odstraněna nebo zakázána. |
| 1008 | Platnost tokenu zabezpečení vypršela, proto je porušena zásada autorizace. |
| 1011 | Ve službě se něco nepovedlo. |
Odmítnutí soketu
Odmítnutí soketu po kontrole accept zprávy vyžaduje podobné metody handshake, aby stavový kód a popis stavu komunikující s důvodem zamítnutí mohl proudit zpět odesílateli.
Volba návrhu protokolu zde je použít metodu handshake protokolu WebSocket (která je navržená tak, aby skončila v definovaném chybovém stavu), aby implementace klienta naslouchacího procesu mohly nadále spoléhat na klienta Protokolu WebSocket a nemusí využívat další holý klient HTTP.
Pokud chcete soket odmítnout, klient vezme identifikátor URI adresy ze accept zprávy a připojí k němu dva parametry řetězce dotazu, a to následujícím způsobem:
| Param | Požadováno | Popis |
|---|---|---|
| sb-hc-statusCode | Ano | Číselný stavový kód HTTP |
| sb-hc-statusDescription | Ano | Lidský čitelný důvod zamítnutí. |
Výsledný identifikátor URI se pak použije k navázání připojení WebSocket.
Při správném dokončování tento metodu handshake záměrně selže s kódem chyby HTTP 410, protože nebyl vytvořen žádný protokol WebSocket. Pokud se něco nepovede, následující kódy popisují chybu:
| Kód | Chyba | Popis |
|---|---|---|
| 403 | Zakázáno | Adresa URL není platná. |
| 500 | Vnitřní chyba | Ve službě se něco nepovedlo. |
Žádost o zprávu
Zpráva request je odeslána službou naslouchacímu procesu přes řídicí kanál. Stejná zpráva je také odeslána přes rendezvous WebSocket po vytvoření.
Skládá request se ze dvou částí: záhlaví a binárních rámečeků textu.
Pokud neexistuje žádný text, vynechá se snímky těla. Logická body vlastnost označuje, zda je tělo přítomno ve zprávě požadavku.
U požadavku s textem požadavku může struktura vypadat takto:
----- Web Socket text frame ----
{
"request" :
{
"body" : true,
...
}
}
----- Web Socket binary frame ----
FEFEFEFEFEFEFEFEFEFEF...
----- Web Socket binary frame ----
FEFEFEFEFEFEFEFEFEFEF...
----- Web Socket binary frame -FIN
FEFEFEFEFEFEFEFEFEFEF...
----------------------------------
Naslouchací proces musí zpracovat příjem textu požadavku rozděleného mezi více binárních rámců (viz fragmenty protokolu WebSocket). Požadavek končí, když byl přijat binární rámec s nastaveným příznakem FIN.
Pro požadavek bez textu je jenom jeden textový rámeček.
----- Web Socket text frame ----
{
"request" :
{
"body" : false,
...
}
}
----------------------------------
Obsah JSON je request následující:
address – řetězec identifikátoru URI. Jedná se o adresu rendezvous, která se má použít pro tuto žádost. Pokud je příchozí požadavek větší než 64 kB, zbývající část této zprávy zůstane prázdná a klient musí zahájit metodu handshake schůzky odpovídající
acceptníže popsané operaci. Služba pak umístí dokončenírequestna vytvořený webový soket. Pokud lze očekávat, že odpověď překročí 64 kB, naslouchací proces musí také zahájit metodu handshake schůzky a pak přenést odpověď přes zavedený webový soket.id – řetězec. Jedinečný identifikátor pro tento požadavek.
requestHeaders – tento objekt obsahuje všechny hlavičky HTTP zadané do koncového bodu odesílatelem, s výjimkou autorizačních informací, jak je vysvětleno výše, a hlavičky, které se výhradně vztahují k připojení k bráně. Konkrétně jsou všechny hlavičky definované nebo vyhrazené v RFC7230 s výjimkou
Via, jsou vyjmuty a nepřesílané:Connection(RFC7230 oddíl 6.1)Content-Length(RFC7230 oddíl 3.3.2)Host(RFC7230 oddíl 5.4)TE(RFC7230 oddíl 4.3)Trailer(RFC7230 oddíl 4.4)Transfer-Encoding(RFC7230 oddíl 3.3.1)Upgrade(RFC7230 oddíl 6.7)Close(RFC7230 oddíl 8.1)
requestTarget – řetězec. Tato vlastnost obsahuje požadavek "Request Target" (RFC7230 oddíl 5.3). Obsahuje část řetězce dotazu, která se odstraní z parametrů s předponou ALL
sb-hc-.metoda – řetězec. Toto je metoda požadavku podle RFC7231 oddílu 4. Metoda
CONNECTNESMÍ být použita.body – boolean. Určuje, zda následuje jeden nebo více binárních tělových rámců.
{
"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
}
}
Reagování na žádosti
Příjemce musí odpovědět. Opakované selhání reakce na požadavky při zachování připojení může vést k zablokování naslouchacího procesu.
Odpovědi můžou být odeslány v libovolném pořadí, ale každý požadavek musí být zodpovězen do 60 sekund nebo se doručení ohlásí jako neúspěšné. 60sekundový termín se počítá, dokud response služba nepředpočítá rámec. Probíhající odpověď s více binárními snímky se nemůže stát nečinnou déle než 60 sekund nebo se ukončí.
Pokud je požadavek přijat přes řídicí kanál, musí být odpověď odeslána na řídicí kanál, ze kterého byl požadavek přijat, nebo musí být odeslán přes kanál rendezvous.
Odpověď je objekt JSON s názvem "response". Pravidla pro zpracování obsahu textu jsou přesně stejná jako u request zprávy a na body základě vlastnosti.
- requestId – řetězec. POŽADOVANÉ. Hodnota
idrequestvlastnosti zprávy, na kterou se odpovídá. - statusCode – číslo. POŽADOVANÉ. číselný stavový kód HTTP, který označuje výsledek oznámení. Všechny stavové kódy RFC7231, oddíl 6 jsou povoleny, s výjimkou 502 Chybná brána a 504 "Časový limit brány".
- statusDescription – řetězec. VOLITELNÉ. Fráze důvodu stavového kódu HTTP na RFC7230, oddíl 3.1.2
- responseHeaders – hlavičky HTTP, které se mají nastavit v externí odpovědi HTTP.
Stejně jako u
requestRFC7230 definovaných hlaviček se nesmí používat. - body – boolean. Určuje, zda binární body rámce následují.
----- 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" }
----------------------------------
Reagování prostřednictvím setkání
U odpovědí, které překračují 64 kB, musí být odpověď doručena přes redezvous zásuvku. Pokud požadavek překročí 64 kB a request obsahuje pouze pole adresy, musí být vytvořen soket rendezvous k získání request. Jakmile se vytvoří soket rendezvous, odpovědi na příslušného klienta a následné požadavky z tohoto klienta musí být doručeny přes soket rendezvous, zatímco se zachová.
Adresa address URL musí request být použita tak, jak je určena k vytvoření soketu rendezvous, ale obsahuje následující parametry:
| Parametr | Požadováno | Popis |
|---|---|---|
sb-hc-action |
Ano | Pro přijetí soketu musí být parametr sb-hc-action=request |
Pokud dojde k chybě, může služba odpovědět následujícím způsobem:
| Kód | Chyba | Popis |
|---|---|---|
| 400 | Neplatný požadavek | Nerozpoznaná akce nebo neplatná adresa URL |
| 403 | Zakázáno | Platnost adresy URL vypršela. |
| 500 | Vnitřní chyba | Ve službě se něco nepovedlo |
Po navázání připojení server vypne protokol WebSocket, když se soket HTTP klienta vypne nebo má následující stav:
| Stav WS | Popis |
|---|---|
| 1001 | Klient odesílatele vypne připojení. |
| 1001 | Cesta hybridního Připojení ionu byla odstraněna nebo zakázána. |
| 1008 | Platnost tokenu zabezpečení vypršela, proto je porušena zásada autorizace. |
| 1011 | Ve službě se něco nepovedlo. |
Obnovení tokenu naslouchacího procesu
Když vyprší platnost tokenu naslouchacího procesu, může ho nahradit odesláním zprávy textového rámce službě přes vytvořený řídicí kanál. Zpráva obsahuje objekt JSON s názvem renewToken, který v tuto chvíli definuje následující vlastnost:
- token – platný přístupový token služby Service Bus kódovaný adresou URL pro obor názvů nebo hybridní Připojení ion, který uděluje právo naslouchat.
{
"renewToken": {
"token":
"SharedAccessSignature sr=http%3a%2f%2fcontoso.servicebus.windows.net%2fhyco%2f&sig=XXXXXXXXXX%3d&se=1471633754&skn=SasKeyName"
}
}
Pokud se ověření tokenu nezdaří, přístup se odepře a cloudová služba zavře webSocket řídicího kanálu s chybou. V opačném případě neexistuje odpověď.
| Stav WS | Popis |
|---|---|
| 1008 | Platnost tokenu zabezpečení vypršela, proto je porušena zásada autorizace. |
Protokol Pro připojení k webovému soketu
Protokol odesílatele je efektivně identický se způsobem vytvoření naslouchacího procesu. Cílem je maximální transparentnost pro kompletní webSocket. Adresa, ke které se chcete připojit, je stejná jako pro naslouchací proces, ale akce se liší a token potřebuje jiné oprávnění:
wss://{namespace-address}/$hc/{path}?sb-hc-action=...&sb-hc-id=...&sb-hc-token=...
Adresa oboru názvů je plně kvalifikovaný název domény oboru názvů Služby Azure Relay, který hostuje hybridní Připojení ion, obvykle formuláře {myname}.servicebus.windows.net.
Požadavek může obsahovat libovolná nadbytečná hlavička HTTP, včetně hlaviček definovaných aplikací. Tok všech zadaných hlaviček do naslouchacího procesu a lze jej najít v connectHeader objektu řídicí zprávy přijmout .
Možnosti parametru řetězce dotazu jsou následující:
| Param | Povinné? | Popis |
|---|---|---|
sb-hc-action |
Ano | Pro roli odesílatele musí být sb-hc-action=connectparametr . |
{path} |
Ano | (viz následující odstavec) |
sb-hc-token |
Ano* | Naslouchací proces musí poskytnout platný sdílený přístupový token služby Service Bus kódovaný adresou URL pro obor názvů nebo hybridní Připojení ion, který uděluje právo odeslat. |
sb-hc-id |
No | Volitelné ID, které umožňuje komplexní diagnostické trasování a je zpřístupněno naslouchacímu procesu během metody handshake pro příjem. |
Je to {path} cesta oboru názvů zakódovaná adresou URL předkonfigurovaného hybridního Připojení, na kterém se má tento naslouchací proces zaregistrovat. Výraz path lze rozšířit příponou a výrazem řetězce dotazu, který bude dále komunikovat. Pokud je v cestě hycozaregistrovaná hybridní Připojení ion , path může hyco/suffix?param=value&... za výrazem následovat parametry řetězce dotazu definované zde. Úplný výraz pak může být následující:
wss://{namespace-address}/$hc/hyco/suffix?param=value&sb-hc-action=...[&sb-hc-id=...&]sb-hc-token=...
Výraz path se předává naslouchacímu procesu v identifikátoru URI adresy obsaženém v řídicí zprávě "accept".
Pokud připojení WebSocket selže kvůli nezaregistrované cestě hybridního Připojení, neplatnému nebo chybějícímu tokenu nebo jiné chybě, je zpětná vazba k chybě poskytována pomocí běžného modelu zpětné vazby stavu HTTP 1.1. Popis stavu obsahuje ID sledování chyb, které lze sdělit podpora Azure pracovníkům:
| Kód | Chyba | Popis |
|---|---|---|
| 404 | Nenalezeno | Cesta hybridního Připojení ionu je neplatná nebo je poškozená základní adresa URL. |
| 401 | Neautorizováno | Token zabezpečení chybí nebo je poškozený nebo neplatný. |
| 403 | Zakázáno | Token zabezpečení není pro tuto cestu a pro tuto akci platný. |
| 500 | Vnitřní chyba | Ve službě se něco nepovedlo. |
Pokud je připojení WebSocket záměrně vypnuto službou po jeho počátečním nastavení, je důvod, proč to udělat, prostřednictvím příslušného kódu chyby protokolu WebSocket spolu s popisnou chybovou zprávou, která obsahuje také ID sledování.
| Stav WS | Popis |
|---|---|
| 1000 | Naslouchací proces vypne soket. |
| 1001 | Cesta hybridního Připojení ionu byla odstraněna nebo zakázána. |
| 1008 | Platnost tokenu zabezpečení vypršela, takže dojde k porušení zásad autorizace. |
| 1011 | Ve službě se něco nepovedlo. |
Protokol požadavku HTTP
Protokol požadavku HTTP umožňuje libovolné požadavky HTTP s výjimkou upgradů protokolu. Požadavky HTTP odkazují na běžnou adresu modulu runtime entity bez $hc oprava, která se používá pro klienty WebSocket hybridních připojení.
https://{namespace-address}/{path}?sb-hc-token=...
Adresa oboru názvů je plně kvalifikovaný název domény oboru názvů Služby Azure Relay, který hostuje hybridní Připojení ion, obvykle formuláře {myname}.servicebus.windows.net.
Požadavek může obsahovat libovolná nadbytečná hlavička HTTP, včetně hlaviček definovaných aplikací. Všechny zadané hlavičky s výjimkou těch, které jsou přímo definované v toku RFC7230 (viz Zpráva požadavku) do naslouchacího procesu a lze je najít v requestHeader objektu zprávy požadavku .
Možnosti parametru řetězce dotazu jsou následující:
| Param | Povinné? | Popis |
|---|---|---|
sb-hc-token |
Ano* | Naslouchací proces musí poskytnout platný sdílený přístupový token služby Service Bus kódovaný adresou URL pro obor názvů nebo hybridní Připojení ion, který uděluje právo odeslat. |
Token lze také přenášet v ServiceBusAuthorization hlavičce http.Authorization Token je možné vynechat, pokud je hybridní Připojení ion nakonfigurovaný tak, aby povoloval anonymní požadavky.
Vzhledem k tomu, že služba efektivně funguje jako proxy server, i když ne jako skutečný proxy server HTTP, přidá Via hlavičku nebo přidá poznámky stávající Via hlavičky vyhovující RFC7230 oddílu 5.7.1.
Služba přidá název hostitele oboru názvů Relay do Via.
| Kód | Message | Popis |
|---|---|---|
| 200 | OK | Požadavek zpracovává alespoň jeden naslouchací proces. |
| 202 | Akceptováno | Požadavek přijal alespoň jeden naslouchací proces. |
Pokud dojde k chybě, může služba odpovědět následujícím způsobem. Jestli odpověď pochází ze služby nebo z naslouchacího procesu, je možné identifikovat prostřednictvím přítomnosti hlavičky Via . Pokud je záhlaví k dispozici, odpověď pochází z naslouchacího procesu.
| Kód | Chyba | Popis |
|---|---|---|
| 404 | Nenalezeno | Cesta hybridního Připojení ionu je neplatná nebo je poškozená základní adresa URL. |
| 401 | Neautorizováno | Token zabezpečení chybí nebo je poškozený nebo neplatný. |
| 403 | Zakázáno | Token zabezpečení není pro tuto cestu a pro tuto akci platný. |
| 500 | Vnitřní chyba | Ve službě se něco nepovedlo. |
| 503 | Chybná brána | Požadavek nelze směrovat do žádného naslouchacího procesu. |
| 504 | Časový limit brány | Požadavek byl směrován do naslouchacího procesu, ale naslouchací proces nepotvrdil potvrzení v požadovaném čase. |