Azure Relay Hybrid Csatlakozás ions protokoll

Cikk
10/24/2023

Az Azure Relay az Azure Service Bus platform egyik fő képességpillére. A Relay új hibrid Csatlakozás ions képessége egy biztonságos, nyílt protokollon alapuló fejlődés HTTP- és WebSocket-alapú. Felváltja az egykori, egyenlő nevű BizTalk Services funkciót, amely egy védett protokollalapra épült. A hibrid Csatlakozás ok integrálása a Azure-alkalmazás-szolgáltatásokba továbbra is működik.

A hibrid Csatlakozás ions kétirányú, kérés-válasz és bináris adatfolyam-kommunikációt, valamint egyszerű adatfolyam-forgalmat tesz lehetővé két hálózati alkalmazás között. Vagy mindkét fél mögött NATs vagy tűzfalak.

Ez a cikk a hibrid Csatlakozás ions relay ügyféloldali interakcióit ismerteti a figyelő és a küldő szerepkörben lévő ügyfelek csatlakoztatásához. Azt is ismerteti, hogyan fogadják el a figyelők az új kapcsolatokat és kéréseket.

Interakciós modell

A hibrid Csatlakozás ions relay két felet köt össze azáltal, hogy egy rendezvous pontot biztosít az Azure-felhőben, amelyhez a felek saját hálózatuk szempontjából képesek felderíteni és csatlakozni. A rendezési pont neve "Hibrid Csatlakozás ion" ebben és más dokumentációban, az API-kban és az Azure Portalon. A hibrid Csatlakozás ions szolgáltatásvégpontot a cikk további részében "szolgáltatásnak" nevezzük.

A szolgáltatás lehetővé teszi a Web Socket-kapcsolatok és HTTP-kérések és válaszok újrafektetését.

Az interakciós modell sok más hálózati API-k által létrehozott nómenklatúrára támaszkodik. Van egy figyelő, amely először azt jelzi, hogy készen áll a bejövő kapcsolatok kezelésére, majd fogadja őket érkezéskor. A másik oldalon egy ügyfél csatlakozik a figyelőhöz, és azt várja, hogy a kapcsolat elfogadva legyen egy kétirányú kommunikációs útvonal létrehozásához. A "Csatlakozás", a "Figyelés" és az "Elfogadás" kifejezés ugyanazokat a kifejezéseket használja, mint a legtöbb szoftvercsatornás API-ban.

A továbbított kommunikációs modellek bármelyik fél kimenő kapcsolatot létesítenek egy szolgáltatásvégpont felé. Így a "figyelő" köznyelvi használatban is "ügyfél", és más terminológiák túlterhelését is okozhatja. A hibrid Csatlakozás ionok pontos terminológiája tehát a következő:

A kapcsolat mindkét oldalán lévő programokat "ügyfeleknek" nevezzük, mivel ők a szolgáltatás ügyfelei. A kapcsolatokat várakozó és elfogadó ügyfél a "figyelő", vagy azt mondják, hogy a "figyelői szerepkörben" van. A szolgáltatáson keresztül egy figyelő felé új kapcsolatot kezdeményező ügyfelet "feladónak" nevezzük, vagy "feladói szerepkörrel" rendelkezik.

Figyelők interakciói

A figyelő öt interakcióval rendelkezik a szolgáltatással; a hivatkozási szakaszban található cikk későbbi részében minden vezetékrészletet ismertetünk.

A figyelés, az elfogadás és a kérés üzenetei a szolgáltatástól érkeznek. A megújítási és pingelési műveleteket a figyelő küldi el.

Üzenet figyelés

Ha azt szeretné jelezni, hogy a figyelő készen áll a kapcsolatok elfogadására, létrehoz egy kimenő WebSocket-kapcsolatot. A kapcsolati kézfogás a Relay névtéren konfigurált hibrid Csatlakozás ion nevét, valamint egy biztonsági jogkivonatot hordoz, amely közvetlenül ezen a névn biztosítja a "Figyelés" nevet.

Amikor a szolgáltatás elfogadja a WebSocketet, a regisztráció befejeződött, és a létrehozott WebSocket a "vezérlőcsatornaként" életben marad az összes további interakció engedélyezéséhez. A szolgáltatás egy hibrid Csatlakozás legfeljebb 25 egyidejű figyelőt tesz lehetővé. Meg kell határozni az AppHooks kvótáját.

Hibrid Csatlakozás esetén, ha két vagy több aktív figyelő van, a bejövő kapcsolatok véletlenszerű sorrendben vannak osztva; a tisztességes elosztást a rendszer a legjobb erőfeszítéssel próbálja meg.

Üzenet elfogadása

Amikor egy feladó új kapcsolatot nyit meg a szolgáltatáson, a szolgáltatás kiválasztja és értesíti az egyik aktív figyelőt a Hibrid Csatlakozás ionon. Ezt az értesítést a rendszer JSON-üzenetként küldi el a figyelőnek a nyitott vezérlőcsatornán keresztül. Az üzenet annak a WebSocket-végpontnak az URL-címét tartalmazza, amelyhez a figyelőnek csatlakoznia kell a kapcsolat elfogadásához.

