Protocol voor hybride Verbinding maken van Azure Relay

  • Artikel

Azure Relay is een van de belangrijkste pijlers van het Azure Service Bus-platform. De nieuwe mogelijkheid voor hybride Verbinding maken ions van Relay is een veilige open-protocolontwikkeling op basis van HTTP en WebSockets. Het vervangt de voormalige, even benoemde BizTalk Services-functie die is gebouwd op een eigen protocolbasis. De integratie van hybrid Verbinding maken ions in Azure-app Services blijft functioneren.

Hybride Verbinding maken ions maken bidirectionele communicatie, aanvraag-antwoord en binaire stroomcommunicatie mogelijk, en eenvoudige datagramstroom tussen twee netwerktoepassingen. Beide partijen kunnen zich achter NAT's of firewalls bevinden.

In dit artikel worden de interacties aan de clientzijde beschreven met de Hybrid Verbinding maken ions Relay voor het verbinden van clients in listener- en afzenderrollen. Ook wordt beschreven hoe listeners nieuwe verbindingen en aanvragen accepteren.

Interactiemodel

De Hybrid Verbinding maken ions Relay verbindt twee partijen door een rendezvous-punt in de Azure-cloud te bieden waarmee partijen vanuit hun eigen netwerk kunnen detecteren en er verbinding mee kunnen maken. Het rendez-vouspunt wordt hybride Verbinding maken ion genoemd in deze en andere documentatie, in de API's en ook in Azure Portal. Het service-eindpunt voor hybride Verbinding maken ionen wordt de 'service' genoemd voor de rest van dit artikel.

De service maakt het mogelijk om Web Socket-verbindingen en HTTP(S)-aanvragen en -antwoorden door te sturen.

Het interactiemodel leunt op de nomenclatuur die door vele andere netwerk-API's is vastgesteld. Er is een listener die eerst de gereedheid aangeeft om binnenkomende verbindingen af te handelen en deze vervolgens accepteert wanneer ze binnenkomen. Aan de andere kant maakt een client verbinding met de listener, waarbij wordt verwacht dat deze verbinding wordt geaccepteerd voor het tot stand brengen van een bidirectioneel communicatiepad. 'Verbinding maken', 'Luisteren' en 'Accepteren' zijn dezelfde termen die u in de meeste socket-API's vindt.

Elk relay-communicatiemodel heeft een van beide partijen die uitgaande verbindingen naar een service-eindpunt maken. Dit maakt de 'listener' ook een 'client' in colloquiaal gebruik en kan ook andere terminologieoverbelastingen veroorzaken. De exacte terminologie die daarom wordt gebruikt voor hybride Verbinding maken ionen is als volgt:

De programma's aan beide zijden van een verbinding worden clients genoemd, omdat ze clients voor de service zijn. De client die wacht op en accepteert verbindingen is de 'listener', of wordt gezegd dat deze zich in de 'listenerrol' bevindt. De client die via de service een nieuwe verbinding naar een listener initieert, wordt de 'afzender' genoemd of heeft de 'afzenderrol'.

Interacties van listener

De listener heeft vijf interacties met de service; alle draaddetails worden verderop in dit artikel in de naslagsectie beschreven.

De berichten Luisteren, Accepteren en Aanvragen worden ontvangen van de service. De bewerkingen Vernieuwen en Ping worden verzonden door de listener.

Bericht beluisteren

Om aan te geven dat een listener gereed is voor het accepteren van verbindingen, wordt er een uitgaande WebSocket-verbinding gemaakt. De verbindingshanddruk heeft de naam van een hybride Verbinding maken ion die is geconfigureerd in de Relay-naamruimte en een beveiligingstoken dat de naam 'Luisteren' aan die naam verleent.

Wanneer de WebSocket wordt geaccepteerd door de service, wordt de registratie voltooid en blijft de gevestigde WebSocket actief als het 'besturingskanaal' voor het inschakelen van alle volgende interacties. De service biedt maximaal 25 gelijktijdige listeners voor één hybride Verbinding maken ion. Het quotum voor AppHooks moet worden bepaald.

Voor hybride Verbinding maken ionen, als er twee of meer actieve listeners zijn, worden binnenkomende verbindingen in willekeurige volgorde verdeeld. Er wordt geprobeerd om eerlijk te verdelen met het beste vermogen.

Bericht accepteren

Wanneer een afzender een nieuwe verbinding voor de service opent, kiest en meldt de service een van de actieve listeners op de hybride Verbinding maken ion. Deze melding wordt naar de listener verzonden via het open besturingskanaal als een JSON-bericht. Het bericht bevat de URL van het WebSocket-eindpunt waarmee de listener verbinding moet maken om de verbinding te accepteren.

