Protocollo per le connessioni ibride di inoltro di AzureAzure Relay Hybrid Connections protocol

L'inoltro di Azure è una delle funzionalità chiave di base della piattaforma Bus di servizio di Azure.Azure Relay is one of the key capability pillars of the Azure Service Bus platform. La nuova funzionalità Connessioni ibride di inoltro è un'evoluzione sicura del protocollo aperto basata su HTTP e WebSocket.The new Hybrid Connections capability of Relay is a secure, open-protocol evolution based on HTTP and WebSockets. Sostituisce la funzionalità precedente, comunemente denominata Servizi BizTalk, che è basata su un protocollo di proprietà.It supersedes the former, equally named BizTalk Services feature that was built on a proprietary protocol foundation. L'integrazione di Connessioni ibride nei servizi app di Azure continuerà a funzionare così com'è.The integration of Hybrid Connections into Azure App Services will continue to function as-is.

Connessioni ibride permette di stabilire una comunicazione bidirezionale con flussi binari tra due applicazioni di rete,Hybrid Connections enables bi-directional, binary stream communication and simple datagram flow between two networked applications. di cui una o entrambe le parti sono protette da NAT o firewall.Either or both parties can reside behind NATs or firewalls.

Questo articolo descrive le interazioni lato client con l'inoltro di Connessioni ibride per la connessione dei client nei ruoli listener e mittenteThis article describes the client-side interactions with the Hybrid Connections relay for connecting clients in listener and sender roles. e il modo in cui i listener accettano nuove connessioni e richieste.It also describes how listeners accept new connections and requests.

Modello di interazioneInteraction model

L'inoltro di Connessioni ibride connette due parti tramite un punto di incontro nel cloud di Azure che le parti possono individuare e a cui possono connettersi dalla rispettiva rete.The Hybrid Connections relay connects two parties by providing a rendezvous point in the Azure cloud that parties can discover and connect to from their own network’s perspective. Tale punto di incontro è detto "connessione ibrida" in questo e in altri documenti, nelle API e nel portale di Azure.The rendezvous point is called "Hybrid Connection" in this and other documentation, in the APIs, and also in the Azure portal. L'endpoint di servizio di Connessioni ibride viene chiamato "servizio" nella parte restante di questo articolo.The Hybrid Connections service endpoint is referred to as the "service" for the rest of this article.

Il servizio consente di inoltrare connessioni WebSocket e richieste e risposte HTTP/HTTPS.The service allows for relaying Web Socket connections and HTTP(S) requests and responses.

Il modello di interazione si basa sulla nomenclatura stabilita da diverse altre API di rete.The interaction model leans on the nomenclature established by many other networking APIs. È presente un listener che prima indica la conformità alla gestione delle connessioni in ingresso e successivamente le accetta quando arrivano.There is a listener that first indicates readiness to handle incoming connections, and subsequently accepts them as they arrive. Sull'altro lato un client si connette al listener, aspettando che la connessione venga accettata per stabilire un percorso di comunicazione bidirezionale.On the other side, a client connects towards the listener, expecting that connection to be accepted for establishing a bi-directional communication path. "Connettersi", "essere in ascolto", "accettare" sono gli stessi termini usati nella maggior parte delle API socket."Connect," "Listen," and "Accept" are the same terms you find in most socket APIs.

In un modello di comunicazione di inoltro entrambe le parti creano connessioni in uscita verso un endpoint di servizio,Any relayed communication model has either party making outbound connections towards a service endpoint. rendendo il "listener" anche un "client" nel linguaggio comune e causando altre sovrapposizioni terminologiche.This makes the "listener" also a "client" in colloquial use, and may also cause other terminology overloads. La terminologia esatta usata per Connessioni ibride è quindi la seguente:The precise terminology therefore used for Hybrid Connections is as follows:

I programmi su entrambi i lati di una connessione sono detti "client", perché sono i client del servizio.The programs on both sides of a connection are called "clients," since they are clients to the service. Il client che attende e accetta le connessioni è il "listener", che è anche nel "ruolo listener".The client that waits for and accepts connections is the "listener," or is said to be in the "listener role." Il client che avvia una nuova connessione verso un listener tramite il servizio è detto "mittente", che è anche nel "ruolo mittente".The client that initiates a new connection towards a listener via the service is called the "sender," or is in the "sender role."

Interazioni del listenerListener interactions

Il listener ha cinque interazioni con il servizio. Tutti i dettagli sono descritti più avanti in questo articolo nella sezione di riferimento.The listener has five interactions with the service; all wire details are described later in this article in the reference section.

I messaggi di ascolto, accettazione e richiesta vengono ricevuti dal servizio.The Listen, Accept, and Request messages are received from the service. Le operazioni di rinnovo e ping vengono inviate dal listener.The Renew, and Ping operations are sent by the listener.

Messaggio di ascoltoListen message

Un listener, per indicare al servizio che è pronto ad accettare le connessioni, crea una connessione WebSocket in uscita.To indicate readiness to the service that a listener is ready to accept connections, it creates an outbound WebSocket connection. L'handshake della connessione trasporta il nome di una connessione ibrida configurata nello spazio dei nomi dell'inoltro e un token di sicurezza che conferisce il diritto di "ascoltare" a tale nome.The connection handshake carries the name of a Hybrid Connection configured on the Relay namespace, and a security token that confers the "Listen" right on that name.

Quando il WebSocket viene accettato dal servizio, la registrazione è completa e il WebSocket stabilito viene mantenuto attivo come "canale di controllo" per abilitare tutte le interazioni successive.When the WebSocket is accepted by the service, the registration is complete and the established WebSocket is kept alive as the "control channel" for enabling all subsequent interactions. Il servizio consente fino a 25 listener simultanei in una connessione ibrida.The service allows up to 25 concurrent listeners one Hybrid Connection. La quota per AppHooks deve essere stabilita.The quota for AppHooks is to be determined.

Per Connessioni ibride, se sono presenti due o più listener attivi, le connessioni in ingresso sono bilanciate tra loro in ordine casuale e non viene garantita una distribuzione equa.For Hybrid Connections, if there are two or more active listeners, incoming connections are balanced across them in random order; fair distribution is attempted with best effort.

Messaggio di accettazioneAccept message

Quando un mittente apre una nuova connessione nel servizio, il servizio sceglie uno dei listener attivi nella connessione ibrida e gli invia una notifica.When a sender opens a new connection on the service, the service chooses and notifies one of the active listeners on the Hybrid Connection. La notifica viene inviata al listener tramite il canale di controllo aperto come messaggio JSONThis notification is sent to the listener over the open control channel as a JSON message. contenente l'URL dell'endpoint del WebSocket a cui il listener deve connettersi per accettare la connessione.The message contains the URL of the WebSocket endpoint that the listener must connect to for accepting the connection.