Az URL-címet a figyelő közvetlenül, további munka nélkül használhatja és használhatja. A kódolt információk csak rövid ideig érvényesek, lényegében addig, amíg a feladó hajlandó megvárni, amíg a kapcsolat létrejön a végpontok között. A maximálisan feltételezhető érték 30 másodperc. Az URL-cím csak egy sikeres kapcsolati kísérlethez használható. Amint létrejött a WebSocket kapcsolat a rendezési URL-címmel, a WebSocket minden további tevékenysége továbbítva lesz a feladótól és a feladónak. Ez a viselkedés a szolgáltatás beavatkozása vagy értelmezése nélkül történik.

Üzenet kérése

A WebSocket-kapcsolatokon kívül a figyelő HTTP-kéréskereteket is fogadhat a feladótól, ha ez a funkció kifejezetten engedélyezve van a hibrid Csatlakozás ionon.

A HTTP-támogatással rendelkező hibrid Csatlakozás csatoló figyelőknek kezelnie kell a kézmozdulatotrequest. A szolgáltatás a jövőben letilthatja azokat a figyelőket, amelyek nem kezelik request , és ezért ismétlődő időtúllépési hibákat okoznak a csatlakozás során.

A HTTP-keretfejléc metaadatai jSON-ra vannak lefordítva a figyelő keretrendszer egyszerűbb kezelése érdekében, valamint azért is, mert a HTTP-fejlécelemző kódtárak ritkábbak, mint a JSON-elemzők. A rendszer nem továbbítja azokat a HTTP-metaadatokat, amelyek csak a feladó és a Relay HTTP-átjáró közötti kapcsolat szempontjából relevánsak, beleértve az engedélyezési adatokat is. A HTTP-kérelemtörzsek bináris WebSocket-keretekként transzparens módon lesznek átadva.

A figyelő ezzel egyenértékű válaszmozdulattal válaszolhat a HTTP-kérésekre.

A kérés-válasz folyamat alapértelmezés szerint a vezérlőcsatornát használja, de szükség esetén "frissíthető" egy különálló rendezésű WebSocketre. A különböző WebSocket-kapcsolatok javítják az egyes ügyfélbeszélgetések átviteli sebességét, de a figyelőt több olyan kapcsolattal terhelik, amelyeket kezelni kell, ami nem biztos, hogy könnyű ügyfelekre vágyik.

A vezérlőcsatornán a kérelem- és választestek legfeljebb 64 kB méretűek lehetnek. A HTTP-fejléc metaadatai összesen 32 kB-ra korlátozódnak. Ha a kérés vagy a válasz túllépi ezt a küszöbértéket, a figyelőnek egy rendezvous WebSocketre kell frissítenie az Elfogadás kezelésével egyenértékű kézmozdulattal.

A kérések esetében a szolgáltatás dönti el, hogy a kéréseket a vezérlőcsatornán keresztül irányítja-e. Ez magában foglalja, de nem korlátozható olyan esetekre, amikor egy kérés meghaladja a 64 kB-ot (fejlécek plusz törzs) egyenesen, vagy ha a kérést "tömbösített" átvitelkódolással küldik el, és a szolgáltatásnak oka van arra, hogy a kérés meghaladja a 64 kB-ot, vagy a kérés olvasása nem azonnali. Ha a szolgáltatás úgy dönt, hogy rendezve kézbesíti a kérést, csak a rendezés címét adja át a figyelőnek. A figyelőnek ezután létre kell hoznia a rendezvous WebSocketet, és a szolgáltatás azonnal kézbesíti a teljes kérést, beleértve a rendezésű WebSocketen lévő szerveket is. A válasznak a rendezésű WebSocketet is használnia kell.

A vezérlőcsatornára érkező kérések esetén a figyelő dönti el, hogy válaszol-e a vezérlőcsatornára vagy rendezvouson keresztül. A szolgáltatásnak tartalmaznia kell egy rendezvous címet, amely minden kérést a vezérlőcsatornára irányít át. Ez a cím csak az aktuális kérésről való frissítésre érvényes.

Ha a figyelő a frissítés mellett dönt, csatlakozik, és azonnal elküldi a választ a létrehozott rendezvous szoftvercsatornán keresztül.

A rendezvous WebSocket létrehozása után a figyelőnek fenn kell tartania azt az ugyanazon ügyféltől érkező kérések és válaszok további kezeléséhez. A szolgáltatás mindaddig fenntartja a WebSocketet, amíg a küldővel fennálló HTTPS-szoftvercsatorna-kapcsolat nem szűnik meg, és az adott feladótól érkező összes további kérést a fenntartott WebSocketre irányítja át. Ha a figyelő úgy dönt, hogy az oldaláról elveti a rendezésű WebSocketet, a szolgáltatás a feladóval való kapcsolatot is megszakítja, függetlenül attól, hogy egy későbbi kérés már folyamatban van-e.

Művelet megújítása