De URL kan en moet rechtstreeks door de listener worden gebruikt zonder extra werk. De gecodeerde informatie is slechts gedurende een korte periode geldig, in wezen zolang de afzender bereid is te wachten tot de verbinding tot stand is gebracht. Het maximum dat moet worden aangenomen, is 30 seconden. De URL kan slechts worden gebruikt voor één geslaagde verbindingspoging. Zodra de WebSocket-verbinding met de rendezvous-URL tot stand is gebracht, wordt alle verdere activiteit op deze WebSocket doorgestuurd van en naar de afzender. Dit gedrag gebeurt zonder tussenkomst of interpretatie door de service.

Bericht aanvragen

Naast WebSocket-verbindingen kan de listener ook HTTP-aanvraagframes van een afzender ontvangen als deze mogelijkheid expliciet is ingeschakeld op de Hybride Verbinding maken ion.

Listeners die zijn gekoppeld aan hybride Verbinding maken ions met HTTP-ondersteuning, moeten de request beweging afhandelen. Een listener die niet wordt verwerkt request en waardoor herhaalde time-outfouten optreden terwijl er verbinding wordt gemaakt, kan in de toekomst door de service worden geblokkeerd.

Metagegevens van HTTP-frameheaders worden omgezet in JSON voor eenvoudigere verwerking door het listenerframework, ook omdat http-headerparseringsbibliotheken zeldzaam zijn dan JSON-parsers. HTTP-metagegevens die alleen relevant zijn voor de relatie tussen de afzender en de Relay HTTP-gateway, inclusief autorisatiegegevens, worden niet doorgestuurd. HTTP-aanvraagteksten worden transparant overgedragen als binaire WebSocket-frames.

De listener kan reageren op HTTP-aanvragen met behulp van een equivalente reactiebeweging.

De aanvraag-/antwoordstroom maakt standaard gebruik van het besturingskanaal, maar kan indien nodig worden geüpgraded naar een afzonderlijke rendezvous WebSocket. Afzonderlijke WebSocket-verbindingen verbeteren de doorvoer voor elk clientgesprek, maar ze belasten de listener met meer verbindingen die moeten worden verwerkt, wat mogelijk niet geschikt is voor lichtgewicht clients.

Op het besturingskanaal zijn aanvraag- en antwoordteksten beperkt tot maximaal 64 kB in grootte. Metagegevens van HTTP-headers zijn beperkt tot in totaal 32 kB. Als de aanvraag of het antwoord deze drempelwaarde overschrijdt, moet de listener upgraden naar een rendezvous WebSocket met behulp van een gebaar dat gelijk is aan het verwerken van de Accept.

Voor aanvragen bepaalt de service of aanvragen via het besturingskanaal moeten worden gerouteerd. Dit omvat, maar is mogelijk niet beperkt tot gevallen waarin een aanvraag groter is dan 64 kB (headers plus hoofdtekst) of als de aanvraag wordt verzonden met 'gesegmenteerde' overdrachtscodering en de service reden heeft om te verwachten dat de aanvraag groter is dan 64 kB of het lezen van de aanvraag niet onmiddellijk is. Als de service ervoor kiest om de aanvraag via rendezvous af te leveren, wordt alleen het rendezvous-adres doorgegeven aan de listener. De listener moet vervolgens de rendezvous WebSocket tot stand brengen en de service levert onmiddellijk de volledige aanvraag, inclusief lichamen via de rendezvous WebSocket. Het antwoord MOET ook gebruikmaken van de rendezvous WebSocket.

Voor aanvragen die via het controlekanaal binnenkomen, bepaalt de listener of moet reageren via het controlekanaal of via rendezvous. De service MOET een rendez-vous-adres bevatten met elke aanvraag die via het controlekanaal wordt gerouteerd. Dit adres is alleen geldig voor het upgraden van de huidige aanvraag.

Als de listener ervoor kiest om een upgrade uit te voeren, maakt deze verbinding en levert deze prompt het antwoord via de bestaande rendezvous-socket.

Zodra de rendezvous WebSocket is ingesteld, moet de listener deze onderhouden voor verdere verwerking van aanvragen en antwoorden van dezelfde client. De service onderhoudt de WebSocket zolang de HTTPS-socketverbinding met de afzender zich blijft voordoen en alle volgende aanvragen van die afzender via de onderhouden WebSocket worden doorgestuurd. Als de listener ervoor kiest om de rendezvous WebSocket van de kant te verwijderen, wordt de verbinding met de afzender ook verwijderd, ongeacht of er al een volgende aanvraag wordt uitgevoerd.