L'URL può e deve essere usato direttamente dal listener senza operazioni aggiuntive.The URL can and must be used directly by the listener without any extra work. Le informazioni codificate sono valide solo per un breve periodo, essenzialmente finché il mittente è disposto ad attendere che venga stabilita una connessione end-to-end.The encoded information is only valid for a short period of time, essentially for as long as the sender is willing to wait for the connection to be established end-to-end. Il tempo massimo previsto è pari a 30 secondi.The maximum to assume is 30 seconds. L'URL può essere usato solo per tentativo di connessione riuscito.The URL can only be used for one successful connection attempt. Non appena viene stabilita la connessione WebSocket con l'URL di incontro, tutte le altre attività in questo WebSocket vengono inoltrate da e verso il mittente,As soon as the WebSocket connection with the rendezvous URL is established, all further activity on this WebSocket is relayed from and to the sender. senza interventi o interpretazioni da parte del servizio.This happens without any intervention or interpretation by the service.

Messaggio di richiestaRequest message

Oltre alle connessioni WebSocket, il listener può anche ricevere frame di richiesta HTTP da un mittente, se questa funzionalità è abilitata in modo esplicito per la connessione ibrida.In addition to WebSocket connections, the listener can also receive HTTP request frames from a sender, if this capability is explicitly enabled on the Hybrid Connection.

I listener associati a Connessioni ibride con supporto HTTP DEVONO gestire l'azione request.Listeners that attach to Hybrid Connections with HTTP support MUST handle the request gesture. Un listener che non gestisce l'azione request e che pertanto causa errori di timeout ripetuti durante la connessione PUÒ essere disattivato dal servizio in futuro.A listener that doesn't handle request and therefore causes repeated timeout errors while being connected MAY be blacklisted by the service in the future.

I metadati di intestazione del frame HTTP vengono convertiti in JSON per essere gestiti in modo più semplice dal framework del listener, anche perché le librerie di analisi dell'intestazione HTTP sono più rare rispetto ai parser JSON.HTTP frame header metadata is translated into JSON for simpler handling by the listener framework, also because HTTP header parsing libraries are rarer than JSON parsers. I metadati HTTP rilevanti solo per la relazione tra il mittente e il gateway HTTP di inoltro, incluse le informazioni di autorizzazione, non vengono inoltrati.HTTP metadata that is only relevant for the relationship between the sender and the Relay HTTP gateway, including authorization information, is not forwarded. I corpi delle richieste HTTP vengono trasferiti in modo trasparente come frame WebSocket binari.HTTP request bodies are transparently transferred as binary WebSocket frames.

Il listener può rispondere a richieste HTTP effettuate con un'azione di risposta equivalente.The listener can respond to HTTP requests using an equivalent response gesture.

Il flusso di richiesta/risposta usa il canale di controllo per impostazione predefinita, ma può essere "aggiornato" a un WebSocket di incontro distinto, quando necessario.The request/response flow uses the control channel by default, but can be "upgraded" to a distinct rendezvous WebSocket whenever required. Connessioni WebSocket distinte migliorano la velocità effettiva per ogni conversazione client, ma aumentano il carico del listener con più connessioni da gestire, situazione non auspicabile per i client più semplici.Distinct WebSocket connections improve throughput for each client conversation, but they burden the listener with more connections that need to be handled, which may not be desire able for lightweight clients.

Sul canale di controllo le dimensioni dei corpi dei messaggi di richiesta e risposta sono limitate a un massimo di 64 KB.On the control channel, request and response bodies are limited to at most 64 kB in size. I metadati di intestazione HTTP sono limitati a un totale di 32 KB.HTTP header metadata is limited to a total of 32 kB. Se la richiesta o la risposta supera tale soglia, il listener DEVE eseguire l'aggiornamento a un WebSocket di incontro con un'azione equivalente alla gestione del massaggio di accettazione.If either the request or the response exceeds that threshold, the listener MUST upgrade to a rendezvous WebSocket using a gesture equivalent to handling the Accept.

Il servizio decide se instradare le richieste tramite il canale di controllo.For requests, the service decides whether to route requests over the control channel. Ciò include, in via esemplificativa, il caso in cui una richiesta superi i 64 KB (intestazioni e corpo) complessivi o quello in cui la richiesta venga inviata con codifica di trasferimento in blocchi e il servizio preveda che la richiesta superi i 64 KB o legga che la richiesta non è istantanea.This includes, but may not be limited to cases where a request exceeds 64 kB (headers plus body) outright, or if the request is sent with "chunked" transfer-encoding and the service has reason to expect for the request to exceed 64kB or reading the request is not instantaneous. Se il servizio sceglie di recapitare la richiesta sul punto di incontro, al listener passa solo l'indirizzo di quest'ultimo.If the service chooses to deliver the request over rendezvous, it only passes the rendezvous address to the listener. Il listener DEVE quindi stabilire il WebSocket di incontro e il servizio recapita tempestivamente la richiesta completa, inclusi i corpi, sul WebSocket di incontro.The listener then MUST establish the rendezvous WebSocket and the service promptly delivers the full request including bodies over the rendezvous WebSocket. Anche la risposta DEVE usare il WebSocket di incontro.The response MUST also use the rendezvous WebSocket.

Per le richieste che arrivano tramite il canale di controllo, il listener decide se rispondere sul canale di controllo o tramite punto di incontro.For requests that arrive over the control channel, the listener decides whether to respond over the control channel or via rendezvous. Il servizio DEVE includere un indirizzo del punto di incontro in tutte le richieste indirizzate tramite il canale di controllo.The service MUST include a rendezvous address with every request routed over the control channel. Tale indirizzo è valido solo per l'aggiornamento dalla richiesta corrente.This address is only valid for upgrading from the current request.

Se il listener sceglie di eseguire l'aggiornamento, si connette e recapita tempestivamente la risposta sul socket di incontro stabilito.If the listener chooses to upgrade, it connects and promptly delivers the response over the established rendezvous socket.

Dopo che il WebSocket di incontro è stato stabilito, il listener DEVE mantenerlo per gestire successivamente le richieste e le risposte dello stesso client.Once the rendezvous WebSocket has been established, the listener SHOULD maintain it for further handling of requests and responses from the same client. Il servizio mantiene il WebSocket fino a quando la connessione socket HTTPS con il mittente è presente e indirizza tutte le richieste successive provenienti da tale mittente sul WebSocket specifico.The service will maintain the WebSocket for as long as the HTTPS socket connection with the sender persists and will route all subsequent requests from that sender over the maintained WebSocket. Se il listener sceglie di eliminare il WebSocket di incontro nel proprio lato, il servizio elimina anche la connessione al mittente, indipendentemente dal fatto che una richiesta successiva possa essere già in corso.If the listener chooses to drop the rendezvous WebSocket from its side, the service will also drop the connection to the sender, irrespective of whether a subsequent request might already be in progress.

Operazione di rinnovoRenew operation