A figyelő regisztrálásához és a vezérlőcsatorna karbantartásához használandó biztonsági jogkivonat lejárhat, amíg a figyelő aktív. A jogkivonat lejárata nincs hatással a folyamatban lévő kapcsolatokra, de ez azt eredményezi, hogy a szolgáltatás a lejárat pillanatában vagy azt követően nem sokkal elveti a vezérlőcsatornát. A "megújítás" művelet egy JSON-üzenet, amelyet a figyelő elküldhet a vezérlőcsatornához társított jogkivonat cseréjéhez, így a vezérlőcsatorna hosszabb ideig tartható fenn.

Pingelési művelet

Ha a vezérlőcsatorna hosszú ideig tétlen marad, az útban lévő közvetítők, például a terheléselosztók vagy a NAT-k megszakíthatják a TCP-kapcsolatot. A "pingelés" művelet elkerüli, hogy kis mennyiségű adatot küldjön a csatornán, amely emlékezteti a hálózati útvonalon lévő összes felhasználót arra, hogy a kapcsolatnak életben kell lennie, és "élő" tesztként is szolgál a figyelő számára. Ha a pingelés sikertelen, a vezérlőcsatornát használhatatlannak kell tekinteni, és a figyelőnek újra kell kapcsolódnia.

A feladó interakciója

A feladónak két interakciója van a szolgáltatással: csatlakoztat egy webcsatornát, vagy HTTPS-en keresztül küld kéréseket. A kérések nem küldhetők webcsatornán keresztül a feladói szerepkörből.

Csatlakozás művelet

A "connect" művelet megnyitja a WebSocketet a szolgáltatásban, megadva a hibrid Csatlakozás ion nevét, és (opcionálisan, de alapértelmezés szerint kötelező) egy biztonsági jogkivonatot, amely "Küldés" engedélyt ad a lekérdezési sztringben. A szolgáltatás ezután a korábban ismertetett módon kommunikál a figyelővel, és a figyelő létrehoz egy rendezvous kapcsolatot, amely ehhez a WebSockethez csatlakozik. A WebSocket elfogadása után a WebSocket minden további interakciója egy csatlakoztatott figyelővel van.

Kérelemművelet

A hibrid Csatlakozás, amelyek esetében a funkció engedélyezve van, a küldő nagyrészt korlátlan HTTP-kéréseket küldhet a figyelőknek.

A lekérdezési sztringbe vagy a kérelem HTTP-fejlécébe beágyazott Relay hozzáférési jogkivonat kivételével a Relay teljes mértékben transzparens a Relay-cím és a Relay címútvonal összes utótagja számára, így a figyelő teljes mértékben szabályozhatja a végpontok közötti engedélyezést és még a HTTP-bővítmények funkcióit is, például a CORS-t.

A továbbítási végponttal rendelkező feladó-engedélyezés alapértelmezés szerint be van kapcsolva, de NEM KÖTELEZŐ. A hibrid Csatlakozás ion tulajdonosa dönthet úgy, hogy engedélyezi a névtelen feladókat. A szolgáltatás az alábbiak szerint fogja lehallgatni, megvizsgálni és lecsupasztatni az engedélyezési adatokat:

Ha a lekérdezési sztring tartalmaz egy sb-hc-token kifejezést, a kifejezés MINDIG törlődik a lekérdezési sztringből. A rendszer kiértékeli, hogy a Relay-engedélyezés be van-e kapcsolva.
Ha a kérelemfejlécek fejlécet ServiceBusAuthorization tartalmaznak, a fejléckifejezés MINDIG törlődik a fejlécgyűjteményből. A rendszer kiértékeli, hogy a Relay-engedélyezés be van-e kapcsolva.
Csak akkor, ha a Relay-engedélyezés be van kapcsolva, és ha a kérelemfejlécek fejlécet tartalmaznak Authorization , és egyik korábbi kifejezés sem szerepel, a rendszer kiértékeli és eltávolítja a fejlécet. Ellenkező esetben a Authorizationtovábbítás mindig a következőképpen történik.

Ha nincs aktív figyelő, a szolgáltatás egy 502"Bad Gateway" hibakódot ad vissza. Ha úgy tűnik, hogy a szolgáltatás nem kezeli a kérést, a szolgáltatás 60 másodperc után 504 "átjáró időtúllépést" ad vissza.

Interakciók összegzése

Ennek az interakciós modellnek az az eredménye, hogy a küldő ügyfél kijön a kézfogásból egy "tiszta" WebSockettel, amely egy figyelőhöz csatlakozik, és amelyhez nincs szükség további preambulumokra vagy előkészítésre. Ez a modell gyakorlatilag minden meglévő WebSocket-ügyfél-implementáció számára lehetővé teszi a Hibrid Csatlakozás ions szolgáltatás előnyeit, ha helyesen összeállított URL-címet ad meg a WebSocket ügyfélrétegébe.

A figyelő által az elfogadási interakción keresztül beszerzett rendezvous connection WebSocket szintén tiszta, és bármely meglévő WebSocket-kiszolgáló-implementációnak átadható, minimális extra absztrakcióval, amely megkülönbözteti a keretrendszer helyi hálózati figyelőinek "elfogadás" műveleteit és a hibrid Csatlakozás ions távoli "elfogadás" műveleteit.