Bewerking vernieuwen

Het beveiligingstoken dat moet worden gebruikt om de listener te registreren en het besturingskanaal te onderhouden, kan verlopen terwijl de listener actief is. Het verlopen van het token heeft geen invloed op lopende verbindingen, maar zorgt er wel voor dat het besturingskanaal wordt verwijderd door de service op of kort na het verstrijken van het tijdstip. De bewerking Vernieuwen is een JSON-bericht dat de listener kan verzenden om het token dat is gekoppeld aan het besturingskanaal te vervangen, zodat het besturingskanaal gedurende langere perioden kan worden onderhouden.

Pingbewerking

Als het besturingskanaal gedurende lange tijd inactief blijft, kunnen tussenpersonen op de weg, zoals load balancers of NAT's, de TCP-verbinding verwijderen. De ping-bewerking voorkomt dat door een kleine hoeveelheid gegevens op het kanaal te verzenden die iedereen op de netwerkroute eraan herinnert dat de verbinding bedoeld is om in leven te zijn, en het fungeert ook als een 'live'-test voor de listener. Als de ping mislukt, moet het besturingskanaal als onbruikbaar worden beschouwd en moet de listener opnieuw verbinding maken.

Interactie met afzender

De afzender heeft twee interacties met de service: hiermee wordt een websocket verbonden of worden aanvragen via HTTPS verzonden. Aanvragen kunnen niet via een websocket worden verzonden vanuit de rol van afzender.

Verbinding maken bewerking

Met de bewerking Verbinding maken wordt een WebSocket in de service geopend, waarbij de naam van de hybride Verbinding maken ion wordt opgegeven en (optioneel, maar standaard vereist) een beveiligingstoken met de machtiging Verzenden in de querytekenreeks. De service communiceert vervolgens met de listener op de eerder beschreven manier en de listener maakt een rendezvous-verbinding die is gekoppeld aan deze WebSocket. Nadat de WebSocket is geaccepteerd, zijn alle verdere interacties in die WebSocket met een verbonden listener.

Aanvraagbewerking

Voor hybride Verbinding maken ions waarvoor de functie is ingeschakeld, kan de afzender grotendeels onbeperkte HTTP-aanvragen verzenden naar listeners.

Behalve een Relay-toegangstoken dat is ingesloten in de querytekenreeks of in een HTTP-header van de aanvraag, is de Relay volledig transparant voor alle HTTP-bewerkingen op het Relay-adres en alle achtervoegsels van het Relay-adrespad, waardoor de listener volledig controle heeft over end-to-end-autorisatie en zelfs HTTP-extensiefuncties zoals CORS.

Autorisatie van afzenders met het Relay-eindpunt is standaard ingeschakeld, maar is optioneel. De eigenaar van de Hybride Verbinding maken ion kan ervoor kiezen anonieme afzenders toe te staan. De service onderschept, inspecteert en stript autorisatiegegevens als volgt:

  1. Als de querytekenreeks een sb-hc-token expressie bevat, wordt de expressie ALTIJD verwijderd uit de querytekenreeks. Deze wordt geëvalueerd als Relay-autorisatie is ingeschakeld.
  2. Als de aanvraagheaders een ServiceBusAuthorization koptekst bevatten, wordt de header-expressie ALTIJD verwijderd uit de headerverzameling. Deze wordt geëvalueerd als Relay-autorisatie is ingeschakeld.
  3. Alleen als Relay-autorisatie is ingeschakeld en als de aanvraagheaders een Authorization header bevatten en geen van de voorgaande expressies aanwezig is, wordt de header geëvalueerd en verwijderd. Anders wordt het Authorizationaltijd doorgegeven zoals het is.

Als er geen actieve listener is, retourneert de service de foutcode 502 'Ongeldige gateway'. Als de service de aanvraag niet verwerkt, retourneert de service na 60 seconden een time-out van 504 'Gatewaytime-out'.

Interactiesamenvatting

Het resultaat van dit interactiemodel is dat de afzenderclient uit de handshake komt met een 'schone' WebSocket, die is verbonden met een listener en dat geen verdere preparaten of voorbereiding nodig heeft. Met dit model kan vrijwel elke bestaande WebSocket-client-implementatie direct profiteren van de service Hybride Verbinding maken ions door een correct samengestelde URL op te geven in hun WebSocket-clientlaag.

De rendezvous connection WebSocket die de listener verkrijgt via de acceptinteractie is ook schoon en kan worden overgedragen aan elke bestaande WebSocket-server-implementatie met een minimale extra abstractie die onderscheid maakt tussen 'accepteren'-bewerkingen op de lokale netwerklisteners van hun framework en hybride Verbinding maken ions externe 'accepteren'-bewerkingen.