Il token di sicurezza che deve essere usato per registrare il listener e mantenere il canale di controllo può scadere mentre il listener è attivo.The security token that must be used to register the listener and maintain the control channel may expire while the listener is active. La scadenza del token non ha effetto sulle connessioni in corso, ma il canale di controllo viene rimosso dal servizio al momento della scadenza o poco dopo.The token expiry does not affect ongoing connections, but it does cause the control channel to be dropped by the service at or soon after the moment of expiry. L'operazione "renew" è un messaggio JSON che il listener può inviare per sostituire il token associato al canale di controllo che potrà quindi essere mantenuto per lunghi periodi.The "renew" operation is a JSON message that the listener can send to replace the token associated with the control channel, so that the control channel can be maintained for extended periods.

Operazione di pingPing operation

Se il canale di controllo rimane inattivo a lungo, gli intermediari lungo il percorso, ad esempio servizi di bilanciamento del carico o NAT, potrebbero rimuovere la connessione TCP.If the control channel stays idle for a long time, intermediaries on the way, such as load balancers or NATs may drop the TCP connection. L'operazione "ping" evita questo problema inviando nel canale una piccola quantità di dati che ricorda a tutti gli elementi nella route di rete che la connessione deve restare attiva, oltre a fungere da test dello stato attivo per il listener.The "ping" operation avoids that by sending a small amount of data on the channel that reminds everyone on the network route that the connection is meant to be alive, and it also serves as a "live" test for the listener. Se il ping non riesce, il canale di controllo deve essere considerato non utilizzabile e il listener deve riconnettersi.If the ping fails, the control channel should be considered unusable and the listener should reconnect.

Interazione del mittenteSender interaction

Il mittente ha due interazioni con il servizio, ovvero si connette a un protocollo WebSocket o invia richieste tramite HTTPS.The sender has two interactions with the service: it connects a Web Socket or it sends requests via HTTPS. Le richieste non possono essere inviate tramite WebSocket dal ruolo mittente.Requests cannot be sent over a Web Socket from the sender role.

Operazione di connessioneConnect operation

L'operazione "connect" apre un WebSocket nel servizio, fornendo il nome della connessione ibrida e un token di sicurezza (facoltativo, ma richiesto per impostazione predefinita) che conferisce l'autorizzazione "Send" nella stringa di query.The "connect" operation opens a WebSocket on the service, providing the name of the Hybrid Connection and (optionally, but required by default) a security token conferring "Send" permission in the query string. Il servizio interagisce quindi con il listener nel modo descritto in precedenza e il listener crea una connessione di incontro che viene unita a questo WebSocket.The service then interacts with the listener in the way described previously, and the listener creates a rendezvous connection that is joined with this WebSocket. Dopo che il WebSocket è stato accettato, tutte le altre interazioni nel WebSocket avvengono quindi con un listener connesso.After the WebSocket has been accepted, all further interactions on that WebSocket are with a connected listener.

Operazione di richiestaRequest operation

Per le istanze di Connessioni ibride per cui è stata la funzionalità è stata abilitata, il mittente può inviare al listener richieste HTTP in gran parte senza restrizioni.For Hybrid Connections for which the feature has been enabled, the sender can send largely unrestricted HTTP requests to listeners.

Ad eccezione di un token di accesso di inoltro incorporato nella stringa di query o in un'intestazione HTTP della richiesta, il servizio di inoltro è completamente trasparente per tutte le operazioni HTTP sull'indirizzo di inoltro e per tutti i suffissi del percorso relativo, lasciando al listener il pieno controllo dell'autorizzazione end-to-end e anche le funzionalità di estensione HTTP, ad esempio CORS.Except for a Relay access token that is either embedded in the query string or in an HTTP header of the request, the Relay is fully transparent to all HTTP operations on the Relay address and all suffixes of the Relay address path, leaving the listener fully in control of end-to-end authorization and even HTTP extension features like CORS.

L'autorizzazione mittente per l'endpoint di inoltro è attivata per impostazione predefinita, ma è FACOLTATIVA.Sender authorization with the Relay endpoint is turned on by default, but is OPTIONAL. Il proprietario della connessione ibrida può scegliere di consentire mittenti anonimi.The owner of the Hybrid Connection can choose to allow anonymous senders. Il servizio intercetta, controlla e rimuove le informazioni di autorizzazione come indicato di seguito:The service will intercept, inspect, and strip authorization information as follows:

  1. Se la stringa di query contiene un'espressione sb-hc-token, l'espressione viene SEMPRE rimossa dalla stringa di queryIf the query string contains a sb-hc-token expression, the expression will ALWAYS be stripped from the query string. e viene valutato se l'autorizzazione di inoltro è attivata.It will be evaluated if Relay authorization is turned on.
  2. Se le intestazioni della richiesta contengono un elemento ServiceBusAuthorization, l'espressione dell'intestazione viene SEMPRE rimossa dalla raccolta di intestazioniIf the request headers contain a ServiceBusAuthorization header, the header expression will ALWAYS be stripped from the header collection. e viene valutato se l'autorizzazione di inoltro è attivata.It will be evaluated if Relay authorization is turned on.
  3. Solo se l'autorizzazione di inoltro è attivata, se le intestazioni della richiesta contengono un elemento Authorization e se nessuna delle espressioni precedenti è presente, l'intestazione viene valutata e rimossa.Only if Relay authorization is turned on, and if the request headers contain an Authorization header, and neither of the prior expressions is present, the header will be evaluated and stripped. In caso contrario, l'elemento Authorization viene sempre trasmesso così com'è.Otherwise, the Authorizationis always passed on as-is.

Se non è presente alcun listener attivo, il servizio restituisce un codice di errore 502 "Gateway non valido".If there is no active listener, the service will return a 502 "Bad Gateway" error code. Se sembra che il servizio non gestisca la richiesta, viene restituito un codice di errore 504 "Timeout gateway" dopo 60 secondi.If the service does not appear to handle the request, the service will return a 504 "Gateway Timeout" after 60 seconds.

Riepilogo delle interazioniInteraction summary

Il risultato di questo modello di interazione è che il client mittente esce dall'handshake con un WebSocket "pulito" che è connesso a un listener e non richiede altri preamboli o preparazioni.The result of this interaction model is that the sender client comes out of the handshake with a "clean" WebSocket, which is connected to a listener and that needs no further preambles or preparation. Questo modello consente in pratica alle implementazioni di client WebSocket esistenti di usare subito il servizio Connessioni ibride specificando un URL correttamente costruito nel livello del client WebSocket.This model enables practically any existing WebSocket client implementation to readily take advantage of the Hybrid Connections service by supplying a correctly constructed URL into their WebSocket client layer.

Anche il WebSocket della connessione di incontro che il listener ottiene tramite l'interazione accept è pulito e può essere assegnato a qualsiasi implementazione di server WebSocket esistente con una minima astrazione aggiuntiva che distingue tra operazioni "accept" sui listener di rete locale del framework e operazioni "accept" remote di Connessioni ibride.The rendezvous connection WebSocket that the listener obtains through the accept interaction is also clean and can be handed to any existing WebSocket server implementation with some minimal extra abstraction that distinguishes between "accept" operations on their framework's local network listeners and Hybrid Connections remote "accept" operations.