A HTTP-kérés-/válaszmodell nagyrészt korlátlan HTTP protokollfelületet biztosít a feladónak, opcionális engedélyezési réteggel. A figyelő egy előre elemezett HTTP-kérésfejlécszakaszt kap, amely visszafordítható alsóbb rétegbeli HTTP-kéréssé, vagy az adott módon kezelhetővé, HTTP-törzseket tartalmazó bináris keretekkel. A válaszok formátuma megegyezik. A 64 KB-nál kisebb kérelem- és választörzsű interakciók egyetlen webcsatornán keresztül kezelhetők, amely minden feladó számára meg van osztva. A nagyobb kérések és válaszok a rendezés modellel kezelhetők.

Protokollhivatkozás

Ez a szakasz a korábban ismertetett protokoll-interakciók részleteit ismerteti.

Az összes WebSocket-kapcsolat a 443-as porton jön létre a HTTPS 1.1-es verzióról való frissítésként, amelyet általában néhány WebSocket-keretrendszer vagy API absztrakciója tesz lehetővé. Az itt szereplő leírás nem tartalmazott implementációt, konkrét keretrendszerre nem utalva.

Figyelő protokoll

A figyelőprotokoll két kapcsolati kézmozdulatból és három üzenetműveletből áll.

Figyelővezérlő csatornakapcsolata

A vezérlőcsatorna megnyílik egy WebSocket-kapcsolat létrehozásával a következőkkel:

wss://{namespace-address}/$hc/{path}?sb-hc-action=...[&sb-hc-id=...]&sb-hc-token=...

A namespace-address hibrid Csatlakozás iont üzemeltető Azure Relay névtér teljes tartományneve, általában az űrlap{myname}.servicebus.windows.net.

A lekérdezési sztring paraméterbeállításai a következők.

Parameter	Kötelező	Leírás
`sb-hc-action`	Igen	A figyelőszerepkörhöz a paraméternek sb-hc-action=listen
`{path}`	Igen	A figyelő regisztrálásához az előre konfigurált hibrid Csatlakozás ion URL-kódolt névterének elérési útja. Ez a kifejezés hozzá van fűzve a rögzített `$hc/` elérési út részhez.
`sb-hc-token`	Igen*	A figyelőnek érvényes, URL-kódolású Service Bus megosztott hozzáférési jogkivonatot kell biztosítania ahhoz a névtérhez vagy hibrid Csatlakozás, amely a figyelési jogot biztosítja.
`sb-hc-id`	Nem	Ez az ügyfél által megadott opcionális azonosító lehetővé teszi a végpontok közötti diagnosztikai nyomkövetést.

Ha a WebSocket-kapcsolat meghiúsul, mert a hibrid Csatlakozás ion elérési útja nem regisztrálva, vagy érvénytelen vagy hiányzó jogkivonat vagy valamilyen egyéb hiba miatt meghiúsul, a hibavisszajelzést a rendszer a normál HTTP 1.1 állapotvisszajelzési modell használatával adja meg. Az állapot leírása tartalmaz egy hibakövetési azonosítót, amely Azure-támogatás személyzettel közölhető:

Code	Error	Leírás
404	Nem található	A hibrid Csatlakozás ion elérési útja érvénytelen, vagy az alap URL-cím hibás.
401	Unauthorized	A biztonsági jogkivonat hiányzik, hibás vagy érvénytelen.
403	Forbidden	A biztonsági jogkivonat nem érvényes ehhez a művelethez.
500	Belső hiba	Hiba történt a szolgáltatásban.

Ha a WebSocket-kapcsolatot a szolgáltatás szándékosan leállítja a kezdeti beállítás után, ennek okát egy megfelelő WebSocket protokoll hibakóddal, valamint egy leíró hibaüzenettel közli, amely egy nyomkövetési azonosítót is tartalmaz. A szolgáltatás nem fogja leállítani a vezérlőcsatornát hibaállapot nélkül. A tiszta leállítás az ügyfél által vezérelve van.

WS állapota	Leírás
1001	A hibrid Csatlakozás ion elérési útját törölték vagy letiltották.
1008	A biztonsági jogkivonat lejárt, ezért az engedélyezési szabályzat sérül.
1011	Hiba történt a szolgáltatásban.

Kézfogás elfogadása

A szolgáltatás JSON-üzenetként küldi el az "elfogadás" értesítést a figyelőnek a korábban létrehozott vezérlőcsatornán keresztül egy WebSocket-szövegkeretben. Erre az üzenetre nincs válasz.

Az üzenet egy "accept" nevű JSON-objektumot tartalmaz, amely jelenleg a következő tulajdonságokat határozza meg:

cím – a WebSocket szolgáltatáshoz való létrehozásához használandó URL-sztring a bejövő kapcsolat elfogadásához.
id – a kapcsolat egyedi azonosítója. Ha az azonosítót a küldő ügyfél szolgáltatta, az a feladó által megadott érték, ellenkező esetben rendszer által generált érték.
connectHeaders – minden OLYAN HTTP-fejléc, amelyet a feladó a Relay végponthoz adott, beleértve a Sec-WebSocket-Protocol és a Sec-WebSocket-Extensions fejléceket is.

{
    "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" : "..."
        }
     }
}