Het HTTP-aanvraag-/antwoordmodel geeft de afzender een grotendeels onbeperkte oppervlakte van het HTTP-protocol met een OPTIONELE autorisatielaag. De listener krijgt een vooraf geparseerde sectie http-aanvraagheader die kan worden teruggezet naar een downstream HTTP-aanvraag of verwerkt zoals dat is, met binaire frames met HTTP-lichamen. Antwoorden gebruiken dezelfde indeling. Interacties met minder dan 64 kB aan aanvraag- en antwoordtekst kunnen worden verwerkt via één websocket die wordt gedeeld voor alle afzenders. Grotere aanvragen en antwoorden kunnen worden verwerkt met behulp van het rendezvous-model.

Protocolreferentie

In deze sectie worden de details beschreven van de eerder beschreven protocolinteracties.

Alle WebSocket-verbindingen worden gemaakt op poort 443 als een upgrade van HTTPS 1.1. Dit wordt meestal geabstraheerd door een WebSocket-framework of API. De beschrijving hier blijft implementatieneutraal, zonder een specifiek framework voor te stellen.

Listener-protocol

Het listenerprotocol bestaat uit twee verbindingsbewegingen en drie berichtbewerkingen.

Listener-kanaalverbinding

Het besturingskanaal wordt geopend met het maken van een WebSocket-verbinding met:

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

Dit namespace-address is de volledig gekwalificeerde domeinnaam van de Azure Relay-naamruimte die als host fungeert voor de hybride Verbinding maken ion, meestal van de vorm{myname}.servicebus.windows.net.

De parameteropties voor queryreeksen zijn als volgt.

Parameter Vereist Omschrijving
sb-hc-action Ja Voor de listener-rol moet de parameter sb-hc-action=listen zijn
{path} Ja Het pad naar de naamruimte met URL-codering van de vooraf geconfigureerde Hybride Verbinding maken ion waarop deze listener moet worden geregistreerd. Deze expressie wordt toegevoegd aan het gedeelte met het vaste $hc/ pad.
sb-hc-token Ja* De listener moet een geldig, MET URL gecodeerd Service Bus Shared Access Token opgeven voor de naamruimte of hybrid Verbinding maken ion die het listen-recht verleent.
sb-hc-id Nee Deze door de client geleverde optionele id maakt end-to-end diagnostische tracering mogelijk.

Als de WebSocket-verbinding mislukt omdat het pad voor hybride Verbinding maken ion niet is geregistreerd, of een ongeldig of ontbrekend token, of een andere fout, wordt de foutfeedback verstrekt met behulp van het normale HTTP 1.1-statusfeedbackmodel. De statusbeschrijving bevat een id voor fouttracking die kan worden gecommuniceerd aan ondersteuning voor Azure personeel:

Code Fout Omschrijving
404 Niet gevonden Het pad voor hybride Verbinding maken ion is ongeldig of de basis-URL is ongeldig.
401 Niet geautoriseerd Het beveiligingstoken ontbreekt of is ongeldig of ongeldig.
403 Verboden Het beveiligingstoken is niet geldig voor dit pad voor deze actie.
500 Interne fout Er is iets misgegaan in de service.

Als de WebSocket-verbinding opzettelijk wordt afgesloten door de service nadat deze in eerste instantie is ingesteld, wordt de reden hiervoor gecommuniceerd met behulp van een geschikte Foutcode van het WebSocket-protocol, samen met een beschrijvend foutbericht dat ook een tracerings-id bevat. De service sluit het besturingskanaal niet af zonder dat er een foutvoorwaarde optreedt. Elke schone afsluiting wordt door de client beheerd.

WS-status Omschrijving
1001 Het pad voor hybride Verbinding maken ion is verwijderd of uitgeschakeld.
1008 Het beveiligingstoken is verlopen, waardoor het autorisatiebeleid wordt geschonden.
1011 Er is iets misgegaan in de service.

Handshake accepteren

De melding 'accepteren' wordt door de service naar de listener verzonden via het eerder tot stand gebrachte besturingskanaal als een JSON-bericht in een WebSocket-tekstframe. Er is geen antwoord op dit bericht.