Il modello di richiesta/risposta HTTP consente al mittente di operare in un'area del protocollo HTTP in gran parte senza restrizioni con un livello di autorizzazione FACOLTATIVO.The HTTP request/response model gives the sender a largely unrestricted HTTP protocol surface area with an OPTIONAL authorization layer. Il listener riceve una sezione di intestazione della richiesta HTTP pre-analizzata riportare a una richiesta HTTP downstream o gestire così com'è, con frame binari che trasporta corpi HTTP.The listener gets a pre-parsed HTTP request header section that can be turned back into a downstream HTTP request or handled as is, with binary frames carrying HTTP bodies. Le risposte usano lo stesso formato.Responses use the same format. Le interazioni con meno di 64 KB nel corpo della richiesta e della risposta possono essere gestite su un singolo WebSocket condiviso tra tutti i mittenti.Interactions with less than 64 KB of request and response body can be handled over a single Web Socket that is shared for all senders. Richieste e risposte di dimensioni maggiori possono essere gestite usando il modello di incontro.Larger requests and responses can be handled using the rendezvous model.

Riferimento al protocolloProtocol reference

Questa sezione descrive i dettagli delle interazioni del protocollo descritte sopra.This section describes the details of the protocol interactions described previously.

Tutte le connessioni WebSocket vengono stabilite sulla porta 443 come aggiornamento da HTTPS 1.1, che è in genere un'astrazione di alcune API o framework del WebSocket.All WebSocket connections are made on port 443 as an upgrade from HTTPS 1.1, which is commonly abstracted by some WebSocket framework or API. La presente descrizione è neutra dal punto di vista dell'implementazione e non suggerisce un framework specifico.The description here is kept implementation neutral, without suggesting a specific framework.

Protocollo del listenerListener protocol

Il protocollo del listener è costituito da due comandi di connessione e da tre operazioni messaggio.The listener protocol consists of two connection gestures and three message operations.

Connessione del canale di controllo del listenerListener control channel connection

Il canale di controllo viene aperto con la creazione di una connessione WebSocket a:The control channel is opened with creating a WebSocket connection to:

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

namespace-address è il nome di dominio completo dello spazio dei nomi di inoltro di Azure che ospita la connessione ibrida, in genere nel formato {myname}.servicebus.windows.net.The namespace-address is the fully qualified domain name of the Azure Relay namespace that hosts the Hybrid Connection, typically of the form {myname}.servicebus.windows.net.

Le opzioni dei parametri della stringa di query sono le seguenti.The query string parameter options are as follows.

ParametroParameter ObbligatoriaRequired DescrizioneDescription
sb-hc-action Yes Per il ruolo listener, il parametro deve essere sb-hc-action=listenFor the listener role, the parameter must be sb-hc-action=listen
{path} Yes Percorso dello spazio dei nomi codificato con URL della connessione ibrida preconfigurata in cui registrare questo listener.The URL-encoded namespace path of the pre-configured Hybrid Connection to register this listener on. Questa espressione viene aggiunta alla parte del percorso $hc/ fissa.This expression is appended to the fixed $hc/ path portion.
sb-hc-token Sì*Yes* Il listener deve fornire un token di accesso condiviso del bus di servizio codificato con URL valido per lo spazio dei nomi o la connessione ibrida che conferisce il diritto Listen.The listener must provide a valid, URL-encoded Service Bus Shared Access Token for the namespace or Hybrid Connection that confers the Listen right.
sb-hc-id No No Questo ID facoltativo fornito dal client consente la traccia diagnostica end-to-end.This client-supplied optional ID enables end-to-end diagnostic tracing.

Se la connessione WebSocket non riesce perché il percorso della connessione ibrida non è registrato oppure a causa di un token mancante o non valido o di un altro errore, il feedback dell'errore viene specificato usando il normale modello di feedback dello stato HTTP 1.1.If the WebSocket connection fails due to the Hybrid Connection path not being registered, or an invalid or missing token, or some other error, the error feedback is provided using the regular HTTP 1.1 status feedback model. La descrizione dello stato contiene un ID di traccia dell'errore che può essere comunicato al personale del supporto di Azure:The status description contains an error tracking-id that can be communicated to Azure support personnel:

CodiceCode Tipi di erroreError DESCRIZIONEDescription
404404 Non trovatoNot Found Il percorso della connessione ibrida non è valido o il formato dell'URL di base non è corretto.The Hybrid Connection path is invalid or the base URL is malformed.
401401 Non autorizzataUnauthorized Il token di sicurezza è mancante, non valido o non corretto.The security token is missing or malformed or invalid.
403403 Accesso negatoForbidden Il token di sicurezza non è valido per questo percorso per questa azione.The security token is not valid for this path for this action.
500500 Errore internoInternal Error Si è verificato un errore nel servizio.Something went wrong in the service.

Se la connessione WebSocket viene intenzionalmente arrestata dal servizio dopo la configurazione iniziale, il motivo viene comunicato usando un codice errore del protocollo WebSocket appropriato con un messaggio di errore descrittivo che include anche un ID di traccia.If the WebSocket connection is intentionally shut down by the service after it was initially set up, the reason for doing so is communicated using an appropriate WebSocket protocol error code along with a descriptive error message that also includes a tracking ID. Il servizio non arresterà il canale di controllo senza riscontrare una condizione di errore.The service will not shut down the control channel without encountering an error condition. Le chiusure normali sono controllate dal client.Any clean shutdown is client controlled.

Stato Web SocketWS Status DESCRIZIONEDescription
10011001 Il percorso della connessione ibrida è stato eliminato o disabilitato.The Hybrid Connection path has been deleted or disabled.
10081008 Il token di sicurezza è scaduto e i criteri di autorizzazione vengono quindi violati.The security token has expired, therefore the authorization policy is violated.
10111011 Si è verificato un errore nel servizio.Something went wrong in the service.

Handshake acceptAccept handshake

La notifica "accept" viene inviata dal servizio al listener tramite il canale di controllo stabilito in precedenza come messaggio JSON in una cornice di testo del WebSocket.The "accept" notification is sent by the service to the listener over the previously established control channel as a JSON message in a WebSocket text frame. Non sono previste risposte a questo messaggio.There is no reply to this message.

Il messaggio contiene un oggetto JSON denominato "accept", che definisce le proprietà attuali seguenti:The message contains a JSON object named "accept", which defines the following properties at this time:

  • address: stringa dell'URL da usare per stabilire il WebSocket al servizio per accettare una connessione in ingresso.address – the URL string to be used for establishing the WebSocket to the service to accept an incoming connection.
  • id: identificatore univoco per questa connessione.id – the unique identifier for this connection. Se l'ID è stato fornito dal client mittente, si tratta del valore fornito dal mittente. In caso contrario, è un valore generato dal sistema.If the ID was supplied by the sender client, it is the sender supplied value, otherwise it is a system generated value.
  • connectHeaders: tutte le intestazioni HTTP fornite all'endpoint di inoltro dal mittente, che include anche le intestazioni Sec-WebSocket-Protocol e Sec-WebSocket-Extensions.connectHeaders – all HTTP headers that have been supplied to the Relay endpoint by the sender, which also includes the Sec-WebSocket-Protocol and the Sec-WebSocket-Extensions headers.
{
    "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" : "..."
        }
     }
}

