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, di cui una o entrambe le parti risiedono dietro NAT o firewall.Hybrid Connections enables bi-directional, binary stream communication between two networked applications, during which 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 mittente e come i listener accettano nuove connessioni.This article describes the client-side interactions with the Hybrid Connections relay for connecting clients in listener and sender roles, and how listeners accept new connections.

Modello di interazioneInteraction model

L'inoltro di Connessioni ibride connette due parti fornendo un punto di incontro nel cloud di Azure che entrambe 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 both parties can discover and connect to from their own network’s perspective. Tale punto di incontro è detto "connessione ibrida" in questo e negli altri documenti, nelle API e anche nel Portale di Azure.That 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 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 è presente un client di connessione che si connette al listener, aspettando che la connessione venga accettata per stabilire un percorso di comunicazione bidirezionale.On the other side, there is a connecting client that 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, rendendo il "listener" anche un "client" nel linguaggio comune e causando altre sovrapposizioni terminologiche.Any relayed communication model has either party making outbound connections towards a service endpoint, which 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 we therefore use 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 quattro interazioni con il servizio. Tutti i dettagli sono descritti più avanti in questo articolo nella sezione di riferimento.The listener has four interactions with the service; all wire details are described later in this article in the reference section.

AttesaListen

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 web 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 on a Hybrid Connection. In presenza di due o più listener attivi, le connessioni in ingresso vengono bilanciate tra di essi in ordine casuale. Non è garantita una distribuzione equa.If there are two or more active listeners, incoming connections are balanced across them in random order; fair distribution is not guaranteed.

AcceptAccept

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 JSON contenente l'URL dell'endpoint del WebSocket a cui il listener deve connettersi per accettare la connessione.This notification is sent to the listener over the open control channel as a JSON message containing 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 e comunque per un massimo di 30 secondi.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, but up to a maximum of 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, senza interventi o interpretazioni da parte del servizio.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, without any intervention or interpretation by the service.

RenewRenew

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.

PingPing

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 una sola interazione con il servizio, la connessione.The sender only has a single interaction with the service: it connects.

ConnettereConnect

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.

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.

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 ObbligatorioRequired 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 Il percorso dello spazio dei nomi codificato con URL della connessione ibrida preconfigurata in cui registrare questo listener.The URL-encoded namespace path of the preconfigured 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 NoNo 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 ErroreError DescriptionDescription
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 DescriptionDescription
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.

Messaggio acceptAccept Message

{                                                           
    "accept" : {
        "address" : "wss://168.61.148.205: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 ObbligatorioRequired 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 NoNo 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 ErroreError DescriptionDescription
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 DescriptionDescription
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 di stato e la descrizione dello stato che comunica 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 ObbligatorioRequired DescrizioneDescription
statusCodestatusCode Yes Codice di stato HTTP numerico.Numeric HTTP status code.
statusDescriptionstatusDescription 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 ErroreError DescriptionDescription
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.

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.

Messaggio renewTokenrenewToken message

{                                                                                                                                                                        
    "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 DescriptionDescription
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 per il mittenteSender 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 action=connect.For the sender role, the parameter must be 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 NoNo 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 ErroreError DescriptionDescription
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 DescriptionDescription
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.

Passaggi successiviNext steps