Het bericht bevat een JSON-object met de naam 'accepteren', waarmee de volgende eigenschappen op dit moment worden gedefinieerd:

  • adres : de URL-tekenreeks die moet worden gebruikt voor het tot stand brengen van de WebSocket voor de service om een binnenkomende verbinding te accepteren.
  • id : de unieke id voor deze verbinding. Als de id is opgegeven door de afzenderclient, is dit de opgegeven waarde van de afzender, anders is het een door het systeem gegenereerde waarde.
  • connectHeaders : alle HTTP-headers die door de afzender aan het Relay-eindpunt zijn opgegeven, waaronder ook de headers Sec-WebSocket-Protocol en 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" : "..."
        }
     }
}

De adres-URL die in het JSON-bericht wordt opgegeven, wordt door de listener gebruikt om de WebSocket tot stand te brengen voor het accepteren of weigeren van de afzendersocket.

De socket accepteren

Om te accepteren, brengt de listener een WebSocket-verbinding tot stand met het opgegeven adres.

Als het bericht 'accepteren' een Sec-WebSocket-Protocol koptekst bevat, wordt verwacht dat de listener alleen de WebSocket accepteert als dit protocol wordt ondersteund. Daarnaast wordt de header ingesteld als de WebSocket tot stand is gebracht.

Hetzelfde geldt voor de Sec-WebSocket-Extensions koptekst. Als het framework een extensie ondersteunt, moet de header worden ingesteld op het antwoord aan de serverzijde van de vereiste Sec-WebSocket-Extensions handshake voor de extensie.

De URL moet worden gebruikt om de accept-socket tot stand te brengen, maar bevat de volgende parameters:

Parameter Vereist Omschrijving
sb-hc-action Ja Voor het accepteren van een socket moet de parameter zijn sb-hc-action=accept
{path} Ja (zie de volgende alinea)
sb-hc-id Nee Zie de vorige beschrijving van de id.

{path}is het url-gecodeerde naamruimtepad van de vooraf geconfigureerde hybride Verbinding maken ion waarop deze listener moet worden geregistreerd. Deze expressie wordt toegevoegd aan het gedeelte met het vaste $hc/ pad.

De path expressie kan worden uitgebreid met een achtervoegsel en een querytekenreeksexpressie die de geregistreerde naam volgt na een gescheiden slash. Met deze parameter kan de afzenderclient verzendargumenten doorgeven aan de accepterende listener wanneer het niet mogelijk is OM HTTP-headers op te nemen. De verwachting is dat het listenerframework het vaste padgedeelte en de geregistreerde naam van het pad parseert en de rest, mogelijk zonder argumenten voor queryreeksen voorafgegaan door sb-, beschikbaar maakt voor de toepassing om te bepalen of de verbinding moet worden geaccepteerd.

Zie de volgende sectie 'Sender Protocol' voor meer informatie.

Als er een fout optreedt, kan de service als volgt reageren:

Code Fout Omschrijving
403 Verboden De URL is niet geldig.
500 Interne fout Er is iets misgegaan in de service

Nadat de verbinding tot stand is gebracht, sluit de server de WebSocket af wanneer de afzender WebSocket wordt afgesloten of met de volgende status:

WS-status Omschrijving
1001 De afzenderclient sluit de verbinding af.
1001 Het pad voor hybride Verbinding maken ion is verwijderd of uitgeschakeld.
1008 Het beveiligingstoken is verlopen, waardoor het autorisatiebeleid wordt geschonden.
1011 Er is iets misgegaan in de service.
De socket weigeren

Voor het weigeren van de socket nadat het accept bericht is geïnspecteerd, is een vergelijkbare handshake vereist, zodat de statuscode en statusbeschrijving die de reden voor de afwijzing aangeeft, weer naar de afzender kunnen stromen.

De keuze voor protocolontwerp is om een WebSocket-handshake te gebruiken (die is ontworpen om te eindigen op een gedefinieerde foutstatus) zodat listenerclient-implementaties kunnen blijven vertrouwen op een WebSocket-client en geen extra, lege HTTP-client hoeven te gebruiken.

Als u de socket wilt weigeren, neemt de client de adres-URI van het accept bericht en voegt deze als volgt twee queryreeksparameters toe:

Param Vereist Beschrijving
sb-hc-statusCode Ja Numerieke HTTP-statuscode.
sb-hc-statusDescription Ja Menselijke leesbare reden voor de afwijzing.

De resulterende URI wordt vervolgens gebruikt om een WebSocket-verbinding tot stand te brengen.

Bij het correct voltooien mislukt deze handshake opzettelijk met een HTTP-foutcode 410, omdat er geen WebSocket is ingesteld. Als er iets misgaat, beschrijven de volgende codes de fout:

Code Fout Omschrijving
403 Verboden De URL is niet geldig.
500 Interne fout Er is iets misgegaan in de service.

Bericht aanvragen