A figyelő a JSON-üzenetben megadott cím URL-címét használja a WebSocket létrehozásához a feladó szoftvercsatornájának elfogadásához vagy elutasításához.

A szoftvercsatorna elfogadása

Az elfogadáshoz a figyelő létrehoz egy WebSocket-kapcsolatot a megadott címmel.

Ha az "elfogadás" üzenet fejlécet Sec-WebSocket-Protocol tartalmaz, a figyelő várhatóan csak akkor fogadja el a WebSocketet, ha támogatja ezt a protokollt. Emellett beállítja a fejlécet a WebSocket létrehozásakor.

Ugyanez vonatkozik a Sec-WebSocket-Extensions fejlécre is. Ha a keretrendszer támogatja a bővítményt, a fejlécet a bővítményhez szükséges Sec-WebSocket-Extensions kézfogás kiszolgálóoldali válaszára kell beállítania.

Az URL-címet az elfogadási szoftvercsatorna létrehozásához kell használni, de a következő paramétereket tartalmazza:

Parameter	Kötelező	Leírás
`sb-hc-action`	Igen	Szoftvercsatorna elfogadásához a paraméternek `sb-hc-action=accept`
`{path}`	Igen	(lásd a következő bekezdést)
`sb-hc-id`	Nem	Lásd az azonosító korábbi leírását.

{path}A figyelő regisztrálásához az előre konfigurált hibrid Csatlakozás ion URL-kódolt névterének elérési útja. Ez a kifejezés hozzá van fűzve a rögzített $hc/ elérési út részhez.

A path kifejezés egy utótaggal és egy lekérdezési sztringkifejezéssel bővíthető, amely a regisztrált nevet követi a perjelek elválasztása után. Ez a paraméter lehetővé teszi, hogy a küldő ügyfél elküldje a küldési argumentumokat az elfogadó figyelőnek, ha nem lehet HTTP-fejléceket belefoglalni. Az elvárás az, hogy a figyelő-keretrendszer elemezze a rögzített elérési út részét és a regisztrált nevet az elérési útból, és a fennmaradó részt , valószínűleg anélkül, hogy a lekérdezési sztring sb-argumentumai előtaggal rendelkezne, elérhetővé teszi az alkalmazás számára, hogy eldöntse, elfogadja-e a kapcsolatot.

További információ: "Sender Protocol" (Feladói protokoll) szakasz.

Hiba esetén a szolgáltatás az alábbiak szerint válaszolhat:

Code	Error	Leírás
403	Forbidden	Az URL-cím érvénytelen.
500	Belső hiba	Hiba történt a szolgáltatásban

A kapcsolat létrejötte után a kiszolgáló leállítja a WebSocketet, amikor a küldő WebSocket leáll, vagy a következő állapottal:

WS állapota	Leírás
1001	A küldő ügyfél leállítja a kapcsolatot.
1001	A hibrid Csatlakozás ion elérési útját törölték vagy letiltották.
1008	A biztonsági jogkivonat lejárt, ezért az engedélyezési szabályzat sérül.
1011	Hiba történt a szolgáltatásban.

A szoftvercsatorna elvetése

Az üzenet vizsgálata accept után a szoftvercsatorna elutasításához hasonló kézfogásra van szükség, hogy az elutasítás okát kommunikáló állapotkód és állapotleírás visszafolyjon a feladóhoz.

A protokollterv itt egy WebSocket-kézfogást használ (amely úgy van kialakítva, hogy meghatározott hibaállapotban végződjön), hogy a figyelőügyfél-implementációk továbbra is a WebSocket-ügyfélre támaszkodjanak, és ne kelljen külön, csupasz HTTP-ügyfelet alkalmazniuk.

A szoftvercsatorna elvetéséhez az ügyfél felveszi az üzenet címének URI-címét accept , és hozzáfűz két lekérdezési sztringparamétert az alábbiak szerint:

Param	Kötelező	Leírás
sb-hc-statusCode	Igen	Numerikus HTTP-állapotkód.
sb-hc-statusDescription	Igen	Az elutasítás emberi olvasható oka.

Ezután az eredményként kapott URI-val létrejön egy WebSocket-kapcsolat.

A helyes befejezésekor ez a kézfogás szándékosan meghiúsul a 410-as HTTP-hibakóddal, mivel nem jött létre WebSocket. Ha hiba történik, a következő kódok ismertetik a hibát:

Code	Error	Leírás
403	Forbidden	Az URL-cím érvénytelen.
500	Belső hiba	Hiba történt a szolgáltatásban.

Üzenet kérése

A request szolgáltatás elküldi az üzenetet a figyelőnek a vezérlőcsatornán keresztül. Ugyanez az üzenet a rendezvous WebSocketen is át lesz küldve, miután létrejött.

A request két részből áll: egy fejlécből és egy bináris törzskeretből. Ha nincs test, a rendszer kihagyja a testkereteket. A logikai body tulajdonság azt jelzi, hogy egy törzs szerepel-e a kérelemüzenetben.

A kérelemtörzsgel rendelkező kérések esetében a struktúra a következőképpen nézhet ki:

----- Web Socket text frame ----
{
    "request" :
    {
        "body" : true,
        ...
    }
}
----- Web Socket binary frame ----
FEFEFEFEFEFEFEFEFEFEF...
----- Web Socket binary frame ----
FEFEFEFEFEFEFEFEFEFEF...
----- Web Socket binary frame -FIN
FEFEFEFEFEFEFEFEFEFEF...
----------------------------------

A figyelőnek kezelnie kell a kérelem törzsének több bináris keretre osztott fogadását (lásd : WebSocket-töredékek). A kérés akkor fejeződik be, ha a FIN jelölőkészlettel rendelkező bináris keret érkezett.

Törzs nélküli kérések esetén csak egy szövegkeret van.

----- Web Socket text frame ----
{
    "request" :
    {
        "body" : false,
        ...
    }
}
----------------------------------

A JSON-tartalom a request következő:

address - URI sztring. Ez a kéréshez használandó rendezvous cím. Ha a bejövő kérés nagyobb, mint 64 kB, az üzenet fennmaradó része üres marad, és az ügyfélnek az alább leírt műveletnek megfelelő rendezési kézfogást kell kezdeményeznie accept . A szolgáltatás ezután a teljes request elemet a létrehozott webes szoftvercsatornára helyezi. Ha a válasz várhatóan meghaladja a 64 kB-ot, a figyelőNEK rendezéses kézfogást is kezdeményeznie kell, majd át kell vinnie a választ a létrehozott webes szoftvercsatornán.
id – sztring. A kérés egyedi azonosítója.
requestHeaders – ez az objektum tartalmazza az összes HTTP-fejlécet, amelyet a feladó adott meg a végpontnak, kivéve a fent ismertetett engedélyezési információkat, valamint az átjáróval való kapcsolathoz szigorúan kapcsolódó fejléceket. Pontosabban a RFC7230 által definiált vagy fenntartott ÖSSZES fejléc, kivéveVia, a rendszer eltávolítja és nem továbbítja:
- Connection (RFC7230, 6.1. szakasz)
- Content-Length (RFC7230, 3.3.2. szakasz)
- Host (RFC7230, 5.4. szakasz)
- TE (RFC7230, 4.3. szakasz)
- Trailer (RFC7230, 4.4. szakasz)
- Transfer-Encoding (RFC7230, 3.3.1. szakasz)
- Upgrade (RFC7230, 6.7. szakasz)
- Close (RFC7230, 8.1. szakasz)
requestTarget – sztring. Ez a tulajdonság tartalmazza a kérés "Kérési cél" (RFC7230, 5.3. szakasz) értékét. Tartalmazza a lekérdezési sztringrészt, amely az ÖSSZES sb-hc- előtagú paramétert eltávolítja.
metódus – sztring. Ez a kérés módszere, RFC7231 4. szakasz szerint. A CONNECT metódus NEM használható.
test – logikai. Azt jelzi, hogy egy vagy több bináris törzskeret követi-e a elemet.

{
    "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
     }
}

Válaszadás a kérelmekre

A fogadónak válaszolnia kell. Ha a kapcsolat fenntartása közben nem válaszol a kérésekre, az azt eredményezheti, hogy a figyelő le lesz tiltva.

A válaszok bármilyen sorrendben elküldhetők, de minden kérésre 60 másodpercen belül válaszolni kell, vagy a kézbesítés sikertelennek minősül. A rendszer a 60 másodperces határidőt addig számítja, amíg a response keretet meg nem kapja a szolgáltatás. A több bináris kerettel rendelkező folyamatban lévő válasz legfeljebb 60 másodpercig tétlenné válhat, vagy leállt.

Ha a kérés a vezérlőcsatornán keresztül érkezik, a választ vagy azon a vezérlőcsatornán kell elküldeni, ahonnan a kérés érkezett, vagy egy rendezésű csatornán kell elküldeni.

A válasz egy "response" nevű JSON-objektum. A törzstartalom kezelésére vonatkozó szabályok pontosan olyanok, mint az request üzenetben és a body tulajdonságon alapulnak.

requestId – sztring. SZÜKSÉGES. A id megválaszolt üzenet tulajdonságértéke request .
statusCode – szám. SZÜKSÉGES. egy numerikus HTTP-állapotkód, amely az értesítés eredményét jelzi. A RFC7231 6. szakaszának összes állapotkódja engedélyezett, kivéve az 502 "Rossz átjáró" és az 504 "Átjáró időtúllépése" értéket.
statusDescription – sztring . VÁLASZTHATÓ. HTTP status-code reason phrase per RFC7230, Section 3.1.2
responseHeaders – KÜLSŐ HTTP-válaszban beállítandó HTTP-fejlécek. requestA RFC7230 megadott fejlécekhez hasonlóan nem használható.
test – logikai. Azt jelzi, hogy a bináris törzskeret(ek) követik-e(ket).

----- 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" }
----------------------------------

Válaszadás rendezvous-on keresztül

