Azure Relay Hybrid Anslut ions-protokoll
Azure Relay är en av grundpelarna för funktioner i Azure Service Bus-plattformen. Den nya Hybrid Anslut ions-funktionen för Relay är en säker utveckling med öppet protokoll baserat på HTTP och WebSockets. Den ersätter den tidigare, lika namngivna BizTalk Services-funktionen som byggdes på en patentskyddad protokollgrund. Integreringen av Hybrid Anslut ions i Azure App Services fortsätter att fungera som den är.
Hybrid-Anslut ions möjliggör dubbelriktad, begärandesvar och binär dataströmkommunikation och enkelt datagramflöde mellan två nätverksanslutna program. Antingen eller båda parter kan ligga bakom NAT eller brandväggar.
Den här artikeln beskriver interaktionen på klientsidan med Hybrid Anslut ions-reläet för att ansluta klienter i lyssnar- och avsändarroller. Den beskriver också hur lyssnare accepterar nya anslutningar och begäranden.
Interaktionsmodell
Hybrid Anslut ions-reläet ansluter två parter genom att tillhandahålla en mötesplats i Azure-molnet som parterna kan identifiera och ansluta till från sitt eget nätverks perspektiv. Rendezvous-punkten kallas "Hybrid Anslut ion" i den här och annan dokumentation, i API:erna och även i Azure-portalen. Tjänstslutpunkten Hybrid Anslut ions kallas "tjänsten" för resten av den här artikeln.
Tjänsten gör det möjligt att vidarebefordra Web Socket-anslutningar och HTTP(S) begäranden och svar.
Interaktionsmodellen lutar sig mot nomenklaturen som upprättats av många andra nätverks-API:er. Det finns en lyssnare som först anger beredskap för att hantera inkommande anslutningar och därefter accepterar dem när de anländer. Å andra sidan ansluter en klient till lyssnaren och förväntar sig att anslutningen godkänns för att upprätta en dubbelriktad kommunikationsväg. "Anslut", "Lyssna" och "Acceptera" är samma termer som du hittar i de flesta socket-API:er.
Alla vidarebefordrade kommunikationsmodeller har någon av parterna som upprättar utgående anslutningar mot en tjänstslutpunkt. Detta gör "lyssnaren" också till en "klient" i vardaglig användning och kan också orsaka andra terminologiöverlagringar. Den exakta terminologi som därför används för Hybrid Anslut ions är följande:
Programmen på båda sidor av en anslutning kallas "klienter", eftersom de är klienter till tjänsten. Klienten som väntar på och accepterar anslutningar är "lyssnaren" eller sägs vara i "lyssnarrollen". Klienten som initierar en ny anslutning till en lyssnare via tjänsten kallas "avsändaren" eller är i "avsändarrollen".
Lyssnarinteraktioner
Lyssnaren har fem interaktioner med tjänsten. all trådinformation beskrivs senare i den här artikeln i referensavsnittet.
Meddelandena Lyssna, Acceptera och Begär tas emot från tjänsten. Åtgärderna Förnya och Pinga skickas av lyssnaren.
Lyssna meddelande
För att ange beredskap för tjänsten att en lyssnare är redo att acceptera anslutningar skapar den en utgående WebSocket-anslutning. Anslutningshandskakningen bär namnet på en Hybrid-Anslut ion som konfigurerats i Relay-namnområdet och en säkerhetstoken som ger rättigheten "Lyssna" på det namnet.
När WebSocket accepteras av tjänsten är registreringen klar och den etablerade WebSocket hålls vid liv som "kontrollkanal" för att aktivera alla efterföljande interaktioner. Tjänsten tillåter upp till 25 samtidiga lyssnare för en Hybrid Anslut ion. Kvoten för AppHooks ska fastställas.
För Hybrid Anslut ions, om det finns två eller flera aktiva lyssnare, balanseras inkommande anslutningar över dem i slumpmässig ordning. Rättvis distribution görs med bästa möjliga ansträngning.
Acceptera meddelande
När en avsändare öppnar en ny anslutning för tjänsten väljer och meddelar tjänsten en av de aktiva lyssnarna i Hybrid Anslut ion. Det här meddelandet skickas till lyssnaren via den öppna kontrollkanalen som ett JSON-meddelande. Meddelandet innehåller URL:en för den WebSocket-slutpunkt som lyssnaren måste ansluta till för att acceptera anslutningen.
URL:en kan och måste användas direkt av lyssnaren utan extra arbete. Den kodade informationen är endast giltig under en kort tidsperiod, i princip så länge avsändaren är villig att vänta tills anslutningen upprättas från slutpunkt till slutpunkt. Maxgränsen är 30 sekunder. URL:en kan bara användas för ett lyckat anslutningsförsök. Så snart WebSocket-anslutningen med rendezvous-URL:en har upprättats vidarebefordras all ytterligare aktivitet på denna WebSocket från och till avsändaren. Det här beteendet inträffar utan någon åtgärd eller tolkning av tjänsten.
Begärandemeddelande
Förutom WebSocket-anslutningar kan lyssnaren även ta emot HTTP-begäranderamar från en avsändare, om den här funktionen uttryckligen är aktiverad på Hybrid Anslut ion.
Lyssnare som ansluter till Hybrid Anslut ions med HTTP-stöd MÅSTE hantera gestenrequest. En lyssnare som inte hanterar request och därför orsakar upprepade timeout-fel när den är ansluten kan blockeras av tjänsten i framtiden.
METADATA för HTTP-ramrubrik översätts till JSON för enklare hantering av lyssnarramverket, även för att HTTP-rubrikparsingbibliotek är ovanligare än JSON-parsare. HTTP-metadata som endast är relevanta för relationen mellan avsändaren och Relay HTTP-gatewayen, inklusive auktoriseringsinformation, vidarebefordras inte. HTTP-begärandeorgan överförs transparent som binära WebSocket-ramar.
Lyssnaren kan svara på HTTP-begäranden med en motsvarande svarsgest.
Begäran/svar-flödet använder kontrollkanalen som standard, men kan "uppgraderas" till en distinkt rendezvous WebSocket när det behövs. Distinkta WebSocket-anslutningar förbättrar dataflödet för varje klientkonversation, men de belastar lyssnaren med fler anslutningar som behöver hanteras, vilket kanske inte är önskvärt för enkla klienter.
På kontrollkanalen är begärande- och svarsorganen begränsade till högst 64 kB i storlek. HTTP-huvudmetadata är begränsade till totalt 32 kB. Om antingen begäran eller svaret överskrider det tröskelvärdet måste lyssnaren uppgradera till en rendezvous WebSocket med en gest som motsvarar hanteringen av Accept.
För begäranden bestämmer tjänsten om begäranden ska dirigeras via kontrollkanalen. Detta inkluderar, men får inte begränsas till fall där en begäran överskrider 64 kB (rubriker plus brödtext) direkt, eller om begäran skickas med "segmenterad" överföringskodning och tjänsten har anledning att förvänta sig att begäran överskrider 64 kB eller att läsa begäran inte är omedelbar. Om tjänsten väljer att leverera begäran via rendezvous skickar den bara rendezvous-adressen till lyssnaren. Lyssnaren måste sedan upprätta rendezvous WebSocket och tjänsten levererar omedelbart hela begäran inklusive organ över rendezvous WebSocket. Svaret MÅSTE också använda rendezvous WebSocket.
För begäranden som kommer över kontrollkanalen bestämmer lyssnaren om den ska svara över kontrollkanalen eller via rendezvous. Tjänsten MÅSTE innehålla en rendezvous-adress med varje begäran som dirigeras över kontrollkanalen. Den här adressen är endast giltig för uppgradering från den aktuella begäran.
Om lyssnaren väljer att uppgradera ansluter den och levererar snabbt svaret över den etablerade rendezvous-socketen.
När rendezvous WebSocket har upprättats bör lyssnaren underhålla den för ytterligare hantering av begäranden och svar från samma klient. Tjänsten underhåller WebSocket så länge HTTPS-socketanslutningen med avsändaren bevaras och dirigerar alla efterföljande begäranden från avsändaren över den underhållna WebSocket. Om lyssnaren väljer att släppa rendezvous WebSocket från sin sida, kommer tjänsten också att släppa anslutningen till avsändaren, oavsett om en efterföljande begäran redan pågår.
Förnya åtgärd
Säkerhetstoken som måste användas för att registrera lyssnaren och underhålla kontrollkanalen kan upphöra att gälla medan lyssnaren är aktiv. Förfallodatum för token påverkar inte pågående anslutningar, men det gör att kontrollkanalen tas bort av tjänsten vid eller strax efter förfallotillfället. Åtgärden "förnya" är ett JSON-meddelande som lyssnaren kan skicka för att ersätta token som är associerad med kontrollkanalen, så att kontrollkanalen kan underhållas under längre perioder.
Pingåtgärd
Om kontrollkanalen håller sig inaktiv under en längre tid kan mellanhänder på vägen, till exempel lastbalanserare eller NAT:er, släppa TCP-anslutningen. "Ping"-åtgärden undviker att genom att skicka en liten mängd data på kanalen som påminner alla på nätverksvägen om att anslutningen är avsedd att vara vid liv, och den fungerar också som ett "live"-test för lyssnaren. Om pingen misslyckas bör kontrollkanalen betraktas som oanvändbar och lyssnaren bör återansluta.
Avsändarinteraktion
Avsändaren har två interaktioner med tjänsten: den ansluter en webbsocket eller skickar begäranden via HTTPS. Begäranden kan inte skickas via en webbsocket från avsändarrollen.
Anslut åtgärd
Åtgärden "anslut" öppnar en WebSocket på tjänsten och anger namnet på Hybrid Anslut ion och (valfritt, men krävs som standard) en säkerhetstoken som ger "Skicka"-behörighet i frågesträngen. Tjänsten interagerar sedan med lyssnaren på det sätt som beskrevs tidigare, och lyssnaren skapar en rendezvous-anslutning som är ansluten till denna WebSocket. När WebSocket har accepterats sker alla ytterligare interaktioner på webSocket med en ansluten lyssnare.
Begärandeåtgärd
För Hybrid Anslut ions som funktionen har aktiverats för kan avsändaren skicka i stort sett obegränsade HTTP-begäranden till lyssnare.
Förutom en Relay-åtkomsttoken som antingen är inbäddad i frågesträngen eller i en HTTP-rubrik i begäran är Relay helt transparent för alla HTTP-åtgärder på relayadressen och alla suffix för relayadresssökvägen, vilket ger lyssnaren fullständig kontroll över auktorisering från slutpunkt till slutpunkt och till och med HTTP-tilläggsfunktioner som CORS.
Avsändarauktorisering med Relay-slutpunkten är aktiverad som standard, men är VALFRI. Ägaren av Hybrid Anslut ion kan välja att tillåta anonyma avsändare. Tjänsten kommer att fånga upp, inspektera och ta bort auktoriseringsinformation enligt följande:
- Om frågesträngen innehåller ett
sb-hc-tokenuttryck tas uttrycket ALLTID bort från frågesträngen. Det utvärderas om Relay-auktorisering är aktiverat. - Om begäranderubrikerna innehåller ett
ServiceBusAuthorizationhuvud tas huvuduttrycket ALLTID bort från rubriksamlingen. Det utvärderas om Relay-auktorisering är aktiverat. - Endast om Relay-auktorisering är aktiverat, och om begäranderubrikerna innehåller ett
Authorizationhuvud och inget av de tidigare uttrycken finns, utvärderas och tas rubriken bort. Annars skickasAuthorizationalltid som den är.
Om det inte finns någon aktiv lyssnare returnerar tjänsten felkoden 502 "Felaktig gateway". Om tjänsten inte verkar hantera begäran returnerar tjänsten 504 "Gateway Timeout" efter 60 sekunder.
Interaktionssammanfattning
Resultatet av den här interaktionsmodellen är att avsändarklienten kommer ut ur handskakningen med en "ren" WebSocket, som är ansluten till en lyssnare och som inte behöver några ytterligare ingresser eller förberedelser. Den här modellen gör att praktiskt taget alla befintliga WebSocket-klientimplementeringar enkelt kan dra nytta av Hybrid Anslut ions-tjänsten genom att tillhandahålla en korrekt konstruerad URL i webSocket-klientlagret.
WebSocket för rendezvous-anslutning som lyssnaren hämtar via acceptinteraktionen är också ren och kan överlämnas till alla befintliga WebSocket-serverimplementeringar med minimal extra abstraktion som skiljer mellan "acceptera"-åtgärder på ramverkets lokala nätverkslyssnare och Hybrid Anslut ions fjärråtgärder för "acceptera".
HTTP-begäran/svarsmodellen ger avsändaren en i stort sett obegränsad HTTP-protokollyta med ett valfritt auktoriseringslager. Lyssnaren hämtar ett förparserat avsnitt för HTTP-begäranderubriken som kan omvandlas tillbaka till en nedströms HTTP-begäran eller hanteras som den är, med binära ramar med HTTP-organ. Svar använder samma format. Interaktioner med mindre än 64 kB begärande- och svarstext kan hanteras via en enda webbsocket som delas för alla avsändare. Större begäranden och svar kan hanteras med hjälp av rendezvous-modellen.
Protokollreferens
I det här avsnittet beskrivs information om protokollinteraktionerna som beskrevs tidigare.
Alla WebSocket-anslutningar görs på port 443 som en uppgradering från HTTPS 1.1, som ofta abstraheras av något WebSocket-ramverk eller API. Beskrivningen här är neutral för implementeringen, utan att föreslå något specifikt ramverk.
Lyssnarprotokoll
Lyssnarprotokollet består av två anslutningsgester och tre meddelandeåtgärder.
Anslutning till lyssnarkontrollkanal
Kontrollkanalen öppnas med att skapa en WebSocket-anslutning till:
wss://{namespace-address}/$hc/{path}?sb-hc-action=...[&sb-hc-id=...]&sb-hc-token=...
namespace-address är det fullständigt kvalificerade domännamnet för Azure Relay-namnområdet som är värd för Hybrid Anslut ion, vanligtvis i formuläret {myname}.servicebus.windows.net.
Alternativen för frågesträngsparametern är följande.
| Parameter | Obligatoriskt | Beskrivning |
|---|---|---|
sb-hc-action |
Ja | För lyssnarrollen måste parametern vara sb-hc-action=listen |
{path} |
Ja | Sökvägen till DET URL-kodade namnområdet för den förkonfigurerade Hybrid-Anslut ion som lyssnaren ska registreras på. Det här uttrycket läggs till i den fasta $hc/ sökvägsdelen. |
sb-hc-token |
Ja* | Lyssnaren måste ange en giltig, URL-kodad Service Bus-token för delad åtkomst för namnområdet eller Hybrid Anslut ion som ger lyssnarbehörigheten. |
sb-hc-id |
Inga | Det här valfria ID:t som tillhandahålls av klienten möjliggör diagnostikspårning från slutpunkt till slutpunkt. |
Om WebSocket-anslutningen misslyckas på grund av att Hybrid Anslut ion-sökvägen inte har registrerats eller en ogiltig eller saknad token, eller något annat fel, tillhandahålls felfeedback med hjälp av den vanliga http 1.1-statusfeedbackmodellen. Statusbeskrivningen innehåller ett felspårnings-ID som kan kommuniceras med Azures supportpersonal:
| Kod | Fel | Description |
|---|---|---|
| 404 | Hittades inte | Hybrid-Anslut ionssökvägen är ogiltig eller så är bas-URL:en felaktig. |
| 401 | Behörighet saknas | Säkerhetstoken saknas, är felaktigt eller ogiltig. |
| 403 | Ej tillåtet | Säkerhetstoken är inte giltig för den här sökvägen för den här åtgärden. |
| 500 | Internt fel | Något gick fel i tjänsten. |
Om WebSocket-anslutningen avsiktligt stängs av av tjänsten efter att den ursprungligen konfigurerades, kommuniceras orsaken till detta med hjälp av en lämplig Felkod för WebSocket-protokollet tillsammans med ett beskrivande felmeddelande som även innehåller ett spårnings-ID. Tjänsten stänger inte av kontrollkanalen utan ett feltillstånd. En ren avstängning styrs av klienten.
| WS-status | Description |
|---|---|
| 1001 | Hybrid-Anslut ionssökvägen har tagits bort eller inaktiverats. |
| 1008 | Säkerhetstoken har upphört att gälla och därför överträds auktoriseringsprincipen. |
| 1011 | Något gick fel i tjänsten. |
Acceptera handskakning
Meddelandet "acceptera" skickas av tjänsten till lyssnaren via den tidigare etablerade kontrollkanalen som ett JSON-meddelande i en WebSocket-textram. Det finns inget svar på det här meddelandet.
Meddelandet innehåller ett JSON-objekt med namnet "accept", som definierar följande egenskaper just nu:
- address – URL-strängen som ska användas för att upprätta WebSocket till tjänsten för att acceptera en inkommande anslutning.
- id – den unika identifieraren för den här anslutningen. Om ID:t har angetts av avsändarklienten är det avsändarens angivna värde, annars är det ett systemgenererat värde.
- connectHeaders – alla HTTP-huvuden som har angetts till Relay-slutpunkten av avsändaren, som även innehåller huvudena Sec-WebSocket-Protocol och 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" : "..."
}
}
}
Adress-URL:en som anges i JSON-meddelandet används av lyssnaren för att upprätta WebSocket för att acceptera eller avvisa avsändarens socket.
Acceptera socketen
För att acceptera upprättar lyssnaren en WebSocket-anslutning till den angivna adressen.
Om meddelandet "acceptera" har ett Sec-WebSocket-Protocol huvud förväntas lyssnaren endast acceptera WebSocket om det stöder det protokollet. Dessutom anges rubriken när WebSocket upprättas.
Samma sak gäller för Sec-WebSocket-Extensions rubriken. Om ramverket stöder ett tillägg bör det ange huvudet till svaret på serversidan för den nödvändiga Sec-WebSocket-Extensions handskakningen för tillägget.
URL:en måste användas som den är för att upprätta accept-socketen, men innehåller följande parametrar:
| Parameter | Obligatoriskt | Beskrivning |
|---|---|---|
sb-hc-action |
Ja | För att acceptera en socket måste parametern vara sb-hc-action=accept |
{path} |
Ja | (se följande stycke) |
sb-hc-id |
Inga | Se föregående beskrivning av ID. |
{path}är den URL-kodade namnområdessökvägen för den förkonfigurerade Hybrid-Anslut ion som lyssnaren ska registreras på. Det här uttrycket läggs till i den fasta $hc/ sökvägsdelen.
Uttrycket path kan utökas med ett suffix och ett frågesträngsuttryck som följer det registrerade namnet efter ett avgränsande snedstreck.
Med den här parametern kan avsändarens klient skicka sändningsargument till den accepterande lyssnaren när det inte går att inkludera HTTP-huvuden. Förväntningen är att lyssnarramverket parsar ut den fasta sökvägsdelen och det registrerade namnet från sökvägen och gör resten, eventuellt utan några frågesträngsargument före , tillgängliga för programmet för att avgöra om anslutningen ska accepteras sb-.
Mer information finns i avsnittet "Sender Protocol".
Om det uppstår ett fel kan tjänsten svara på följande sätt:
| Kod | Fel | Description |
|---|---|---|
| 403 | Ej tillåtet | URL:en är inte giltig. |
| 500 | Internt fel | Något gick fel i tjänsten |
När anslutningen har upprättats stänger servern av WebSocket när avsändaren WebSocket stängs av eller med följande status:
| WS-status | Description |
|---|---|
| 1001 | Avsändarklienten stänger av anslutningen. |
| 1001 | Hybrid-Anslut ionssökvägen har tagits bort eller inaktiverats. |
| 1008 | Säkerhetstoken har upphört att gälla och därför överträds auktoriseringsprincipen. |
| 1011 | Något gick fel i tjänsten. |
Avvisa socketen
Om du avvisar socketen accept efter att du har inspekterat meddelandet krävs ett liknande handskakning så att statuskoden och statusbeskrivningen som kommunicerar orsaken till avvisningen kan flöda tillbaka till avsändaren.
Det här alternativet för protokolldesign är att använda en WebSocket-handskakning (som är utformad för att sluta i ett definierat feltillstånd) så att lyssnarklientimplementeringar kan fortsätta att förlita sig på en WebSocket-klient och inte behöver använda en extra, tom HTTP-klient.
Om du vill avvisa socketen tar klienten adress-URI:n från accept meddelandet och lägger till två frågesträngsparametrar i det, enligt följande:
| Param | Obligatoriskt | Beskrivning |
|---|---|---|
| sb-hc-statusCode | Ja | Numerisk HTTP-statuskod. |
| sb-hc-statusDescription | Ja | Mänsklig läsbar orsak till avslaget. |
Den resulterande URI:n används sedan för att upprätta en WebSocket-anslutning.
När handskakningen slutförs korrekt misslyckas den avsiktligt med HTTP-felkoden 410, eftersom ingen WebSocket har upprättats. Om något går fel beskriver följande koder felet:
| Kod | Fel | Description |
|---|---|---|
| 403 | Ej tillåtet | URL:en är inte giltig. |
| 500 | Internt fel | Något gick fel i tjänsten. |
Begärandemeddelande
Meddelandet request skickas av tjänsten till lyssnaren över kontrollkanalen. Samma meddelande skickas också via rendezvous WebSocket när det har upprättats.
Består request av två delar: en rubrik och binära brödtextramar.
Om det inte finns någon brödtext utelämnas brödtextramarna. Den booleska body egenskapen anger om en brödtext finns i begärandemeddelandet.
För en begäran med en begärandetext kan strukturen se ut så här:
----- Web Socket text frame ----
{
"request" :
{
"body" : true,
...
}
}
----- Web Socket binary frame ----
FEFEFEFEFEFEFEFEFEFEF...
----- Web Socket binary frame ----
FEFEFEFEFEFEFEFEFEFEF...
----- Web Socket binary frame -FIN
FEFEFEFEFEFEFEFEFEFEF...
----------------------------------
Lyssnaren MÅSTE hantera mottagandet av begärandetexten uppdelad över flera binära bildrutor (se WebSocket-fragment). Begäran avslutas när en binär ram med FIN-flagguppsättningen har tagits emot.
För en begäran utan brödtext finns det bara en textram.
----- Web Socket text frame ----
{
"request" :
{
"body" : false,
...
}
}
----------------------------------
JSON-innehållet för request är följande:
address – URI-sträng. Det är den rendezvous-adress som ska användas för den här begäran. Om den inkommande begäran är större än 64 kB lämnas resten av det här meddelandet tomt och klienten MÅSTE initiera ett rendezvous-handskakning motsvarande åtgärden
acceptsom beskrivs nedan. Tjänsten placerar sedan helarequestpå den etablerade webbsocketen. Om svaret kan förväntas överstiga 64 kB måste lyssnaren också initiera ett rendezvous-handskakning och sedan överföra svaret över den etablerade webbsocketen.id – sträng. Den unika identifieraren för den här begäran.
requestHeaders – det här objektet innehåller alla HTTP-huvuden som har angetts till slutpunkten av avsändaren, med undantag för auktoriseringsinformation enligt beskrivningen ovan, och rubriker som är strikt relaterade till anslutningen till gatewayen. Mer specifikt tas ALLA rubriker som definierats eller reserverats i RFC7230, förutom
Via, bort och vidarebefordras inte:Connection(RFC7230, avsnitt 6.1)Content-Length(RFC7230, avsnitt 3.3.2)Host(RFC7230, avsnitt 5.4)TE(RFC7230, avsnitt 4.3)Trailer(RFC7230, avsnitt 4.4)Transfer-Encoding(RFC7230, avsnitt 3.3.1)Upgrade(RFC7230, avsnitt 6.7)Close(RFC7230, avsnitt 8.1)
requestTarget – sträng. Den här egenskapen innehåller begärandemålet (RFC7230, avsnitt 5.3) i begäran. Den innehåller frågesträngsdelen, som tas bort från ALLA
sb-hc-prefixparametrar.method – string. Det här är metoden för begäran, per RFC7231, avsnitt 4. Metoden
CONNECTFÅR INTE användas.body – boolesk. Anger om en eller flera binära brödtextramar följer.
{
"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
}
}
Svara på begäranden
Mottagaren MÅSTE svara. Upprepad underlåtenhet att svara på begäranden vid underhåll av anslutningen kan leda till att lyssnaren blockeras.
Svar kan skickas i valfri ordning, men varje begäran måste besvaras inom 60 sekunder eller så rapporteras leveransen ha misslyckats. Tidsgränsen på 60 sekunder räknas tills ramen response har tagits emot av tjänsten. Ett pågående svar med flera binära bildrutor kan inte bli inaktivt i mer än 60 sekunder eller avslutas.
Om begäran tas emot via kontrollkanalen måste svaret antingen skickas på kontrollkanalen där begäran togs emot eller så måste den skickas via en rendezvous-kanal.
Svaret är ett JSON-objekt med namnet "response". Reglerna för att hantera brödtextinnehåll är precis som med request meddelandet och baserat på body egenskapen.
- requestId – sträng. KRÄVS. Egenskapsvärdet
idför meddelandetrequestsom besvaras. - statusCode – tal. KRÄVS. en numerisk HTTP-statuskod som anger resultatet av meddelandet. Alla statuskoder för RFC7231, avsnitt 6 är tillåtna, förutom 502 "Felaktig gateway" och 504 "Gateway Timeout".
- statusDescription – sträng. VALFRI. HTTP-statuskod orsaksfras per RFC7230, avsnitt 3.1.2
- responseHeaders – HTTP-huvuden som ska anges i ett externt HTTP-svar.
Precis som
requestmed får RFC7230 definierade rubriker INTE användas. - body – boolesk. Anger om binära brödtextramar följer(er).
----- 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" }
----------------------------------
Svara via rendezvous
För svar som överskrider 64 kB måste svaret levereras via en rendezvous socket. Om begäran överskrider 64 kB och den request enda innehåller adressfältet måste en rendezvous-socket upprättas för att hämta request. När en rendezvous-socket har upprättats måste svar på respektive klient och efterföljande begäranden från respektive klient levereras via rendezvous-socketen medan den kvarstår.
address URL:en i request måste användas som den är för att upprätta rendezvous-socketen, men innehåller följande parametrar:
| Parameter | Obligatoriskt | Beskrivning |
|---|---|---|
sb-hc-action |
Ja | För att acceptera en socket måste parametern vara sb-hc-action=request |
Om det uppstår ett fel kan tjänsten svara på följande sätt:
| Kod | Fel | Beskrivning |
|---|---|---|
| 400 | Ogiltig begäran | Okänd åtgärd eller url är inte giltig. |
| 403 | Ej tillåtet | URL:en har upphört att gälla. |
| 500 | Internt fel | Något gick fel i tjänsten |
När anslutningen har upprättats stänger servern av WebSocket när klientens HTTP-socket stängs av eller med följande status:
| WS-status | Description |
|---|---|
| 1001 | Avsändarklienten stänger av anslutningen. |
| 1001 | Hybrid-Anslut ionssökvägen har tagits bort eller inaktiverats. |
| 1008 | Säkerhetstoken har upphört att gälla och därför överträds auktoriseringsprincipen. |
| 1011 | Något gick fel i tjänsten. |
Förnyelse av lyssnartoken
När lyssnartoken snart upphör att gälla kan den ersätta den genom att skicka ett textramsmeddelande till tjänsten via den etablerade kontrollkanalen. Meddelandet innehåller ett JSON-objekt med namnet renewToken, som definierar följande egenskap just nu:
- token – en giltig, URL-kodad Service Bus-token för delad åtkomst för namnområdet eller Hybrid Anslut ion som ger lyssnarrätt.
{
"renewToken": {
"token":
"SharedAccessSignature sr=http%3a%2f%2fcontoso.servicebus.windows.net%2fhyco%2f&sig=XXXXXXXXXX%3d&se=1471633754&skn=SasKeyName"
}
}
Om tokenverifieringen misslyckas nekas åtkomst och molntjänsten stänger kontrollkanalen WebSocket med ett fel. Annars finns det inget svar.
| WS-status | Description |
|---|---|
| 1008 | Säkerhetstoken har upphört att gälla och därför överträds auktoriseringsprincipen. |
Anslutningsprotokoll för Web Socket
Avsändarprotokollet är i praktiken identiskt med hur en lyssnare upprättas. Målet är maximal transparens för WebSocket från slutpunkt till slutpunkt. Adressen som ska anslutas till är samma som för lyssnaren, men "åtgärden" skiljer sig och token behöver en annan behörighet:
wss://{namespace-address}/$hc/{path}?sb-hc-action=...&sb-hc-id=...&sb-hc-token=...
Namnområdesadressen är det fullständigt kvalificerade domännamnet för Azure Relay-namnområdet som är värd för Hybrid Anslut ion, vanligtvis i formuläret {myname}.servicebus.windows.net.
Begäran kan innehålla godtyckliga extra HTTP-huvuden, inklusive programdefinierade. Alla angivna huvuden flödar till lyssnaren och kan hittas i connectHeader objektet för accept-kontrollmeddelandet .
Alternativen för frågesträngsparametern är följande:
| Param | Obligatoriskt? | Description |
|---|---|---|
sb-hc-action |
Ja | För avsändarrollen måste parametern vara sb-hc-action=connect. |
{path} |
Ja | (se följande stycke) |
sb-hc-token |
Ja* | Lyssnaren måste ange en giltig, URL-kodad Service Bus-token för delad åtkomst för namnområdet eller Hybrid Anslut ion som ger behörigheten Skicka. |
sb-hc-id |
Inga | Ett valfritt ID som möjliggör diagnostikspårning från slutpunkt till slutpunkt och görs tillgängligt för lyssnaren under handskakningen. |
{path} är den URL-kodade namnområdessökvägen för den förkonfigurerade Hybrid-Anslut ion som lyssnaren ska registreras på. Uttrycket path kan utökas med ett suffix och ett frågesträngsuttryck för att kommunicera vidare. Om Hybrid Anslut ion registreras under sökvägen hycopath kan uttrycket följas hyco/suffix?param=value&... av frågesträngsparametrarna som definieras här. Ett fullständigt uttryck kan då vara följande:
wss://{namespace-address}/$hc/hyco/suffix?param=value&sb-hc-action=...[&sb-hc-id=...&]sb-hc-token=...
Uttrycket path skickas till lyssnaren i adress-URI:n som finns i kontrollmeddelandet "acceptera".
Om WebSocket-anslutningen misslyckas på grund av att Hybrid Anslut ion-sökvägen inte har registrerats, en ogiltig eller saknad token eller något annat fel, tillhandahålls felfeedback med hjälp av den vanliga http 1.1-statusfeedbackmodellen. Statusbeskrivningen innehåller ett felspårnings-ID som kan kommuniceras med Azures supportpersonal:
| Kod | Fel | Description |
|---|---|---|
| 404 | Hittades inte | Hybrid-Anslut ionssökvägen är ogiltig eller så är bas-URL:en felaktig. |
| 401 | Behörighet saknas | Säkerhetstoken saknas, är felaktigt eller ogiltig. |
| 403 | Ej tillåtet | Säkerhetstoken är inte giltig för den här sökvägen och för den här åtgärden. |
| 500 | Internt fel | Något gick fel i tjänsten. |
Om WebSocket-anslutningen avsiktligt stängs av av tjänsten efter att den har konfigurerats kommuniceras orsaken till detta med hjälp av en lämplig Felkod för WebSocket-protokollet tillsammans med ett beskrivande felmeddelande som även innehåller ett spårnings-ID.
| WS-status | Description |
|---|---|
| 1000 | Lyssnaren stänger av socketen. |
| 1001 | Hybrid-Anslut ionssökvägen har tagits bort eller inaktiverats. |
| 1008 | Säkerhetstoken har upphört att gälla, så auktoriseringsprincipen överträds. |
| 1011 | Något gick fel i tjänsten. |
HTTP-begärandeprotokoll
Protokollet för HTTP-begäran tillåter godtyckliga HTTP-begäranden, förutom protokolluppgraderingar. HTTP-begäranden riktas mot entitetens vanliga körningsadress, utan det $hc infix som används för WebSocket-hybridanslutningar.
https://{namespace-address}/{path}?sb-hc-token=...
Namnområdesadressen är det fullständigt kvalificerade domännamnet för Azure Relay-namnområdet som är värd för Hybrid Anslut ion, vanligtvis i formuläret {myname}.servicebus.windows.net.
Begäran kan innehålla godtyckliga extra HTTP-huvuden, inklusive programdefinierade. Alla angivna huvuden, förutom de som definierats direkt i RFC7230 (se Begärandemeddelande) flödar till lyssnaren requestHeader och kan hittas i objektet för begärandemeddelandet.
Alternativen för frågesträngsparametern är följande:
| Param | Obligatoriskt? | Description |
|---|---|---|
sb-hc-token |
Ja* | Lyssnaren måste ange en giltig, URL-kodad Service Bus-token för delad åtkomst för namnområdet eller Hybrid Anslut ion som ger behörigheten Skicka. |
Token kan också överföras i antingen ServiceBusAuthorization HTTP-huvudet eller Authorization HTTP-huvudet. Token kan utelämnas om Hybrid Anslut ion har konfigurerats för att tillåta anonyma begäranden.
Eftersom tjänsten effektivt fungerar som en proxy, även om den inte är en sann HTTP-proxy, lägger den antingen till ett Via huvud eller kommenterar det befintliga Via huvudet som är kompatibelt med RFC7230, avsnitt 5.7.1.
Tjänsten lägger till värdnamnet för Relay-namnområdet till Via.
| Kod | Meddelande | Description |
|---|---|---|
| 200 | OK | Begäran har hanterats av minst en lyssnare. |
| 202 | Godkänd | Begäran har godkänts av minst en lyssnare. |
Om det uppstår ett fel kan tjänsten svara på följande sätt. Om svaret kommer från tjänsten eller från lyssnaren kan identifieras via närvaro av Via huvudet. Om rubriken finns kommer svaret från lyssnaren.
| Kod | Fel | Description |
|---|---|---|
| 404 | Hittades inte | Hybrid-Anslut ionssökvägen är ogiltig eller så är bas-URL:en felaktig. |
| 401 | Behörighet saknas | Säkerhetstoken saknas, är felaktigt eller ogiltig. |
| 403 | Ej tillåtet | Säkerhetstoken är inte giltig för den här sökvägen och för den här åtgärden. |
| 500 | Internt fel | Något gick fel i tjänsten. |
| 503 | Felaktig gateway | Det gick inte att dirigera begäran till någon lyssnare. |
| 504 | Tidsgräns för gateway | Begäran dirigerades till en lyssnare, men lyssnaren bekräftade inte mottagandet under den tid som krävdes. |