Het request bericht wordt door de service naar de listener verzonden via het besturingskanaal. Hetzelfde bericht wordt ook verzonden via de rendezvous WebSocket eenmaal tot stand gebracht.

Het request bestaat uit twee delen: een koptekst en binaire hoofdtekstframe(s). Als er geen hoofdtekst is, worden de hoofdframes weggelaten. De booleaanse body eigenschap geeft aan of een hoofdtekst aanwezig is in het aanvraagbericht.

Voor een aanvraag met een aanvraagbody kan de structuur er als volgt uitzien:

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

De listener MOET het ontvangen van de aanvraagbody splitsen over meerdere binaire frames (zie WebSocket-fragmenten). De aanvraag eindigt wanneer een binair frame met de FIN-vlagset is ontvangen.

Voor een aanvraag zonder hoofdtekst is er slechts één tekstkader.

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

De JSON-inhoud voor request is als volgt:

  • adres - URI-tekenreeks. Het is het rendezvous-adres dat voor deze aanvraag moet worden gebruikt. Als de binnenkomende aanvraag groter is dan 64 kB, blijft de rest van dit bericht leeg en moet de client een rendez-vous handshake starten die gelijk is aan de accept hieronder beschreven bewerking. De service plaatst vervolgens het volledige request op de bestaande websocket. Als het antwoord naar verwachting groter is dan 64 kB, moet de listener ook een rendez-vous handshake initiëren en vervolgens het antwoord overdragen via de bestaande websocket.

  • id – tekenreeks. De unieke id voor deze aanvraag.

  • requestHeaders: dit object bevat alle HTTP-headers die door de afzender aan het eindpunt zijn verstrekt, met uitzondering van autorisatie-informatie zoals hierboven uitgelegd, en headers die strikt betrekking hebben op de verbinding met de gateway. In het bijzonder worden ALLE headers die zijn gedefinieerd of gereserveerd in RFC7230, met uitzondering Viavan, verwijderd en niet doorgestuurd:

    • Connection (RFC7230, sectie 6.1)
    • Content-Length (RFC7230, sectie 3.3.2)
    • Host (RFC7230, sectie 5.4)
    • TE (RFC7230, sectie 4.3)
    • Trailer (RFC7230, sectie 4.4)
    • Transfer-Encoding (RFC7230, sectie 3.3.1)
    • Upgrade (RFC7230, sectie 6.7)
    • Close (RFC7230, sectie 8.1)

  • requestTarget – tekenreeks. Deze eigenschap bevat het aanvraagdoel (RFC7230, sectie 5.3) van de aanvraag. Het bevat het querytekenreeksgedeelte, dat is verwijderd van alle sb-hc- parameters met voorvoegsels.

  • methode - tekenreeks. Dit is de methode van de aanvraag, per RFC7231, sectie 4. De CONNECT methode MAG NIET worden gebruikt.

  • body – Booleaanse waarde. Geeft aan of een of meer binaire hoofdtekstframes volgen.

{
    "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
     }
}
Reageren op aanvragen

De ontvanger MOET reageren. Herhaalde mislukte reactie op aanvragen terwijl de verbinding wordt onderhouden, kan ertoe leiden dat de listener wordt geblokkeerd.

Antwoorden kunnen in elke volgorde worden verzonden, maar elke aanvraag moet binnen 60 seconden worden beantwoord of de levering wordt gerapporteerd als mislukt. De deadline van 60 seconden wordt geteld totdat het response frame door de service is ontvangen. Een doorlopend antwoord met meerdere binaire frames kan niet langer dan 60 seconden inactief worden of wordt beëindigd.

Als de aanvraag wordt ontvangen via het controlekanaal, moet het antwoord worden verzonden op het besturingskanaal van waaruit de aanvraag is ontvangen of moet het worden verzonden via een rendezvous-kanaal.

Het antwoord is een JSON-object met de naam 'response'. De regels voor het verwerken van hoofdtekstinhoud zijn precies hetzelfde als bij het request bericht en op basis van de body eigenschap.

  • requestId – tekenreeks. VEREIST. De id eigenschapswaarde van het request bericht dat wordt beantwoord.
  • statusCode – getal. VEREIST. een numerieke HTTP-statuscode die het resultaat van de melding aangeeft. Alle statuscodes van RFC7231, sectie 6 zijn toegestaan, met uitzondering van 502 'Ongeldige gateway' en 504 'Time-out van gateway'.
  • statusDescription - tekenreeks. OPTIONELE. Redenzin voor HTTP-statuscode per RFC7230, sectie 3.1.2
  • responseHeaders : HTTP-headers die moeten worden ingesteld in een extern HTTP-antwoord. Net als bij de requestgedefinieerde RFC7230 headers MOGEN NIET worden gebruikt.
  • body – Booleaanse waarde. Geeft aan of binaire bodyframe(s) volgen(en).