A 64 kB-ot meghaladó válaszok esetén a választ rendezésű szoftvercsatornán kell kézbesíteni. Ha a kérelem meghaladja a 64 kB-ot, és csak a request címmezőt tartalmazza, létre kell hozni egy rendezésű szoftvercsatornát a request. A rendezvous socket létrehozása után a megfelelő ügyfélre adott válaszokat és az adott ügyféltől érkező későbbi kéréseket a rendezésű szoftvercsatornán keresztül kell kézbesíteni, amíg az megmarad.

A address rendezésű szoftvercsatorna létrehozásához a request benne lévő URL-címet kell használni, de a következő paramétereket tartalmazza:

Parameter	Kötelező	Leírás
`sb-hc-action`	Igen	Szoftvercsatorna elfogadásához a paraméternek `sb-hc-action=request`

Hiba esetén a szolgáltatás az alábbiak szerint válaszolhat:

Code	Error	Leírás
400	Érvénytelen kérelem	Ismeretlen művelet vagy URL-cím érvénytelen.
403	Forbidden	Az URL-cím lejárt.
500	Belső hiba	Hiba történt a szolgáltatásban

A kapcsolat létrejötte után a kiszolgáló leállítja a WebSocketet, amikor az ügyfél HTTP-szoftvercsatornája leáll, vagy a következő állapottal:

WS állapota	Leírás
1001	A küldő ügyfél leállítja a kapcsolatot.
1001	A hibrid Csatlakozás ion elérési útját törölték vagy letiltották.
1008	A biztonsági jogkivonat lejárt, ezért az engedélyezési szabályzat sérül.
1011	Hiba történt a szolgáltatásban.

Figyelő jogkivonat megújítása

Amikor a figyelő jogkivonata hamarosan lejár, lecserélheti egy szövegkeret-üzenetet küldve a szolgáltatásnak a létrehozott vezérlőcsatornán keresztül. Az üzenet egy JSON-objektumot renewTokentartalmaz, amely jelenleg a következő tulajdonságot határozza meg:

token – egy érvényes, URL-kódolt Service Bus megosztott hozzáférésű jogkivonat a névtérhez vagy a hibrid Csatlakozás, amely a figyelési jogot biztosítja.

{
  "renewToken": {
    "token":
      "SharedAccessSignature sr=http%3a%2f%2fcontoso.servicebus.windows.net%2fhyco%2f&amp;sig=XXXXXXXXXX%3d&amp;se=1471633754&amp;skn=SasKeyName"
  }
}

Ha a jogkivonat érvényesítése sikertelen, a hozzáférés megtagadva, és a felhőszolgáltatás hiba miatt bezárja a WebSocket vezérlőcsatornát. Ellenkező esetben nincs válasz.

WS állapota	Leírás
1008	A biztonsági jogkivonat lejárt, ezért az engedélyezési szabályzat sérül.

Web Socket connect protokoll

A küldő protokoll gyakorlatilag megegyezik a figyelők alapításának módjával. A cél a teljes körű WebSocket maximális átláthatósága. A csatlakozni kívánt cím megegyezik a figyelő címével, de a "művelet" eltér, és a jogkivonatnak más engedélyre van szüksége:

wss://{namespace-address}/$hc/{path}?sb-hc-action=...&sb-hc-id=...&sb-hc-token=...

A névtércím a hibrid Csatlakozás iont futtató Azure Relay névtér teljes tartományneve, általában az űrlapon{myname}.servicebus.windows.net.

A kérelem tetszőleges további HTTP-fejléceket tartalmazhat, beleértve az alkalmazás által definiált fejléceket is. Az összes megadott fejléc a figyelőhöz áramlik, és az connectHeader elfogadás vezérlőüzenet objektumában található.

A lekérdezési sztring paraméterbeállításai a következők:

Param	Kötelező?	Leírás
`sb-hc-action`	Igen	A feladói szerepkörhöz a paraméternek kell lennie `sb-hc-action=connect`.
`{path}`	Igen	(lásd a következő bekezdést)
`sb-hc-token`	Igen*	A figyelőnek érvényes, URL-kódolt Service Bus megosztott hozzáférési jogkivonatot kell biztosítania ahhoz a névtérhez vagy hibrid Csatlakozás, amely a küldési jogot biztosítja.
`sb-hc-id`	Nem	Opcionális azonosító, amely lehetővé teszi a végpontok közötti diagnosztikai nyomkövetést, és a figyelő számára elérhetővé válik az elfogadási kézfogás során.

A {path} figyelő regisztrálásához az előre konfigurált hibrid Csatlakozás ion URL-kódolt névterének elérési útja. A path kifejezés egy utótaggal és egy lekérdezési sztringkifejezéssel bővíthető a további kommunikációhoz. Ha a hibrid Csatlakozás ion regisztrálva van az elérési út hycoalatt, a path kifejezést az itt definiált lekérdezési sztringparaméterek követhetikhyco/suffix?param=value&.... A teljes kifejezés a következő lehet:

wss://{namespace-address}/$hc/hyco/suffix?param=value&sb-hc-action=...[&sb-hc-id=...&]sb-hc-token=...

A path kifejezés át lesz adva a figyelőnek az "elfogadás" vezérlőüzenetben található URI-címben.