L'URL dell'indirizzo specificato nel messaggio JSON viene usato dal listener per stabilire il WebSocket per accettare o rifiutare il socket del mittente.The address URL provided in the JSON message is used by the listener to establish the WebSocket for accepting or rejecting the sender socket.

Accettazione del socketAccepting the socket

Per accettare, il listener stabilisce una connessione WebSocket all'indirizzo specificato.To accept, the listener establishes a WebSocket connection to the provided address.

Se il messaggio "accept" contiene un'intestazione Sec-WebSocket-Protocol, è previsto che il listener accetti il WebSocket solo se supporta tale protocollo.If the "accept" message carries a Sec-WebSocket-Protocol header, it is expected that the listener only accepts the WebSocket if it supports that protocol. Imposta inoltre l'intestazione quando viene definito il WebSocket.Additionally, it sets the header as the WebSocket is established.

Lo stesso vale per l'intestazione Sec-WebSocket-Extensions.The same applies to the Sec-WebSocket-Extensions header. Se il framework supporta un'estensione, deve impostare l'intestazione sulla risposta lato server dell'handshake Sec-WebSocket-Extensions obbligatorio per l'estensione.If the framework supports an extension, it should set the header to the server-side reply of the required Sec-WebSocket-Extensions handshake for the extension.

L'URL deve essere usato così com'è per stabilire il socket di accettazione, ma contiene i parametri seguenti:The URL must be used as-is for establishing the accept socket, but contains the following parameters:

ParametroParameter ObbligatoriaRequired DESCRIZIONEDescription
sb-hc-action Yes Per accettare un socket, il parametro deve essere sb-hc-action=acceptFor accepting a socket, the parameter must be sb-hc-action=accept
{path} Yes (vedere il paragrafo seguente)(see the following paragraph)
sb-hc-id No No Vedere la descrizione precedente di id.See previous description of id.

{path} è il percorso dello spazio dei nomi codificato con URL della connessione ibrida preconfigurata in cui registrare questo listener.{path} is the URL-encoded namespace path of the preconfigured Hybrid Connection on which to register this listener. Questa espressione viene aggiunta alla parte del percorso $hc/ fissa.This expression is appended to the fixed $hc/ path portion.

L'espressione path può essere estesa aggiungendo al nome registrato una barra, un suffisso e un'espressione di stringa di query.The path expression may be extended with a suffix and a query string expression that follows the registered name after a separating forward slash. Il client mittente può in questo modo trasmettere gli argomenti di invio al listener di accettazione quando non è possibile includere le intestazioni HTTP.This enables the sender client to pass dispatch arguments to the accepting listener when it is not possible to include HTTP headers. Il framework del listener dovrebbe analizzare la parte fissa del percorso e il nome registrato dal percorso, quindi rendere disponibile la parte restante (possibilmente senza argomenti di stringa di query con prefisso sb-) all'applicazione perché decida se accettare la connessione.The expectation is that the listener framework parses out the fixed path portion and the registered name from the path and makes the remainder, possibly without any query string arguments prefixed by sb-, available to the application for deciding whether to accept the connection.

Per altre informazioni, vedere la sezione "Protocollo per il mittente" che segue.For more information, see the following "Sender Protocol" section.

In caso di errore il servizio può rispondere come segue:If there is an error, the service can reply as follows:

CodiceCode Tipi di erroreError DESCRIZIONEDescription
403403 Accesso negatoForbidden URL non valido.The URL is not valid.
500500 Errore internoInternal Error Si è verificato un errore nel servizioSomething went wrong in the service

Dopo che la connessione è stata stabilita, il server arresta il WebSocket quando il WebSocket mittente si arresta o ha lo stato seguente:After the connection has been established, the server shuts down the WebSocket when the sender WebSocket shuts down, or with the following status:

Stato Web SocketWS Status DESCRIZIONEDescription
10011001 Il client mittente arresta la connessione.The sender client shuts down the connection.
10011001 Il percorso della connessione ibrida è stato eliminato o disabilitato.The Hybrid Connection path has been deleted or disabled.
10081008 Il token di sicurezza è scaduto e i criteri di autorizzazione vengono quindi violati.The security token has expired, therefore the authorization policy is violated.
10111011 Si è verificato un errore nel servizio.Something went wrong in the service.
Rifiuto del socketRejecting the socket

Per rifiutare il socket dopo avere esaminato il messaggio accept, è necessario un handshake simile in modo che il codice e la descrizione dello stato che comunicano il motivo del rifiuto possano tornare al mittente.Rejecting the socket after inspecting the accept message requires a similar handshake so that the status code and status description communicating the reason for the rejection can flow back to the sender.

La scelta di progettazione del protocollo in questo caso prevede l'uso di un handshake WebSocket (progettato per restituire uno stato di errore definito) in modo che le implementazioni del client listener possano continuare a basarsi su un client WebSocket e non sia necessario impiegare un altro client HTTP di base.The protocol design choice here is to use a WebSocket handshake (that is designed to end in a defined error state) so that listener client implementations can continue to rely on a WebSocket client and do not need to employ an extra, bare HTTP client.

Per rifiutare il socket, il client accetta l'URI dell'indirizzo dal messaggio accept e vi aggiunge due parametri di stringa di query, come indicato di seguito:To reject the socket, the client takes the address URI from the accept message and appends two query string parameters to it, as follows:

ParamParam ObbligatoriaRequired DESCRIZIONEDescription
sb-hc-statusCodesb-hc-statusCode Yes Codice di stato HTTP numerico.Numeric HTTP status code.
sb-hc-statusDescriptionsb-hc-statusDescription Yes Motivo leggibile del rifiuto.Human readable reason for the rejection.

L'URI risultante viene quindi usato per stabilire una connessione WebSocket.The resulting URI is then used to establish a WebSocket connection.

Se completato correttamente, questo handshake non riuscirà di proposito con il codice di errore HTTP 410, perché non è stato stabilito alcun WebSocket.When completing correctly, this handshake intentionally fails with an HTTP error code 410, since no WebSocket has been established. Se si verificano problemi, i codici seguenti descrivono l'errore:If something goes wrong, the following codes describe the error:

CodiceCode Tipi di erroreError DESCRIZIONEDescription
403403 Accesso negatoForbidden URL non valido.The URL is not valid.
500500 Errore internoInternal Error Si è verificato un errore nel servizio.Something went wrong in the service.

Messaggio di richiestaRequest message

Il messaggio request viene inviato dal servizio al listener tramite il canale di controllo.The request message is sent by the service to the listener over the control channel. Dopo la definizione della connessione, lo stesso messaggio viene inviato anche sul WebSocket di incontro.The same message is also sent over the rendezvous WebSocket once established.