----- 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" }
----------------------------------
Reageren via rendezvous

Voor antwoorden die groter zijn dan 64 kB, moet het antwoord worden geleverd via een rendezvous-socket. Als de aanvraag groter is dan 64 kB en het request enige adresveld bevat, moet er een rendez-vous-socket worden vastgesteld om de requestaanvraag te verkrijgen. Zodra een rendez-vous socket is vastgesteld, moeten reacties op de respectieve client en volgende verzoeken van die respectieve client worden geleverd via de rendezvous socket terwijl deze zich blijft voordoen.

De address URL in de request url moet worden gebruikt om de rendezvous-socket tot stand te brengen, maar bevat de volgende parameters:

Parameter Vereist Omschrijving
sb-hc-action Ja Voor het accepteren van een socket moet de parameter zijn sb-hc-action=request

Als er een fout optreedt, kan de service als volgt reageren:

Code Fout Description
400 Ongeldige aanvraag Niet-herkende actie of URL is ongeldig.
403 Verboden De URL is verlopen.
500 Interne fout Er is iets misgegaan in de service

Nadat de verbinding tot stand is gebracht, sluit de server de WebSocket af wanneer de HTTP-socket van de client wordt afgesloten of met de volgende status:

WS-status Omschrijving
1001 De afzenderclient sluit de verbinding af.
1001 Het pad voor hybride Verbinding maken ion is verwijderd of uitgeschakeld.
1008 Het beveiligingstoken is verlopen, waardoor het autorisatiebeleid wordt geschonden.
1011 Er is iets misgegaan in de service.

Vernieuwing van listenertoken

Wanneer het listenertoken bijna verloopt, kan het worden vervangen door een tekstframebericht naar de service te verzenden via het tot stand gebrachte besturingskanaal. Het bericht bevat een JSON-object met de naam renewToken, waarmee de volgende eigenschap op dit moment wordt gedefinieerd:

  • token: een geldig, met URL gecodeerd Service Bus Shared Access-token voor de naamruimte of hybride Verbinding maken ion die het luisterrecht verleent.
{
  "renewToken": {
    "token":
      "SharedAccessSignature sr=http%3a%2f%2fcontoso.servicebus.windows.net%2fhyco%2f&sig=XXXXXXXXXX%3d&se=1471633754&skn=SasKeyName"
  }
}

Als de tokenvalidatie mislukt, wordt de toegang geweigerd en sluit de cloudservice het beheerkanaal WebSocket met een fout. Anders is er geen antwoord.

WS-status Omschrijving
1008 Het beveiligingstoken is verlopen, waardoor het autorisatiebeleid wordt geschonden.

Web Socket Connect-protocol

Het afzenderprotocol is in feite identiek aan de manier waarop een listener tot stand is gebracht. Het doel is maximale transparantie voor de end-to-end WebSocket. Het adres waarmee verbinding moet worden gemaakt, is hetzelfde als voor de listener, maar de actie verschilt en het token heeft een andere machtiging nodig:

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

Het naamruimteadres is de volledig gekwalificeerde domeinnaam van de Azure Relay-naamruimte die als host fungeert voor de Hybrid Verbinding maken ion, meestal van het formulier{myname}.servicebus.windows.net.

De aanvraag kan willekeurige extra HTTP-headers bevatten, inclusief door de toepassing gedefinieerde headers. Alle opgegeven headersstroom naar de listener en zijn te vinden op het connectHeader object van het besturingsbericht accepteren .

De parameteropties voor queryreeksen zijn als volgt:

Param Vereist? Omschrijving
sb-hc-action Ja Voor de afzenderrol moet de parameter zijn sb-hc-action=connect.
{path} Ja (zie de volgende alinea)
sb-hc-token Ja* De listener moet een geldig, MET URL gecodeerd Service Bus Shared Access Token opgeven voor de naamruimte of hybrid Verbinding maken ion die het recht Verzenden verleent.
sb-hc-id Nee Een optionele id die end-to-end diagnostische tracering mogelijk maakt en beschikbaar wordt gesteld aan de listener tijdens de accept handshake.

Dit {path} is het url-gecodeerde naamruimtepad van de vooraf geconfigureerde hybride Verbinding maken ion waarop deze listener moet worden geregistreerd. De path expressie kan worden uitgebreid met een achtervoegsel en een querytekenreeksexpressie om verder te communiceren. Als de hybride Verbinding maken ion is geregistreerd onder het padhyco, kan de path expressie worden hyco/suffix?param=value&... gevolgd door de hier gedefinieerde queryreeksparameters. Een volledige expressie kan dan als volgt zijn:

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