Ha a WebSocket-kapcsolat meghiúsul a hibrid Csatlakozás ion elérési útja nem regisztrálva, érvénytelen vagy hiányzó jogkivonat vagy egyéb hiba miatt, a hibavisszajelzést a rendszer a szokásos HTTP 1.1 állapotvisszajelzési modell használatával adja meg. Az állapotleírás tartalmaz egy hibakövetési azonosítót, amely Azure-támogatás személyzettel közölhető:

Code	Error	Leírás
404	Nem található	A hibrid Csatlakozás ion elérési útja érvénytelen, vagy az alap URL-cím hibás.
401	Unauthorized	A biztonsági jogkivonat hiányzik, hibás vagy érvénytelen.
403	Forbidden	A biztonsági jogkivonat nem érvényes erre az útvonalra és a műveletre.
500	Belső hiba	Hiba történt a szolgáltatásban.

Ha a WebSocket-kapcsolatot a szolgáltatás szándékosan leállítja a kezdeti beállítás után, ennek okát egy megfelelő WebSocket-protokoll hibakódjával, valamint egy leíró hibaüzenettel közli, amely egy nyomkövetési azonosítót is tartalmaz.

WS állapota	Leírás
1000	A figyelő leállítja a szoftvercsatornát.
1001	A hibrid Csatlakozás ion elérési útját törölték vagy letiltották.
1008	A biztonsági jogkivonat lejárt, ezért az engedélyezési szabályzat sérül.
1011	Hiba történt a szolgáltatásban.

HTTP-kérelem protokollja

A HTTP-kérelem protokollja tetszőleges HTTP-kéréseket tesz lehetővé, kivéve a protokollfrissítéseket. A HTTP-kérések az entitás normál futtatókörnyezeti címére mutatnak, a hibrid kapcsolatok WebSocket-ügyfelekhez használt $hc infix nélkül.

https://{namespace-address}/{path}?sb-hc-token=...

A névtércím a hibrid Csatlakozás iont futtató Azure Relay névtér teljes tartományneve, általában az űrlapon{myname}.servicebus.windows.net.

A kérelem tetszőleges további HTTP-fejléceket tartalmazhat, beleértve az alkalmazás által definiált fejléceket is. Az összes megadott fejléc, kivéve azokat, amelyek közvetlenül RFC7230 (lásd a Kérelem üzenet) folyamatát a figyelőnek, és a requestHeader kérelemüzenet objektumában találhatók.

A lekérdezési sztring paraméterbeállításai a következők:

Param	Kötelező?	Leírás
`sb-hc-token`	Igen*	A figyelőnek érvényes, URL-kódolt Service Bus megosztott hozzáférési jogkivonatot kell biztosítania ahhoz a névtérhez vagy hibrid Csatlakozás, amely a küldési jogot biztosítja.

A jogkivonat a HTTP-fejlécben ServiceBusAuthorization is Authorization tárolható. A jogkivonat elhagyható, ha a hibrid Csatlakozás ion névtelen kérések engedélyezésére van konfigurálva.

Mivel a szolgáltatás gyakorlatilag proxyként működik, még akkor is, ha nem valódi HTTP-proxyként, vagy hozzáad egy Via fejlécet, vagy a meglévő Via fejlécet a RFC7230 5.7.1 szakaszának megfelelően jegyzeteli. A szolgáltatás hozzáadja a Relay névtér gazdagépnevét.Via

Kód	Üzenet	Leírás
200	OK	A kérést legalább egy figyelő kezelte.
202	Elfogadva	A kérést legalább egy figyelő elfogadta.

Hiba esetén a szolgáltatás az alábbiak szerint válaszolhat. A fejléc jelenlétével Via azonosítható, hogy a válasz a szolgáltatásból vagy a figyelőből származik-e. Ha a fejléc jelen van, a válasz a figyelőtől származik.

Code	Error	Leírás
404	Nem található	A hibrid Csatlakozás ion elérési útja érvénytelen, vagy az alap URL-cím hibás.
401	Unauthorized	A biztonsági jogkivonat hiányzik, hibás vagy érvénytelen.
403	Forbidden	A biztonsági jogkivonat nem érvényes erre az útvonalra és a műveletre.
500	Belső hiba	Hiba történt a szolgáltatásban.
503	Hibás átjáró	A kérés nem irányítható egyetlen figyelőhöz sem.
504	Átjáró időtúllépése	A kérést egy figyelőhöz irányították, de a figyelő nem nyugtázta a visszaigazolást a szükséges időben.

Azure Relay Hybrid Csatlakozás ions protokoll

Interakciós modell

Figyelők interakciói

Üzenet figyelés

Üzenet elfogadása

Üzenet kérése

Művelet megújítása

Pingelési művelet

A feladó interakciója

Csatlakozás művelet

Kérelemművelet

Interakciók összegzése

Protokollhivatkozás

Figyelő protokoll

Figyelővezérlő csatornakapcsolata

Kézfogás elfogadása

A szoftvercsatorna elfogadása

A szoftvercsatorna elvetése

Üzenet kérése

Válaszadás a kérelmekre

Válaszadás rendezvous-on keresztül

Figyelő jogkivonat megújítása

Web Socket connect protokoll

HTTP-kérelem protokollja

Következő lépések

További források