L'elemento request è costituito da due parti: un frame dell'intestazione e uno del corpo binario.The request consists of two parts: a header and binary body frame(s). Se non è presente alcun corpo, i frame del corpo vengono omessi.If there is no body, the body frames are omitted. L'indicatore per verificare se è un corpo è presente è la proprietà booleana body nel messaggio di richiesta.The indicator for whether a body is present is the boolean body property in the request message.

Per una richiesta con un corpo, la richiesta è simile alla presente:For a request with a request body, the structure may look like this:

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

Il listener DEVE gestire la ricezione di corpo della richiesta suddiviso tra più frame binari (vedere Frammenti WebSocket).The listener MUST handle receiving the request body split across multiple binary frames (see WebSocket fragments). La richiesta termina quando viene ricevuto un frame binario con il set di flag FIN.The request ends when a binary frame with the FIN flag set has been received.

Per una richiesta senza corpo, è disponibile solo un frame di testo.For a request without a body, there's only one text frame.

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

Il contenuto JSON per request è indicato di seguito:The JSON content for request is as follows:

  • address - stringa URI.address - URI string. Questo è l'indirizzo di incontro da usare per la richiesta.This is the rendezvous address to use for this request. Se la richiesta in ingresso è superiore a 64 KB, la parte restante di questo messaggio viene lasciata vuota e il client DEVE avviare un handshake di incontro equivalente all'operazione accept descritta di seguito.If the incoming request is larger than 64 kB, the remainder of this message is left empty, and the client MUST initiate a rendezvous handshake equivalent to the accept operation described below. Il servizio inserisce quindi l'elemento request completo sul WebSocket stabilito.The service will then put the complete request on the established Web socket. Se si prevede che la risposta superi i 64 KB, il listener DEVE anche avviare un handshake di incontro e quindi trasferire la risposta tramite il WebSocket stabilito.If the response can be expected to exceed 64 kB, the listener MUST also initiate a rendezvous handshake, and then transfer the response over the established Web socket.
  • id - stringa.id – string. Identificatore univoco per questa richiesta.The unique identifier for this request.
  • requestHeaders - questo oggetto contiene tutte le intestazioni HTTP inviate dal mittente all'endpoint, ad eccezione delle informazioni di autorizzazione come indicato in precedenza, e le intestazioni strettamente correlate alla connessione con il gateway.requestHeaders – this object contains all HTTP headers that have been supplied to the endpoint by the sender, with exception of authorization information as explained above, and headers that strictly relate to the connection with the gateway. In particolare, TUTTE le intestazioni definite o riservate in RFC7230, ad eccezione di Via, vengono rimosse e non inoltrate:Specifically, ALL headers defined or reserved in RFC7230, except Via, are stripped and not forwarded:

    • Connection (RFC7230, Sezione 6.1)Connection (RFC7230, Section 6.1)
    • Content-Length (RFC7230, Sezione 3.3.2)Content-Length (RFC7230, Section 3.3.2)
    • Host (RFC7230, Sezione 5.4)Host (RFC7230, Section 5.4)
    • TE (RFC7230, Sezione 4.3)TE (RFC7230, Section 4.3)
    • Trailer (RFC7230, Sezione 4.4)Trailer (RFC7230, Section 4.4)
    • Transfer-Encoding (RFC7230, Sezione 3.3.1)Transfer-Encoding (RFC7230, Section 3.3.1)
    • Upgrade (RFC7230, Sezione 6.7)Upgrade (RFC7230, Section 6.7)
    • Close (RFC7230, Sezione 8.1)Close (RFC7230, Section 8.1)
  • requestTarget - stringa.requestTarget – string. Questa proprietà contiene la "destinazione richiesta" (RFC7230, Sezione 5.3) della richiesta.This property holds the "Request Target" (RFC7230, Section 5.3) of the request. Ciò include la parte della stringa di query, rimossa da TUTTI i parametri sb-hc- con prefisso.This includes the query string portion, which is stripped of ALL sb-hc- prefixed parameters.

  • method - stringa.method - string. Metodo della richiesta, per ogni elemento RFC7231, Sezione 4.This is the method of the request, per RFC7231, Section 4. Il metodo CONNECT NON DEVE essere usato.The CONNECT method MUST NOT be used.
  • body - booleano.body – boolean. Indica se è presente più di un frame di corpo binario.Indicates whether one more more binary body frame follows.
{
    "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
     }
}
Risposta alle richiesteResponding to requests

Il ricevente DEVE rispondere.The receiver MUST respond. Se ripetuta, la mancata risposta alle richieste durante la connessione può comportare la disattivazione del listener.Repeated failure to respond to requests while maintaining the connection might result in the listener getting blacklisted.

Le risposte possono essere inviate in qualsiasi ordine, ma ogni richiesta deve ottenere una risposta entro 60 secondi o il recapito verrà segnalato come non riuscito.Responses may be sent in any order, but each request must be responded to within 60 seconds or the delivery will be reported as having failed. La scadenza di 60 secondi viene conteggiata fino a quando il frame response non è stato ricevuto dal servizio.The 60-second deadline is counted until the response frame has been received by the service. Una risposta in corso con più frame binari non può restare inattiva per più di 60 secondi o viene terminata.An ongoing response with multiple binary frames cannot become idle for more than 60 seconds or it is terminated.

Se la richiesta viene ricevuta tramite il canale di controllo, la risposta DEVE essere inviata sul canale di controllo da cui la richiesta è stata ricevuta o DEVE essere inviata tramite un canale di incontro.If the request is received over the control channel, the response MUST either be sent on the control channel from where the request was received or it MUST be sent over a rendezvous channel.

La risposta è un oggetto JSON denominato "response".The response is a JSON object named "response". Le regole per la gestione del contenuto del corpo sono esattamente quelle usate con il messaggio request e si basano sulla proprietà body.The rules for handling body content are exactly like with the request message and based on the body property.

  • requestId - stringa.requestId – string. OBBLIGATORIO.REQUIRED. Valore della proprietà id del messaggio request a cui rispondere.The id property value of the request message being responded to.
  • statusCode - numero.statusCode – number. OBBLIGATORIO.REQUIRED. Codice di stato HTTP numerico che indica il risultato della notifica.a numerical HTTP status code that indicates the outcome of the notification. Tutti i codici di stato di RFC7231, Sezione 6 sono consentiti, ad eccezione di 502 "Gateway non valido" e 504 "Timeout gateway".All status codes of RFC7231, Section 6 are permitted, except for 502 "Bad Gateway" and 504 "Gateway Timeout".
  • statusDescription - stringa.statusDescription - string. FACOLTATIVO.OPTIONAL. Frase del motivo del codice di stato HTTP per RFC7230, Sezione 3.1.2HTTP status-code reason phrase per RFC7230, Section 3.1.2
  • responseHeaders - intestazione HTTP da impostare in una risposta HTTP esterna.responseHeaders – HTTP headers to be set in an external HTTP reply. Come con request, le intestazioni RFC7230 definite NON DEVONO essere usate.As with the request, RFC7230 defined headers MUST NOT be used.
  • body - booleano.body – boolean. Indica se sono presenti frame di corpo binari.Indicates whether binary body frame(s) follow(s).