De path expressie wordt doorgegeven aan de listener in de adres-URI in het besturingselement 'accepteren'.

Als de WebSocket-verbinding mislukt omdat het pad voor hybride Verbinding maken ion niet is geregistreerd, een ongeldig token of een andere fout, wordt de foutfeedback verstrekt met behulp van het normale HTTP 1.1-statusfeedbackmodel. De statusbeschrijving bevat een id voor fouttracking die kan worden gecommuniceerd met ondersteuning voor Azure personeel:

Code Fout Omschrijving
404 Niet gevonden Het pad voor hybride Verbinding maken ion is ongeldig of de basis-URL is ongeldig.
401 Niet geautoriseerd Het beveiligingstoken ontbreekt of is ongeldig of ongeldig.
403 Verboden Het beveiligingstoken is niet geldig voor dit pad en voor deze actie.
500 Interne fout Er is iets misgegaan in de service.

Als de WebSocket-verbinding opzettelijk wordt afgesloten door de service nadat deze in eerste instantie is ingesteld, wordt de reden hiervoor gecommuniceerd met behulp van een geschikte Foutcode van het WebSocket-protocol, samen met een beschrijvend foutbericht dat ook een tracerings-id bevat.

WS-status Omschrijving
1000 De listener sluit de socket af.
1001 Het pad voor hybride Verbinding maken ion is verwijderd of uitgeschakeld.
1008 Het beveiligingstoken is verlopen, zodat het autorisatiebeleid wordt geschonden.
1011 Er is iets misgegaan in de service.

HTTP-aanvraagprotocol

Het HTTP-aanvraagprotocol staat willekeurige HTTP-aanvragen toe, met uitzondering van protocolupgrades. HTTP-aanvragen worden verwezen naar het reguliere runtime-adres van de entiteit, zonder het $hc invoegsel dat wordt gebruikt voor hybride verbindingen WebSocket-clients.

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

Het naamruimteadres is de volledig gekwalificeerde domeinnaam van de Azure Relay-naamruimte die als host fungeert voor de Hybrid Verbinding maken ion, meestal van het formulier{myname}.servicebus.windows.net.

De aanvraag kan willekeurige extra HTTP-headers bevatten, inclusief door de toepassing gedefinieerde headers. Alle opgegeven headers, behalve de headers die rechtstreeks zijn gedefinieerd in RFC7230 (zie Aanvraagbericht) naar de listener en zijn te vinden op het requestHeader object van het aanvraagbericht .

De parameteropties voor queryreeksen zijn als volgt:

Param Vereist? Omschrijving
sb-hc-token Ja* De listener moet een geldig, MET URL gecodeerd Service Bus Shared Access Token opgeven voor de naamruimte of hybrid Verbinding maken ion die het recht Verzenden verleent.

Het token kan ook worden meegenomen in de ServiceBusAuthorization of Authorization HTTP-header. Het token kan worden weggelaten als de hybride Verbinding maken ion is geconfigureerd om anonieme aanvragen toe te staan.

Omdat de service effectief als proxy fungeert, zelfs als deze niet als een echte HTTP-proxy fungeert, wordt er een Via header toegevoegd of aantekeningen toegevoegd aan de bestaande Via header die voldoet aan RFC7230, sectie 5.7.1. De service voegt de hostnaam van de Relay-naamruimte toe aan Via.

Code Bericht Omschrijving
200 OK De aanvraag is verwerkt door ten minste één listener.
202 Geaccepteerd De aanvraag is geaccepteerd door ten minste één listener.

Als er een fout optreedt, kan de service als volgt reageren. Of het antwoord afkomstig is van de service of van de listener, kan worden geïdentificeerd via de aanwezigheid van de Via header. Als de header aanwezig is, is het antwoord afkomstig van de listener.

Code Fout Omschrijving
404 Niet gevonden Het pad voor hybride Verbinding maken ion is ongeldig of de basis-URL is ongeldig.
401 Niet geautoriseerd Het beveiligingstoken ontbreekt of is ongeldig of ongeldig.
403 Verboden Het beveiligingstoken is niet geldig voor dit pad en voor deze actie.
500 Interne fout Er is iets misgegaan in de service.
503 Ongeldige gateway De aanvraag kan niet worden doorgestuurd naar een listener.
504 Time-out van gateway De aanvraag is doorgestuurd naar een listener, maar de listener heeft het ontvangstbewijs niet binnen de vereiste tijd bevestigd.

Volgende stappen