----- 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" }
----------------------------------
Risposta tramite incontriResponding via rendezvous

Per le risposte che superano 64 KB, la risposta DEVE essere recapitata tramite un socket di incontro.For responses that exceed 64 kB, the response MUST be delivered over a rendezvous socket. Se la richiesta supera i 64 KB e l'elemento request contiene solo il campo di indirizzo, è necessario anche stabilire un socket di incontro per ottenere l'elemento request.Also, if the request exceeds 64 kB, and the request only contains the address field, a rendezvous socket must be established to obtain the request. Dopo che un socket di incontro è stato stabilito, le risposte ai rispettivi client e alle successive richieste di tali client DEVONO essere recapitate tramite il socket di incontro mentre è attivo.Once a rendezvous socket has been established, responses to the respective client and subsequent requests from that respective client MUST be delivered over the rendezvous socket while it persists.

L'URL address nell'elemento request deve essere usato così com'è per stabilire il socket di incontro, ma contiene i parametri seguenti:The address URL in the request must be used as-is for establishing the rendezvous socket, but contains the following parameters:

ParametroParameter ObbligatoriaRequired DESCRIZIONEDescription
sb-hc-action Yes Per accettare un socket, il parametro deve essere sb-hc-action=requestFor accepting a socket, the parameter must be sb-hc-action=request

In caso di errore il servizio può rispondere come segue:If there is an error, the service can reply as follows:

CodiceCode Tipi di erroreError DESCRIZIONEDescription
400400 Richiesta non validaInvalid Request Azione non riconosciuta o URL non valido.Unrecognized action or URL not valid.
403403 Accesso negatoForbidden L'URL è scaduto.The URL has expired.
500500 Errore internoInternal Error Si è verificato un errore nel servizioSomething went wrong in the service

Dopo che la connessione è stata stabilita, il server arresta il WebSocket quando il socket HTTP del client si arresta o ha lo stato seguente:After the connection has been established, the server shuts down the WebSocket when the client's HTTP socket shuts down, or with the following status:

Stato Web SocketWS Status DESCRIZIONEDescription
10011001 Il client mittente arresta la connessione.The sender client shuts down the connection.
10011001 Il percorso della connessione ibrida è stato eliminato o disabilitato.The Hybrid Connection path has been deleted or disabled.
10081008 Il token di sicurezza è scaduto e i criteri di autorizzazione vengono quindi violati.The security token has expired, therefore the authorization policy is violated.
10111011 Si è verificato un errore nel servizio.Something went wrong in the service.

Rinnovo del token del listenerListener token renewal

Quando il token del listener sta per scadere, può essere sostituito inviando un messaggio in una cornice di testo al servizio tramite il canale di controllo stabilito.When the listener token is about to expire, it can replace it by sending a text frame message to the service via the established control channel. Il messaggio contiene un oggetto JSON denominato renewToken, che definisce la proprietà attuale seguente:The message contains a JSON object called renewToken, which defines the following property at this time:

  • token: token di accesso condiviso del bus di servizio codificato con URL valido per lo spazio dei nomi o la connessione ibrida che conferisce il diritto Listen.token – a valid, URL-encoded Service Bus Shared Access token for the namespace or Hybrid Connection that confers the Listen right.
{
  "renewToken": {
    "token":
      "SharedAccessSignature sr=http%3a%2f%2fcontoso.servicebus.windows.net%2fhyco%2f&sig=XXXXXXXXXX%3d&se=1471633754&skn=SasKeyName"
  }
}

Se la convalida del token non riesce, l'accesso viene negato e il servizio cloud chiude il WebSocket del canale di controllo con un errore.If the token validation fails, access is denied, and the cloud service closes the control channel WebSocket with an error. In caso contrario non vi è alcuna risposta.Otherwise there is no reply.

Stato Web SocketWS Status DESCRIZIONEDescription
10081008 Il token di sicurezza è scaduto e i criteri di autorizzazione vengono quindi violati.The security token has expired, therefore the authorization policy is violated.

Protocollo di connessione al WebSocketWeb Socket connect protocol

Il protocollo per il mittente è di fatto identico a come viene stabilito un listener.The sender protocol is effectively identical to the way a listener is established. L'obiettivo è la massima trasparenza per il WebSocket end-to-end.The goal is maximum transparency for the end-to-end WebSocket. L'indirizzo a cui connettersi è lo stesso del listener, ma l'"azione" è diversa e il token richiede un'autorizzazione diversa:The address to connect to is the same as for the listener, but the "action" differs and the token needs a different permission:

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

namespace-address è il nome di dominio completo dello spazio dei nomi di inoltro di Azure che ospita la connessione ibrida, in genere nel formato {myname}.servicebus.windows.net.The namespace-address is the fully qualified domain name of the Azure Relay namespace that hosts the Hybrid Connection, typically of the form {myname}.servicebus.windows.net.

La richiesta può contenere intestazioni HTTP aggiuntive arbitrarie, incluse quelle definite dall'applicazione.The request can contain arbitrary extra HTTP headers, including application-defined ones. Tutte le intestazioni specificate vengono trasmesse al listener e sono disponibili nell'oggetto connectHeader del messaggio di controllo accept.All supplied headers flow to the listener and can be found on the connectHeader object of the accept control message.

Le opzioni dei parametri della stringa di query sono le seguenti:The query string parameter options are as follows:

ParamParam Obbligatorio?Required? DESCRIZIONEDescription
sb-hc-action Yes Per il ruolo mittente, il parametro deve essere sb-hc-action=connect.For the sender role, the parameter must be sb-hc-action=connect.
{path} Yes (vedere il paragrafo seguente)(see the following paragraph)
sb-hc-token Sì*Yes* Il listener deve fornire un token di accesso condiviso del bus di servizio codificato con URL valido per lo spazio dei nomi o la connessione ibrida che conferisce il diritto Send.The listener must provide a valid, URL-encoded Service Bus Shared Access Token for the namespace or Hybrid Connection that confers the Send right.
sb-hc-id No No ID facoltativo che consente la traccia diagnostica end-to-end ed è disponibile per il listener durante l'handshake accept.An optional ID that enables end-to-end diagnostic tracing and is made available to the listener during the accept handshake.

{path} è il percorso dello spazio dei nomi codificato con URL della connessione ibrida preconfigurata in cui registrare questo listener.The {path} is the URL-encoded namespace path of the preconfigured Hybrid Connection on which to register this listener. L'espressione path può essere estesa con un suffisso e un'espressione di stringa di query per comunicare altre informazioni.The path expression can be extended with a suffix and a query string expression to communicate further. Se la connessione ibrida è registrata nel percorso hyco, l'espressione path può essere hyco/suffix?param=value&... seguita dai parametri di stringa di query definiti qui.If the Hybrid Connection is registered under the path hyco, the path expression can be hyco/suffix?param=value&... followed by the query string parameters defined here. Un'espressione completa potrebbe quindi essere:A complete expression may then be as follows:

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

L'espressione path viene trasmessa al listener nell'URI dell'indirizzo contenuto nel messaggio di controllo "accept".The path expression is passed through to the listener in the address URI contained in the "accept" control message.

Se la connessione WebSocket non riesce perché il percorso della connessione ibrida non è registrato oppure a causa di un token mancante o non valido o di un altro errore, il feedback dell'errore viene specificato usando il normale modello di feedback dello stato HTTP 1.1.If the WebSocket connection fails due to the Hybrid Connection path not being registered, an invalid or missing token, or some other error, the error feedback is provided using the regular HTTP 1.1 status feedback model. La descrizione dello stato contiene un ID di traccia dell'errore che può essere comunicato al personale del supporto di Azure:The status description contains an error tracking ID that can be communicated to Azure support personnel:

CodiceCode Tipi di erroreError DESCRIZIONEDescription
404404 Non trovatoNot Found Il percorso della connessione ibrida non è valido o il formato dell'URL di base non è corretto.The Hybrid Connection path is invalid or the base URL is malformed.
401401 Non autorizzataUnauthorized Il token di sicurezza è mancante, non valido o non corretto.The security token is missing or malformed or invalid.
403403 Accesso negatoForbidden Il token di sicurezza non è valido per questo percorso e per questa azione.The security token is not valid for this path and for this action.
500500 Errore internoInternal Error Si è verificato un errore nel servizio.Something went wrong in the service.

Se la connessione WebSocket viene intenzionalmente arrestata dal servizio dopo la configurazione iniziale, il motivo viene comunicato usando un codice di errore del protocollo WebSocket appropriato con un messaggio di errore descrittivo che include anche un ID di traccia.If the WebSocket connection is intentionally shut down by the service after it has been initially set up, the reason for doing so is communicated using an appropriate WebSocket protocol error code along with a descriptive error message that also includes a tracking ID.

Stato Web SocketWS Status DESCRIZIONEDescription
10001000 Il listener ha arrestato il socket.The listener shut down the socket.
10011001 Il percorso della connessione ibrida è stato eliminato o disabilitato.The Hybrid Connection path has been deleted or disabled.
10081008 Il token di sicurezza è scaduto e i criteri di autorizzazione vengono quindi violati.The security token has expired, therefore the authorization policy is violated.
10111011 Si è verificato un errore nel servizio.Something went wrong in the service.

Protocollo di richiesta HTTPHTTP request protocol

Il protocollo di richiesta HTTP consente le richieste HTTP arbitrarie, ad eccezione degli aggiornamenti di protocollo.The HTTP request protocol allows arbitrary HTTP requests, except protocol upgrades. Alle richieste HTTP si fa riferimento all'indirizzo di runtime regolare dell'entità senza l'infisso $hc usato per i client WebSocket delle connessioni ibride.HTTP requests are pointed at the entity's regular runtime address, without the $hc infix that is used for hybrid connections WebSocket clients.

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

namespace-address è il nome di dominio completo dello spazio dei nomi di inoltro di Azure che ospita la connessione ibrida, in genere nel formato {myname}.servicebus.windows.net.The namespace-address is the fully qualified domain name of the Azure Relay namespace that hosts the Hybrid Connection, typically of the form {myname}.servicebus.windows.net.

La richiesta può contenere intestazioni HTTP aggiuntive arbitrarie, incluse quelle definite dall'applicazione.The request can contain arbitrary extra HTTP headers, including application-defined ones. Tutte le intestazioni specificate, ad eccezione di quelle definite direttamente in RFC7230 (vedere il [messaggio di richiesta](#Request message)) vengono inviate al listener e possono essere trovate nell'oggetto requestHeader del messaggio request.All supplied headers, except those directly defined in RFC7230 (see [request message](#Request message)) flow to the listener and can be found on the requestHeader object of the request message.

Le opzioni dei parametri della stringa di query sono le seguenti:The query string parameter options are as follows:

ParamParam Obbligatorio?Required? DESCRIZIONEDescription
sb-hc-token Sì*Yes* Il listener deve fornire un token di accesso condiviso del bus di servizio codificato con URL valido per lo spazio dei nomi o la connessione ibrida che conferisce il diritto Send.The listener must provide a valid, URL-encoded Service Bus Shared Access Token for the namespace or Hybrid Connection that confers the Send right.

Il token può essere spostato anche nell'intestazione HTTP ServiceBusAuthorization o Authorization.The token can also be carried in either the ServiceBusAuthorization or Authorization HTTP header. Il token può essere omesso se la connessione ibrida è configurata per consentire le richieste anonime.The token can be omitted if the Hybrid Connection is configured to permit anonymous requests.

Il servizio funziona effettivamente come un proxy, anche se non come un proxy HTTP reale, e di conseguenza aggiunge un'intestazione Via o prende nota dell'intestazione Via esistente conforme a RFC7230, Sezione 5.7.1.Because the service effectively acts as a proxy, even if not as a true HTTP proxy, it either adds a Via header or annotates the existing Via header compliant with RFC7230, Section 5.7.1. Il servizio aggiunge il nome host dello spazio dei nomi di inoltro all'elemento Via.The service adds the Relay namespace hostname to Via.

CodiceCode MessageMessage DESCRIZIONEDescription
200200 OKOK La richiesta è stata gestita da almeno un listener.The request has been handled by at least one listener.
202202 AcceptedAccepted La richiesta è stata accettata da almeno un listener.The request has been accepted by at least one listener.

In caso di errore il servizio può rispondere come indicato di seguito.If there is an error, the service can reply as follows. Per determinare se la risposta viene generata dal servizio o da quella del listener, verificare la presenza dell'intestazione Via.Whether the response originates from the service or from the listener can be identified through presence of the Via header. Se l'intestazione è presente, la risposta proviene dal listener.If the header is present, the response is from the listener.

CodiceCode Tipi di erroreError DESCRIZIONEDescription
404404 Non trovatoNot Found Il percorso della connessione ibrida non è valido o il formato dell'URL di base non è corretto.The Hybrid Connection path is invalid or the base URL is malformed.
401401 Non autorizzataUnauthorized Il token di sicurezza è mancante, non valido o non corretto.The security token is missing or malformed or invalid.
403403 Accesso negatoForbidden Il token di sicurezza non è valido per questo percorso e per questa azione.The security token is not valid for this path and for this action.
500500 Errore internoInternal Error Si è verificato un errore nel servizio.Something went wrong in the service.
503503 Gateway non validoBad Gateway La richiesta potrebbe non essere indirizzata ad alcun listener.The request could not be routed to any listener.
504504 Timeout gatewayGateway Timeout La richiesta è stata indirizzata a un listener, ma il listener non ha confermato il ricevimento nel periodo di tempo necessario.The request was routed to a listener, but the listener did not acknowledge receipt in the required time.

Passaggi successiviNext steps