Azure Relay-HybridverbindungsprotokollAzure Relay Hybrid Connections protocol

Azure Relay ist eine der Säulen der Schlüsselfunktionen der Azure Service Bus-PlattformAzure Relay is one of the key capability pillars of the Azure Service Bus platform. Die neue Funktion Hybridverbindungen von Relay ist eine sichere Entwicklung mit offenem Protokoll, die auf HTTP und WebSockets basiert.The new Hybrid Connections capability of Relay is a secure, open-protocol evolution based on HTTP and WebSockets. Sie ersetzt die ehemalige, gleichnamige Funktion BizTalk Services, die auf einer proprietären Protokollbasis erstellt wurde.It supersedes the former, equally named BizTalk Services feature that was built on a proprietary protocol foundation. Die Integration von Hybridverbindungen in Azure App Services funktioniert weiterhin ohne weiteren Aufwand.The integration of Hybrid Connections into Azure App Services will continue to function as-is.

Hybridverbindungen ermöglichen eine bidirektionale, binäre Streamkommunikation und einen einfachen Datagrammfluss zwischen zwei vernetzten Anwendungen.Hybrid Connections enables bi-directional, binary stream communication and simple datagram flow between two networked applications. Eine oder beide Parteien können sich hierbei hinter NATs oder Firewalls befinden.Either or both parties can reside behind NATs or firewalls.

In diesem Artikel werden die clientseitigen Interaktionen mit dem Hybridverbindungsrelay für die Verbindung von Clients in Listener- und Absenderrollen beschrieben.This article describes the client-side interactions with the Hybrid Connections relay for connecting clients in listener and sender roles. Außerdem wird beschrieben, wie Listener neue Verbindungen und Anforderungen akzeptieren.It also describes how listeners accept new connections and requests.

InteraktionsmodellInteraction model

Das Hybridverbindungs-Relay verbindet zwei Parteien durch einen Rendezvouspunkt in der Azure-Cloud, den die Parteien erkennen können und mit dem sie eine Verbindung aus ihrer eigenen Netzwerkperspektive herstellen können.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. In dieser Dokumentation und anderen Dokumentationen, in den APIs und auch im Azure-Portal hat der Rendezvouspunkt die Bezeichnung „Hybridverbindung“.The rendezvous point is called "Hybrid Connection" in this and other documentation, in the APIs, and also in the Azure portal. Der Endpunkt dieses Hybridverbindungsdiensts wird im weiteren Verlauf dieses Artikels als „Dienst“ bezeichnet.The Hybrid Connections service endpoint is referred to as the "service" for the rest of this article.

Der Dienst ermöglicht die Bereitstellung von WebSocket-Verbindungen und HTTP(S)-Anforderungen und -Antworten.The service allows for relaying Web Socket connections and HTTP(S) requests and responses.

Für das Interaktionsmodell werden Bezeichnungen verwendet, die auch für viele andere Netzwerk-APIs gängig sind.The interaction model leans on the nomenclature established by many other networking APIs. Es gibt einen Listener, der zuerst die Bereitschaft anzeigt, eingehende Verbindungen zu verarbeiten und akzeptiert diese anschließend, wenn sie ankommen.There is a listener that first indicates readiness to handle incoming connections, and subsequently accepts them as they arrive. Auf der anderen Seite stellt ein Client eine Verbindung mit dem Listener her und erwartet, dass diese Verbindung für die Erstellung eines bidirektionalen Kommunikationspfads akzeptiert wird.On the other side, a client connects towards the listener, expecting that connection to be accepted for establishing a bi-directional communication path. „Verbinden“ (Connect), „Lauschen“ (Listen) und „Akzeptieren“ (Accept) sind die Begriffe, die Sie in den meisten Socket-APIs finden."Connect," "Listen," and "Accept" are the same terms you find in most socket APIs.

In jedem Relaykommunikationsmodell stellen beide Parteien ausgehende Verbindungen mit einem Dienstendpunkt her.Any relayed communication model has either party making outbound connections towards a service endpoint. Hierdurch wird der „Listener“ umgangssprachlich auch zu einem „Client“ und kann ebenfalls weitere Überschneidungen in der Terminologie verursachen.This makes the "listener" also a "client" in colloquial use, and may also cause other terminology overloads. Daher wird bei Hybridverbindungen die folgende präzise Terminologie verwendet:The precise terminology therefore used for Hybrid Connections is as follows:

Die Programme auf beiden Seiten der Verbindung werden als „Clients“ bezeichnet, da sie für den Dienst Clients darstellen.The programs on both sides of a connection are called "clients," since they are clients to the service. Der Client, der auf Verbindungen wartet und diese akzeptiert, ist der „Listener“ oder befindet sich in der „Listenerrolle“.The client that waits for and accepts connections is the "listener," or is said to be in the "listener role." Der Client, der über den Dienst eine neue Verbindung mit einem Listener herstellt, heißt „Absender“ bzw. befindet sich in der „Absenderrolle“.The client that initiates a new connection towards a listener via the service is called the "sender," or is in the "sender role."

Listener-InteraktionenListener interactions

Der Listener verfügt über fünf Interaktionen mit dem Dienst. Alle Transportdetails werden später im Abschnitt „Referenz“ dieses Artikels erläutert.The listener has five interactions with the service; all wire details are described later in this article in the reference section.

Die Listen-, Accept- und Request-Nachrichten gehen vom Dienst ein.The Listen, Accept, and Request messages are received from the service. Die Renew- und Ping-Vorgänge werden vom Listener gesendet.The Renew, and Ping operations are sent by the listener.

Listen-NachrichtListen message

Um die Bereitschaft an einen Dienst zu übermitteln, dass ein Listener bereit zum Akzeptieren von Verbindungen ist, erstellt er eine ausgehende WebSocket-Verbindung.To indicate readiness to the service that a listener is ready to accept connections, it creates an outbound WebSocket connection. Der Verbindungshandshake enthält den Namen einer Hybridverbindung, die im Relaynamespace konfiguriert wurde, sowie ein Sicherheitstoken, das die Berechtigung „Lauschen“ direkt innerhalb dieses Namens überträgt.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.

Wenn der WebSocket vom Dienst akzeptiert wird, ist die Registrierung abgeschlossen, und der erstellte WebSocket wird als „Steuerungskanal“ für die Aktivierung aller nachfolgenden Interaktionen aufrechterhalten.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. Der Dienst lässt bis zu 25 gleichzeitige Listener für eine Hybridverbindung zu.The service allows up to 25 concurrent listeners for one Hybrid Connection. Das Kontingent für AppHooks muss noch ermittelt werden.The quota for AppHooks is to be determined.

Wenn für Hybridverbindungen zwei oder mehr aktive Listener vorhanden sind, werden eingehende Verbindungen in zufälliger Reihenfolge darauf aufgeteilt. Es wird versucht, eine möglichst gleichmäßige Aufteilung zu erzielen.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.

Accept-NachrichtAccept message

Wenn ein Absender eine neue Verbindung im Dienst öffnet, wählt und benachrichtigt der Dienst einen der aktiven Listener in der Hybridverbindung.When a sender opens a new connection on the service, the service chooses and notifies one of the active listeners on the Hybrid Connection. Diese Benachrichtigung wird über den offenen Steuerkanal als JSON-Nachricht an den Listener gesendet.This notification is sent to the listener over the open control channel as a JSON message. Die Nachricht enthält die URL des WebSocket-Endpunkts, mit dem der Listener eine Verbindung herstellen muss, um die Verbindung zu akzeptieren.The message contains the URL of the WebSocket endpoint that the listener must connect to for accepting the connection.

Die URL kann bzw. muss vom Listener ohne zusätzlichen Aufwand direkt verwendet werden.The URL can and must be used directly by the listener without any extra work. Die codierten Informationen sind nur für kurze Zeit gültig. Dies ist im Grunde genommen der Zeitraum, der vom Absender toleriert wird, bis die End-to-End-Verbindung hergestellt wurde.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. Der anzunehmende Höchstwert beträgt 30 Sekunden.The maximum to assume is 30 seconds. Die URL kann nur für einen erfolgreichen Verbindungsversuch verwendet werden.The URL can only be used for one successful connection attempt. Sobald die WebSocket-Verbindung mit der Rendezvous-URL hergestellt wurde, wird jede weitere Aktivität in diesem WebSocket an den bzw. vom Absender übermittelt.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. Dies erfolgt ohne Eingriff oder Interpretation des Diensts.This happens without any intervention or interpretation by the service.

Request-NachrichtRequest message

Zusätzlich zu WebSocket-Verbindungen kann der Listener auch HTTP-Anforderungsframes von einem Absender empfangen, wenn diese Funktion für die Hybridverbindung explizit aktiviert wird.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.

Listener, die an Hybridverbindungen mit HTTP-Unterstützung angefügt sind, MÜSSEN die request-Geste verarbeiten.Listeners that attach to Hybrid Connections with HTTP support MUST handle the request gesture. Ein Listener, der request nicht verarbeitet und so wiederholt Zeitüberschreitungsfehler verursacht, während die Verbindung besteht, KANN vom Dienst im weiteren Verlauf auf eine Sperrliste gesetzt werden.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.

Die Metadaten von HTTP-Frame-Headern werden in das JSON-Format übersetzt, damit sie vom Listener-Framework einfacher verarbeitet werden können. Ein Grund hierfür ist, dass HTTP-Header-Analysebibliotheken seltener als JSON-Parser sind.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. HTTP-Metadaten, die nur für die Beziehung zwischen dem Absender und dem Relay-HTTP-Gateway relevant sind, z.B. Autorisierungsinformationen, werden nicht weitergeleitet.HTTP metadata that is only relevant for the relationship between the sender and the Relay HTTP gateway, including authorization information, is not forwarded. HTTP-Anforderungstexte werden auf transparente Weise als binäre WebSocket-Frames übertragen.HTTP request bodies are transparently transferred as binary WebSocket frames.

Der Listener kann auf HTTP-Anforderungen antworten, indem er eine äquivalente Antwortgeste verwendet.The listener can respond to HTTP requests using an equivalent response gesture.

Für den Anforderung/Antwort-Datenfluss wird standardmäßig der Steuerkanal verwendet, aber es kann bei Bedarf jederzeit ein „Upgrade“ auf ein eindeutiges WebSocket-Rendezvouselement durchgeführt werden.The request/response flow uses the control channel by default, but can be "upgraded" to a distinct rendezvous WebSocket whenever required. Mit eindeutigen WebSocket-Verbindungen wird der Durchsatz für die einzelnen Clientkonversationen verbessert. Sie stellen für den Listener aber eine erhöhte Belastung dar, weil eine größere Zahl von Verbindungen verarbeitet werden muss. Dies ist für einfache Clients unter Umständen nicht wünschenswert.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.

Für den Steuerkanal sind Anforderungs- und Antworttexte auf eine maximale Größe von 64 KB beschränkt.On the control channel, request and response bodies are limited to at most 64 kB in size. Die Metadaten von HTTP-Headern sind auf insgesamt 32 KB beschränkt.HTTP header metadata is limited to a total of 32 kB. Wenn dieser Schwellenwert entweder von der Anforderung oder der Antwort überschritten wird, MUSS der Listener ein Upgrade auf ein WebSocket-Rendezvouselement durchführen, indem er eine Geste verwendet, die zur Verarbeitung der Accept-Nachricht äquivalent ist.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.

Für Anforderungen entscheidet der Dienst, ob Anforderungen über den Steuerkanal geleitet werden.For requests, the service decides whether to route requests over the control channel. Beispiele hierfür sind u.a. Fälle, in denen eine Anforderung den Wert von 64 KB (Header und Text zusammen) klar überschreitet, die Anforderung mit der Übertragungscodierung „Chunked“ gesendet wird und der Dienst den begründeten Verdacht hegt, dass die Anforderung 64 KB überschreitet, oder das Lesen der Anforderung nicht sofort erfolgt.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. Wenn der Dienst für die Zustellung der Anforderung das Rendezvouselement wählt, wird nur die Rendezvousadresse an den Listener übergeben.If the service chooses to deliver the request over rendezvous, it only passes the rendezvous address to the listener. Der Listener MUSS anschließend das WebSocket-Rendezvouselement einrichten, und der Dienst stellt die vollständige Anforderung, einschließlich der Texte, sofort über das WebSocket-Rendezvouselement bereit.The listener then MUST establish the rendezvous WebSocket and the service promptly delivers the full request including bodies over the rendezvous WebSocket. Auch für die Antwort MUSS das WebSocket-Rendezvouselement verwendet werden.The response MUST also use the rendezvous WebSocket.

Für Anforderungen, die über den Steuerkanal eingehen, entscheidet der Listener, ob über den Steuerkanal oder das Rendezvouselement geantwortet werden soll.For requests that arrive over the control channel, the listener decides whether to respond over the control channel or via rendezvous. Der Dienst MUSS eine Rendezvousadresse enthalten, bei der jede Anforderung über den Steuerkanal geleitet wird.The service MUST include a rendezvous address with every request routed over the control channel. Diese Adresse ist nur für Upgrades basierend auf der aktuellen Anforderung gültig.This address is only valid for upgrading from the current request.

Wenn sich der Listener für die Durchführung des Upgrades entscheidet, stellt er eine Verbindung her und stellt die Antwort sofort über das eingerichtete WebSocket-Rendezvouselement zu.If the listener chooses to upgrade, it connects and promptly delivers the response over the established rendezvous socket.

Nachdem das WebSocket-Rendezvouselement eingerichtet wurde, SOLLTE der Listener es für die weitere Verarbeitung der Anforderungen und Antworten desselben Clients beibehalten.Once the rendezvous WebSocket has been established, the listener SHOULD maintain it for further handling of requests and responses from the same client. Der Dienst behält das WebSocket-Element so lange bei, wie die HTTPS-Socketverbindung mit dem Absender besteht, und alle nachfolgenden Anforderungen von diesem Absender werden über das beibehaltene WebSocket-Element geleitet.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. Wenn der Listener sich auf seiner Seite für das Verwerfen des WebSocket-Rendezvouselement entscheidet, verwirft der Dienst auch die Verbindung mit dem Absender. Dies gilt unabhängig davon, ob sich eine nachfolgende Anforderung ggf. bereits in Bearbeitung befindet.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.

Renew-VorgangRenew operation

Das Sicherheitstoken, das verwendet werden muss, um den Listener zu registrieren und den Steuerungskanal zu verwalten, läuft möglicherweise ab, währen der Listener aktiv ist.The security token that must be used to register the listener and maintain the control channel may expire while the listener is active. Der Ablauf des Tokens beeinträchtigt keine laufenden Verbindungen, aber der Steuerungskanal wird dadurch während oder kurz nach dem Moment des Ablaufs vom Dienst entfernt.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. Der „renew“-Vorgang zum Erneuern ist eine JSON-Nachricht, die der Listener senden kann, um das Token zu ersetzen, das dem Steuerungskanal zugeordnet ist. Dadurch kann der Steuerungskanal über einen längeren Zeitraum beibehalten werden.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.

Ping-VorgangPing operation

Wenn der Steuerungskanal für lange Zeit im Leerlauf bleibt, wird die TCP-Verbindung möglicherweise von geplanten Vermittlern, z.B. vom Lastenausgleich oder von NATs, gelöscht.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. Der „ping“-Vorgang vermeidet dies, indem eine kleine Datenmenge durch den Kanal gesendet wird, die alle beteiligten Elemente auf der Netzwerkroute daran erinnert, dass die Verbindung aufrechterhalten werden soll. Der Vorgang dient auch als Aktivitätstest für den 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. Wenn der Ping-Befehl fehlschlägt, sollte der Steuerungskanal als nicht verwendbar angesehen werden und der Listener sollte eine neue Verbindung herstellen.If the ping fails, the control channel should be considered unusable and the listener should reconnect.

AbsenderinteraktionSender interaction

Der Absender verfügt über zwei Interaktionen mit dem Dienst: Er stellt eine Verbindung für ein WebSocket-Element her oder sendet Anforderungen per HTTPS.The sender has two interactions with the service: it connects a Web Socket or it sends requests via HTTPS. Anforderungen können per Absenderrolle nicht über ein WebSocket-Element gesendet werden.Requests cannot be sent over a Web Socket from the sender role.

Connect-VorgangConnect operation

Der „connect“-Vorgang zum Verbinden öffnet einen WebSocket im Dienst, der den Namen der Hybridverbindung sowie ein (optionales, aber standardmäßig erforderliches) Sicherheitstoken bereitstellt, das Berechtigungen zum Senden in der Abfragezeichenfolge überträgt.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. Der Dienst interagiert dann mit dem Listener, wie oben beschrieben. Der Listener erstellt eine Rendezvousverbindung, die mit diesem WebSocket verknüpft wird.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. Nachdem der WebSocket akzeptiert wurde, werden alle weiteren Interaktionen für diesen WebSocket mit dem verbundenen Listener durchgeführt.After the WebSocket has been accepted, all further interactions on that WebSocket are with a connected listener.

Request-VorgangRequest operation

Für Hybridverbindungen, für die das Feature aktiviert wurde, kann der Absender größtenteils unbeschränkte HTTP-Anforderungen an Listener senden.For Hybrid Connections for which the feature has been enabled, the sender can send largely unrestricted HTTP requests to listeners.

Bis auf ein Relay-Zugriffstoken, das entweder in die Abfragezeichenfolge oder einen HTTP-Header der Anforderung eingebettet ist, ist der Relay-Vorgang für alle HTTP-Vorgänge unter der Relay-Adresse und alle Suffixe des Relay-Adresspfads vollständig transparent. Somit verfügt der Listener über die volle Kontrolle der End-to-End-Autorisierung und sogar über HTTP-Erweiterungsfeatures wie 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.

Die Absenderautorisierung für den Relay-Endpunkt ist standardmäßig aktiviert, aber sie ist OPTIONAL.Sender authorization with the Relay endpoint is turned on by default, but is OPTIONAL. Der Besitzer der Hybridverbindung kann auswählen, dass anonyme Absender zulässig sind.The owner of the Hybrid Connection can choose to allow anonymous senders. Der Dienst führt für Autorisierungsinformationen wie folgt das Abfangen, Untersuchen und Entfernen durch:The service will intercept, inspect, and strip authorization information as follows:

  1. Wenn die Abfragezeichenfolge einen sb-hc-token-Ausdruck enthält, wird der Ausdruck IMMER aus der Abfragezeichenfolge entfernt.If the query string contains a sb-hc-token expression, the expression will ALWAYS be stripped from the query string. Die Auswertung erfolgt, wenn die Relay-Autorisierung aktiviert ist.It will be evaluated if Relay authorization is turned on.
  2. Wenn die Anforderungsheader einen ServiceBusAuthorization-Header enthalten, wird der Ausdruck IMMER aus der Headersammlung entfernt.If the request headers contain a ServiceBusAuthorization header, the header expression will ALWAYS be stripped from the header collection. Die Auswertung erfolgt, wenn die Relay-Autorisierung aktiviert ist.It will be evaluated if Relay authorization is turned on.
  3. Für den Header wird die Auswertung und Entfernung nur dann durchgeführt, wenn die Relay-Autorisierung aktiviert ist, die Anforderungsheader einen Authorization-Header enthalten und keiner der obigen Ausdrücke vorhanden ist.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. Andernfalls wird Authorization immer unverändert übergeben.Otherwise, the Authorizationis always passed on as-is.

Falls kein aktiver Listener vorhanden ist, gibt der Dienst den Fehlercode „502 Ungültiges Gateway“ zurück.If there is no active listener, the service will return a 502 "Bad Gateway" error code. Wenn die Anforderung vom Dienst scheinbar nicht verarbeitet wird, gibt der Dienst nach 60 Sekunden „504 Gatewaytimeout“ zurück.If the service does not appear to handle the request, the service will return a 504 "Gateway Timeout" after 60 seconds.

Zusammenfassung der InteraktionInteraction summary

Das Ergebnis dieses Interaktionsmodells ist, dass der Absenderclient den Handshake mit einem „bereinigten“ WebSocket verlässt, der mit einem Listener verbunden ist und keine weitere Präambel oder Vorbereitung benötigt.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. Dieses Modell ermöglicht, dass praktisch alle vorhandenen Implementierungen des WebSocket-Clients den Hybridverbindungsdienst nutzen, indem eine richtig strukturierte URL für die WebSocket-Clientebene angegeben wird.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.

Der WebSocket der Rendezvousverbindung, den der Listener durch die akzeptierten Interaktionen abruft, ist ebenfalls bereinigt und kann mit minimaler zusätzlicher Abstraktion an jede vorhandene WebSocket-Serverimplementierung übergeben werden. Die Abstraktion unterscheidet zwischen „accept“-Vorgängen in den lokalen Netzwerklistenern des Frameworks und den „accept“-Remotevorgängen der Hybridverbindungen.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.

Beim Modell der HTTP-Anforderungen und -Antworten erhält der Absender einen größtenteils unbeschränkten HTTP-Protokolloberflächenbereich mit einer OPTIONALEN Autorisierungsebene.The HTTP request/response model gives the sender a largely unrestricted HTTP protocol surface area with an OPTIONAL authorization layer. Der Listener erhält einen vorab analysierten HTTP-Anforderungsheaderabschnitt, der zurück in eine nachgeschaltete HTTP-Anforderung verwandelt oder unverändert verarbeitet werden kann, wobei binäre Frames mit HTTP-Texten verwendet werden.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. Für Antworten wird das gleiche Format verwendet.Responses use the same format. Interaktionen mit weniger als 64 KB an Anforderungs- und Antworttext können über ein einzelnes WebSocket-Element verarbeitet werden, das für alle Absender gemeinsam verwendet wird.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. Umfangreichere Anforderungen und Antworten können mit dem Rendezvousmodell verarbeitet werden.Larger requests and responses can be handled using the rendezvous model.

ProtokollreferenzProtocol reference

In diesem Abschnitt werden die Details der oben erwähnten Protokollinteraktionen beschrieben.This section describes the details of the protocol interactions described previously.

Alle WebSocket-Verbindungen werden an Port 443 als Upgrade von HTTPS 1.1 durchgeführt, das häufig durch ein WebSocket-Framework oder eine API abstrahiert wird.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. Die Beschreibung hier hält die Implementierung neutral und ohne ein bestimmtes Framework vorzuschlagen.The description here is kept implementation neutral, without suggesting a specific framework.

Listener-ProtokollListener protocol

Das Listener-Protokoll besteht aus zwei Verbindungsgesten und drei Nachrichtenvorgängen.The listener protocol consists of two connection gestures and three message operations.

Verbindung des Listener-SteuerungskanalsListener control channel connection

Der Steuerungskanal wird mit der Erstellung der folgenden WebSocket-Verbindung geöffnet: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=...

Die namespace-address ist der vollqualifizierte Domänenname des Azure Relaynamespace, der die Hybridverbindung hostet, typischerweise in der Form {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.

Der Abfragezeichenfolgenparameter verfügt über folgende Optionen.The query string parameter options are as follows.

ParameterParameter ErforderlichRequired BESCHREIBUNGDescription
sb-hc-action JaYes Für die Listener-Rolle muss der Parameter sb-hc-action=listen lauten.For the listener role, the parameter must be sb-hc-action=listen
{path} JaYes Der URL-codierte Namespacepfad der vorkonfigurierten Hybridverbindung, für die dieser Listener registriert wird.The URL-encoded namespace path of the pre-configured Hybrid Connection to register this listener on. Dieser Ausdruck wird an den festen Pfadteil $hc/ angehängt.This expression is appended to the fixed $hc/ path portion.
sb-hc-token Ja*Yes* Der Listener muss ein gültiges URL-codiertes Service Bus Shared Access-Token für den Namespace bereitstellen, oder eine Hybridverbindung, die Listen (Lauschen) direkt verleiht.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 NeinNo Diese vom Client bereitgestellte optionale ID ermöglicht die End-to-End-Diagnoseablaufverfolgung.This client-supplied optional ID enables end-to-end diagnostic tracing.

Wenn die WebSocket-Verbindung nicht hergestellt werden kann, weil der Pfad der Hybridverbindung nicht registriert ist, ein Token ungültig ist oder fehlt oder ein anderer Fehler vorliegt, wird das Fehlerfeedback mithilfe des regulären HTTP 1.1-Statusinformationsmodells bereitgestellt.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. Die Statusbeschreibung enthält eine Fehlernachverfolgungs-ID, die an die Azure-Supportmitarbeiter übermittelt werden kann:The status description contains an error tracking-id that can be communicated to Azure support personnel:

CodeCode FehlerError BESCHREIBUNGDescription
404404 Nicht gefundenNot Found Der Pfad der Hybridverbindung ist ungültig, oder die Basis-URL ist falsch formatiert.The Hybrid Connection path is invalid or the base URL is malformed.
401401 Nicht autorisiertUnauthorized Das Sicherheitstoken ist nicht vorhanden, falsch formatiert oder ungültig.The security token is missing or malformed or invalid.
403403 VerbotenForbidden Das Sicherheitstoken ist für diesen Pfad für diese Aktion ungültig.The security token is not valid for this path for this action.
500500 Interner FehlerInternal Error Es ist ein Fehler im Dienst aufgetreten.Something went wrong in the service.

Wenn die WebSocket-Verbindung absichtlich durch den Dienst heruntergefahren wird, nachdem sie anfangs eingerichtet wurde, erfolgt die Angabe des Grunds dafür mithilfe eines entsprechenden WebSocket-Protokollfehlercodes sowie mit einer beschreibenden Fehlermeldung, die auch eine Nachverfolgungs-ID enthält.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. Ohne eine erkennbare Fehlerbedingung fährt der Dienst den Steuerungskanal nicht herunter.The service will not shut down the control channel without encountering an error condition. Jedes saubere Herunterfahren wird durch den Client gesteuert.Any clean shutdown is client controlled.

WS-StatusWS Status BESCHREIBUNGDescription
10011001 Der Hybridverbindungspfad wurde gelöscht oder deaktiviert.The Hybrid Connection path has been deleted or disabled.
10081008 Das Sicherheitstoken ist abgelaufen, sodass die Autorisierungsrichtlinie verletzt wurde.The security token has expired, therefore the authorization policy is violated.
10111011 Es ist ein Fehler im Dienst aufgetreten.Something went wrong in the service.

Akzeptieren von HandshakeAccept handshake

Die Benachrichtigung zum Akzeptieren wird vom Dienst als JSON-Nachricht in einem WebSocket-Textrahmen über den zuvor erstellten Steuerungskanal an den Listener übermittelt.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. Es gibt keine Antwort auf diese Nachricht.There is no reply to this message.

Die Nachricht enthält ein JSON-Objekt mit dem Namen „accept“, das zu diesem Zeitpunkt die folgenden Eigenschaften definiert:The message contains a JSON object named "accept", which defines the following properties at this time:

  • address: Die URL-Zeichenfolge, die zum Erstellen des WebSockets für den Dienst verwendet wird, um eingehende Verbindungen zu akzeptieren.address – the URL string to be used for establishing the WebSocket to the service to accept an incoming connection.
  • id: Der eindeutige Bezeichner für diese Verbindung.id – the unique identifier for this connection. Wenn die ID vom Absenderclient angegeben wurde, ist sie der Wert, der vom Absender angegeben wurde. Andernfalls ist sie ein systemgenerierter Wert.If the ID was supplied by the sender client, it is the sender supplied value, otherwise it is a system generated value.
  • connectHeaders: Alle HTTP-Header, die durch den Absender auf dem Relay-Endpunkt angegeben wurden, der ebenso das Sec-WebSocket-Protocol und die Sec-WebSocket-Extensions-Header enthält.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" : "..."
        }
     }
}

Die in der JSON-Nachricht bereitgestellte Adress-URL wird vom Listener verwendet, um den WebSocket zu erstellen, der den Absendersocket akzeptieren oder ablehnen soll.The address URL provided in the JSON message is used by the listener to establish the WebSocket for accepting or rejecting the sender socket.

Akzeptieren des SocketsAccepting the socket

Der Listener erstellt eine WebSocket-Verbindung zu der bereitgestellten Adresse, um zu akzeptieren.To accept, the listener establishes a WebSocket connection to the provided address.

Wenn die Benachrichtigung zum Akzeptieren einen Sec-WebSocket-Protocol-Header enthält, wird erwartet, dass der Listener den WebSocket nur dann akzeptiert, sofern er dieses Protokoll unterstützt.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. Außerdem wird der Header bei der WebSocket-Einrichtung festgelegt.Additionally, it sets the header as the WebSocket is established.

Dasselbe gilt für den Sec-WebSocket-Extensions-Header.The same applies to the Sec-WebSocket-Extensions header. Wenn das Framework eine Erweiterung unterstützt, sollte es den Header auf die serverseitige Antwort des erforderlichen Sec-WebSocket-Extensions-Handshakes für die Erweiterung festlegen.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.

Die URL muss unverändert für die Erstellung des accept-Sockets verwendet werden, doch enthält folgenden Parameter:The URL must be used as-is for establishing the accept socket, but contains the following parameters:

ParameterParameter ErforderlichRequired BESCHREIBUNGDescription
sb-hc-action JaYes Zum Akzeptieren eines Sockets muss der Parameter sb-hc-action=accept lauten.For accepting a socket, the parameter must be sb-hc-action=accept
{path} JaYes (Siehe folgenden Abschnitt.)(see the following paragraph)
sb-hc-id NeinNo Siehe obige Beschreibung von id.See previous description of id.

{path} ist der URL-codierte Namespacepfad der vorkonfigurierten Hybridverbindung, für die dieser Listener registriert werden soll.{path} is the URL-encoded namespace path of the preconfigured Hybrid Connection on which to register this listener. Dieser Ausdruck wird an den festen Pfadteil $hc/ angehängt.This expression is appended to the fixed $hc/ path portion.

Der path-Ausdruck kann mit einem Suffix und einem Abfragezeichenfolgenausdruck erweitert werden, der nach einem trennenden Schrägstrich auf den registrierten Namen folgt.The path expression may be extended with a suffix and a query string expression that follows the registered name after a separating forward slash. Hiermit kann der Absenderclient dispatch-Argumente an den akzeptierenden Listener übergeben, wenn das Einschließen von HTTP-Headern nicht möglich ist.This enables the sender client to pass dispatch arguments to the accepting listener when it is not possible to include HTTP headers. Erwartet wird, dass das Listenerframework den festen Pfadteil und den registrierten Namen aus dem Pfad analysiert und den Rest – unter Umständen ohne Abfragezeichenfolgenargumente mit vorangestelltem sb- – für die Anwendung verfügbar macht, damit diese entscheiden kann, ob die Verbindung akzeptiert wird.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.

Weitere Informationen finden Sie im Abschnitt „Absenderprotokoll“ weiter unten.For more information, see the following "Sender Protocol" section.

Wenn ein Fehler auftritt, kann der Dienst wie folgt reagieren:If there is an error, the service can reply as follows:

CodeCode FehlerError BESCHREIBUNGDescription
403403 VerbotenForbidden Die URL ist nicht gültig.The URL is not valid.
500500 Interner FehlerInternal Error Es ist ein Fehler im Dienst aufgetretenSomething went wrong in the service

Nachdem die Verbindung hergestellt wurde, beendet der Server den WebSocket, wenn der Absender-WebSocket beendet wird oder folgenden Status aufweist:After the connection has been established, the server shuts down the WebSocket when the sender WebSocket shuts down, or with the following status:

WS-StatusWS Status BESCHREIBUNGDescription
10011001 Der Absenderclient beendet die Verbindung.The sender client shuts down the connection.
10011001 Der Hybridverbindungspfad wurde gelöscht oder deaktiviert.The Hybrid Connection path has been deleted or disabled.
10081008 Das Sicherheitstoken ist abgelaufen, sodass die Autorisierungsrichtlinie verletzt wurde.The security token has expired, therefore the authorization policy is violated.
10111011 Es ist ein Fehler im Dienst aufgetreten.Something went wrong in the service.
Ablehnen des SocketsRejecting the socket

Das Ablehnen des Sockets nach dem Untersuchen der accept-Nachricht erfordert einen ähnlichen Handshake, sodass der Statuscode und die Statusbeschreibung, über die der Grund für die Ablehnung mitgeteilt wird, an den Absender zurückgegeben werden können.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.

Gemäß Protokollentwurf wird hier ein WebSocket-Handshake verwendet (der per Entwurf in einem definierten Fehlerstatus endet), sodass Implementierungen von Listenerclients weiterhin auf einem WebSocket-Client basieren können und keinen zusätzlichen reinen HTTP-Client verwenden müssen.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.

Zum Ablehnen des Sockets verwendet der Client den Adress-URI aus der accept-Nachricht und fügt wie folgt zwei Abfragezeichenfolgenparameter an:To reject the socket, the client takes the address URI from the accept message and appends two query string parameters to it, as follows:

ParameterParam ErforderlichRequired BESCHREIBUNGDescription
sb-hc-statusCodesb-hc-statusCode JaYes Numerischer HTTP-Statuscode.Numeric HTTP status code.
sb-hc-statusDescriptionsb-hc-statusDescription JaYes Ein visuell lesbarer Grund für die Ablehnung.Human readable reason for the rejection.

Der resultierende URI wird dann verwendet, um eine WebSocket-Verbindung herzustellen.The resulting URI is then used to establish a WebSocket connection.

Wenn der Vorgang erfolgreich abgeschlossen ist, schlägt dieser Handshake absichtlich mit dem HTTP-Fehlercode 410 fehl, da kein WebSocket erstellt wurde.When completing correctly, this handshake intentionally fails with an HTTP error code 410, since no WebSocket has been established. Im Fehlerfall werden Fehler mit den folgenden Codes beschrieben:If something goes wrong, the following codes describe the error:

CodeCode FehlerError BESCHREIBUNGDescription
403403 VerbotenForbidden Die URL ist nicht gültig.The URL is not valid.
500500 Interner FehlerInternal Error Es ist ein Fehler im Dienst aufgetreten.Something went wrong in the service.

Request-NachrichtRequest message

Die request-Nachricht wird vom Dienst über den Steuerkanal an den Listener gesendet.The request message is sent by the service to the listener over the control channel. Die gleiche Nachricht wird auch über das WebSocket-Rendezvouselement gesendet, nachdem es eingerichtet wurde.The same message is also sent over the rendezvous WebSocket once established.

request besteht aus zwei Teilen: einem Header und einem oder mehreren binären Textframes.The request consists of two parts: a header and binary body frame(s). Wenn kein Text vorhanden ist, werden die Textframes weggelassen.If there is no body, the body frames are omitted. Der Indikator für das Vorhandensein eines Texts ist die boolesche body-Eigenschaft in der „request“-Nachricht.The indicator for whether a body is present is the boolean body property in the request message.

Für eine Anforderung mit einem Anforderungstext kann die Struktur beispielsweise wie folgt aussehen: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...
----------------------------------

Der Listener MUSS den Empfang des Anforderungsheaders, der auf mehrere binäre Frames aufgeteilt ist (siehe WebSocket-Fragmente), verarbeiten können.The listener MUST handle receiving the request body split across multiple binary frames (see WebSocket fragments). Die Anforderung endet, wenn ein binärer Frame mit FIN-Flag empfangen wurde.The request ends when a binary frame with the FIN flag set has been received.

Bei einer Anforderung ohne Text ist nur ein Textframe vorhanden.For a request without a body, there's only one text frame.

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

Der JSON-Inhalt für request lautet wie folgt:The JSON content for request is as follows:

  • address: URI-Zeichenfolge.address - URI string. Dies ist die Rendezvousadresse, die für diese Anforderung verwendet wird.This is the rendezvous address to use for this request. Wenn die eingehende Anforderung größer als 64 KB ist, ist der Rest dieser Nachricht leer, und der Client MUSS einen Rendezvous-Handshake initiieren, der äquivalent zum unten beschriebenen accept-Vorgang ist.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. Anschließend legt der Dienst das vollständige request-Element auf dem eingerichteten WebSocket-Element ab.The service will then put the complete request on the established Web socket. Falls die Antwort voraussichtlich größer als 64 KB ist, MUSS der Listener auch einen Rendezvous-Handshake initiieren und die Antwort dann über das eingerichtete WebSocket-Element übertragen.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: Zeichenfolge.id – string. Der eindeutige Bezeichner für diese Anforderung.The unique identifier for this request.

  • requestHeaders: Dieses Objekt enthält alle HTTP-Header, die vom Absender für den Endpunkt bereitgestellt wurden, mit Ausnahme der Autorisierungsinformationen (wie oben beschrieben) und von Headern, die sich ausschließlich auf die Verbindung mit dem Gateway beziehen.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. Es werden für ALLE Header, die in RFC7230 definiert oder reserviert sind (mit Ausnahme von Via), Entfernungen durchgeführt, und sie werden nicht weitergeleitet:Specifically, ALL headers defined or reserved in RFC7230, except Via, are stripped and not forwarded:

    • Connection (RFC7230, Abschnitt 6.1)Connection (RFC7230, Section 6.1)
    • Content-Length (RFC7230, Abschnitt 3.3.2)Content-Length (RFC7230, Section 3.3.2)
    • Host (RFC7230, Abschnitt 5.4)Host (RFC7230, Section 5.4)
    • TE (RFC7230, Abschnitt 4.3)TE (RFC7230, Section 4.3)
    • Trailer (RFC7230, Abschnitt 4.4)Trailer (RFC7230, Section 4.4)
    • Transfer-Encoding (RFC7230, Abschnitt 3.3.1)Transfer-Encoding (RFC7230, Section 3.3.1)
    • Upgrade (RFC7230, Abschnitt 6.7)Upgrade (RFC7230, Section 6.7)
    • Close (RFC7230, Abschnitt 8.1)Close (RFC7230, Section 8.1)
  • requestTarget: Zeichenfolge.requestTarget – string. Diese Eigenschaft enthält das „Anforderungsziel“ (RFC7230, Abschnitt 5.3) der Anforderung.This property holds the "Request Target" (RFC7230, Section 5.3) of the request. Hierin ist der Abfragezeichenfolgen-Teil enthalten, aus dem ALLE Parameter mit dem Präfix sb-hc- entfernt werden.This includes the query string portion, which is stripped of ALL sb-hc- prefixed parameters.

  • method: Zeichenfolge.method - string. Dies ist die Methode der Anforderung gemäß RFC7231, Abschnitt 4.This is the method of the request, per RFC7231, Section 4. Die CONNECT-Methode darf NICHT verwendet werden.The CONNECT method MUST NOT be used.

  • body: Boolescher Wert.body – boolean. Gibt an, ob ein einzelner Frame oder mehrere Frames mit binärem Text folgen.Indicates whether one or 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
     }
}
Antworten auf AnforderungenResponding to requests

Der Empfänger MUSS antworten.The receiver MUST respond. Wenn eine Antwort auf Anforderungen wiederholt ausbleibt, während die Verbindung besteht, kann dies dazu führen, dass der Listener auf eine Sperrliste gesetzt wird.Repeated failure to respond to requests while maintaining the connection might result in the listener getting blacklisted.

Antworten können in einer beliebigen Reihenfolge gesendet werden, aber auf jede Anforderung muss innerhalb von 60 Sekunden eine Antwort erfolgen, da die Zustellung ansonsten als nicht erfolgreich gemeldet wird.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. Der Zeitraum von 60 Sekunden läuft, bis der response-Frame vom Dienst empfangen wurde.The 60-second deadline is counted until the response frame has been received by the service. Eine aktive Antwort mit mehreren binären Frames darf sich nicht länger als 60 Sekunden im Leerlauf befinden, da sie sonst beendet wird.An ongoing response with multiple binary frames cannot become idle for more than 60 seconds or it is terminated.

Wenn die Anforderung über den Steuerkanal empfangen wird, MUSS die Antwort entweder über den Steuerkanal gesendet werden, über den die Anforderung eingegangen ist, oder sie MUSS über einen Rendezvous-Kanal gesendet werden.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.

Die Antwort ist ein JSON-Objekt mit dem Namen „response“.The response is a JSON object named "response". Die Regeln für die Verarbeitung des Textinhalts entsprechen genau der Verwendung der request-Nachricht und basieren auf der body-Eigenschaft.The rules for handling body content are exactly like with the request message and based on the body property.

  • requestId: Zeichenfolge.requestId – string. REQUIRED. (ERFORDERLICH.)REQUIRED. Der id-Eigenschaftswert der request-Nachricht, auf die geantwortet wird.The id property value of the request message being responded to.
  • statusCode: Zahl.statusCode – number. REQUIRED. (ERFORDERLICH.)REQUIRED. Ein numerischer HTTP-Statuscode, der das Ergebnis der Benachrichtigung angibt.a numerical HTTP status code that indicates the outcome of the notification. Alle Statuscodes aus RFC7231, Abschnitt 6 sind zulässig, mit Ausnahme von 502 „Ungültiges Gateway“ und 504 „Gatewaytimeout“.All status codes of RFC7231, Section 6 are permitted, except for 502 "Bad Gateway" and 504 "Gateway Timeout".
  • statusDescription: Zeichenfolge.statusDescription - string. OPTIONAL.OPTIONAL. HTTP-Statuscode-Ursachentext gemäß RFC7230, Abschnitt 3.1.2HTTP status-code reason phrase per RFC7230, Section 3.1.2
  • responseHeaders: HTTP-Header, die in einer externen HTTP-Antwort festgelegt werden.responseHeaders – HTTP headers to be set in an external HTTP reply. Wie bei request auch, dürfen per RFC7230 definierte Header NICHT verwendet werden.As with the request, RFC7230 defined headers MUST NOT be used.
  • body: Boolescher Wert.body – boolean. Gibt an, ob ein oder mehrere Textframes folgen.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" }
----------------------------------
Antworten per RendezvousResponding via rendezvous

Für Antworten, die größer als 64 KB sind, MUSS die Antwort per Rendezvous-Socket zugestellt werden.For responses that exceed 64 kB, the response MUST be delivered over a rendezvous socket. Falls die Anforderung größer als 64 KB ist und request nur das Adressfeld enthält, muss ein Rendezvous-Socket eingerichtet werden, um das request-Element zu erhalten.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. Nachdem ein Rendezvous-Socket eingerichtet wurde, MÜSSEN Antworten an den jeweiligen Client und nachfolgende Anforderungen vom Client über den Rendezvous-Socket zugestellt werden, solange dieser aktiv ist.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.

Die URL von address im request-Element muss unverändert für die Erstellung des Rendezvous-Sockets verwendet werden, aber sie enthält die folgenden Parameter:The address URL in the request must be used as-is for establishing the rendezvous socket, but contains the following parameters:

ParameterParameter ErforderlichRequired BESCHREIBUNGDescription
sb-hc-action JaYes Zum Akzeptieren eines Sockets muss der Parameter sb-hc-action=request lauten.For accepting a socket, the parameter must be sb-hc-action=request

Wenn ein Fehler auftritt, kann der Dienst wie folgt reagieren:If there is an error, the service can reply as follows:

CodeCode FehlerError BESCHREIBUNGDescription
400400 Ungültige AnforderungInvalid Request Nicht erkannte Aktion oder ungültige URL.Unrecognized action or URL not valid.
403403 VerbotenForbidden Die URL ist abgelaufen.The URL has expired.
500500 Interner FehlerInternal Error Es ist ein Fehler im Dienst aufgetretenSomething went wrong in the service

Nachdem die Verbindung hergestellt wurde, beendet der Server den WebSocket, wenn der HTTP-Socket des Clients beendet wird oder folgenden Status aufweist: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:

WS-StatusWS Status BESCHREIBUNGDescription
10011001 Der Absenderclient beendet die Verbindung.The sender client shuts down the connection.
10011001 Der Hybridverbindungspfad wurde gelöscht oder deaktiviert.The Hybrid Connection path has been deleted or disabled.
10081008 Das Sicherheitstoken ist abgelaufen, sodass die Autorisierungsrichtlinie verletzt wurde.The security token has expired, therefore the authorization policy is violated.
10111011 Es ist ein Fehler im Dienst aufgetreten.Something went wrong in the service.

Erneuerung des ListenertokensListener token renewal

Wenn das Listenertoken abläuft, kann es ersetzt werden, indem über den eingerichteten Steuerungskanal eine Textrahmennachricht an den Dienst gesendet wird.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. Die Nachricht enthält ein JSON-Objekt mit dem Namen renewToken, das derzeit die folgende Eigenschaft definiert:The message contains a JSON object called renewToken, which defines the following property at this time:

  • token: Ein gültiges URL-codiertes Service Bus Shared Access-Token für den Namespace oder eine Hybridverbindung zum direkten Gewähren des Rechts Listen (Lauschen).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"
  }
}

Wenn die Tokenüberprüfung nicht erfolgreich ist, wird der Zugriff verweigert, und der Clouddienst schließt den WebSocket des Steuerkanals mit einem Fehler.If the token validation fails, access is denied, and the cloud service closes the control channel WebSocket with an error. Andernfalls erfolgt keine Antwort.Otherwise there is no reply.

WS-StatusWS Status BESCHREIBUNGDescription
10081008 Das Sicherheitstoken ist abgelaufen, sodass die Autorisierungsrichtlinie verletzt wurde.The security token has expired, therefore the authorization policy is violated.

WebSocket-VerbindungsprotokollWeb Socket connect protocol

Das Absenderprotokoll ist praktisch identisch mit der Erstellung eines Listeners.The sender protocol is effectively identical to the way a listener is established. Das Ziel ist die maximale Transparenz für den End-to-End-WebSocket.The goal is maximum transparency for the end-to-end WebSocket. Die Adresse für die Verbindung ist dieselbe wie für den Listener, aber die „action“ ist anders, und das Token benötigt eine andere Berechtigung: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=...

Die namespace-address ist der vollqualifizierte Domänenname des Azure Relaynamespace, der die Hybridverbindung hostet, typischerweise in der Form {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.

Die Anforderung kann beliebige zusätzliche HTTP-Header enthalten, z.B. auch von der Anwendung definierte Header.The request can contain arbitrary extra HTTP headers, including application-defined ones. Alle angegebenen Header werden an den Listener weitergegeben und befinden sich im connectHeader-Objekt der accept-Steuerungsnachricht.All supplied headers flow to the listener and can be found on the connectHeader object of the accept control message.

Die Optionen des Abfragezeichenfolgenparameters lauten wie folgt:The query string parameter options are as follows:

ParameterParam Erforderlich?Required? BESCHREIBUNGDescription
sb-hc-action JaYes Für die Absenderrolle muss der Parameter sb-hc-action=connect lauten.For the sender role, the parameter must be sb-hc-action=connect.
{path} JaYes (Siehe folgenden Abschnitt.)(see the following paragraph)
sb-hc-token Ja*Yes* Der Listener muss ein gültiges URL-codiertes Service Bus Shared Access-Token für den Namespace oder die Hybridverbindung bereitstellen, das die Berechtigung Senden direkt überträgt.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 NeinNo Eine optionale ID, mit der die End-to-End-Diagnoseablaufverfolgung möglich ist und die während des accept-Handshakes für den Listener verfügbar gemacht wird.An optional ID that enables end-to-end diagnostic tracing and is made available to the listener during the accept handshake.

Der {path} ist der URL-codierte Namespacepfad der vorkonfigurierten Hybridverbindung, für die dieser Listener registriert werden soll.The {path} is the URL-encoded namespace path of the preconfigured Hybrid Connection on which to register this listener. Der path-Ausdruck kann mit einem Suffix und einem Abfragezeichenfolgenausdruck für die weitere Kommunikation erweitert werden.The path expression can be extended with a suffix and a query string expression to communicate further. Wenn die Hybridverbindung unter dem Pfad hyco registriert ist, kann der path-Ausdruck hyco/suffix?param=value&... lauten, gefolgt von den hier definierten Abfragezeichenfolgenparametern.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. Ein vollständiger Ausdruck kann dann wie folgt lauten: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=...

Der path-Ausdruck wird an den Listener in dem Adress-URI übergeben, der in der accept-Steuerungsnachricht enthalten ist.The path expression is passed through to the listener in the address URI contained in the "accept" control message.

Wenn die WebSocket-Verbindung nicht hergestellt werden kann, weil der Pfad der Hybridverbindung nicht registriert ist, ein Token ungültig ist oder fehlt oder ein anderer Fehler vorliegt, wird das Fehlerfeedback mithilfe des regulären HTTP 1.1-Statusinformationsmodells bereitgestellt.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. Die Statusbeschreibung enthält eine Fehlernachverfolgungs-ID, die an die Azure-Supportmitarbeiter übermittelt werden kann:The status description contains an error tracking ID that can be communicated to Azure support personnel:

CodeCode FehlerError BESCHREIBUNGDescription
404404 Nicht gefundenNot Found Der Pfad der Hybridverbindung ist ungültig, oder die Basis-URL ist falsch formatiert.The Hybrid Connection path is invalid or the base URL is malformed.
401401 Nicht autorisiertUnauthorized Das Sicherheitstoken ist nicht vorhanden, falsch formatiert oder ungültig.The security token is missing or malformed or invalid.
403403 VerbotenForbidden Das Sicherheitstoken ist für diesen Pfad und für diese Aktion ungültig.The security token is not valid for this path and for this action.
500500 Interner FehlerInternal Error Es ist ein Fehler im Dienst aufgetreten.Something went wrong in the service.

Wenn die WebSocket-Verbindung absichtlich durch den Dienst heruntergefahren wird, nachdem sie anfangs eingerichtet wurde, erfolgt die Angabe des Grunds dafür mithilfe eines entsprechenden WebSocket-Protokollfehlercodes sowie mit einer beschreibenden Fehlermeldung, die auch eine Nachverfolgungs-ID enthält.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.

WS-StatusWS Status BESCHREIBUNGDescription
10001000 Der Listener beendet den Socket.The listener shut down the socket.
10011001 Der Hybridverbindungspfad wurde gelöscht oder deaktiviert.The Hybrid Connection path has been deleted or disabled.
10081008 Das Sicherheitstoken ist abgelaufen, sodass die Autorisierungsrichtlinie verletzt wurde.The security token has expired, therefore the authorization policy is violated.
10111011 Es ist ein Fehler im Dienst aufgetreten.Something went wrong in the service.

HTTP-AnforderungsprotokollHTTP request protocol

Das HTTP-Anforderungsprotokoll ermöglicht beliebige HTTP-Anforderungen, mit Ausnahme von Protokollupgrades.The HTTP request protocol allows arbitrary HTTP requests, except protocol upgrades. Für HTTP-Anforderungen wird auf die reguläre Laufzeitadresse der Entität verwiesen, aber ohne das Infix $hc, das für WebSocket-Clients von Hybridverbindungen verwendet wird.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=...

Die namespace-address ist der vollqualifizierte Domänenname des Azure Relaynamespace, der die Hybridverbindung hostet, typischerweise in der Form {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.

Die Anforderung kann beliebige zusätzliche HTTP-Header enthalten, z.B. auch von der Anwendung definierte Header.The request can contain arbitrary extra HTTP headers, including application-defined ones. Alle bereitgestellten Header – mit Ausnahme der direkt in RFC7230 definierten (siehe Request-Nachricht) – fließen an den Listener und befinden sich im requestHeader-Objekt der request-Nachricht.All supplied headers, except those directly defined in RFC7230 (see Request message) flow to the listener and can be found on the requestHeader object of the request message.

Die Optionen des Abfragezeichenfolgenparameters lauten wie folgt:The query string parameter options are as follows:

ParameterParam Erforderlich?Required? BESCHREIBUNGDescription
sb-hc-token Ja*Yes* Der Listener muss ein gültiges URL-codiertes Service Bus Shared Access-Token für den Namespace oder die Hybridverbindung bereitstellen, das die Berechtigung Senden direkt überträgt.The listener must provide a valid, URL-encoded Service Bus Shared Access Token for the namespace or Hybrid Connection that confers the Send right.

Das Token kann auch im HTTP-Header ServiceBusAuthorization oder Authorization enthalten sein.The token can also be carried in either the ServiceBusAuthorization or Authorization HTTP header. Das Token kann weggelassen werden, wenn die Hybridverbindung so konfiguriert ist, dass anonyme Anforderungen zulässig sind.The token can be omitted if the Hybrid Connection is configured to permit anonymous requests.

Da der Dienst quasi als Proxy fungiert (wenn auch nicht wie ein echter HTTP-Proxy), fügt er entweder einen Via-Header hinzu oder fügt entsprechend gemäß RFC7230, Abschnitt 5.7.1 Anmerkungen an den vorhandenen Via-Header an.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. Der Dienst fügt den Hostnamen des Relay-Namespace an Via an.The service adds the Relay namespace hostname to Via.

CodeCode MessageMessage BESCHREIBUNGDescription
200200 OKOK Die Anforderung wurde von mindestens einem Listener verarbeitet.The request has been handled by at least one listener.
202202 ZulässigAccepted Die Anforderung wurde von mindestens einem Listener akzeptiert.The request has been accepted by at least one listener.

Wenn ein Fehler auftritt, kann der Dienst wie folgt reagieren.If there is an error, the service can reply as follows. Anhand des Vorhandenseins des Via-Headers kann identifiziert werden, ob die Antwort vom Dienst oder vom Listener stammt.Whether the response originates from the service or from the listener can be identified through presence of the Via header. Wenn der Header vorhanden ist, stammt die Antwort vom Listener.If the header is present, the response is from the listener.

CodeCode FehlerError BESCHREIBUNGDescription
404404 Nicht gefundenNot Found Der Pfad der Hybridverbindung ist ungültig, oder die Basis-URL ist falsch formatiert.The Hybrid Connection path is invalid or the base URL is malformed.
401401 Nicht autorisiertUnauthorized Das Sicherheitstoken ist nicht vorhanden, falsch formatiert oder ungültig.The security token is missing or malformed or invalid.
403403 VerbotenForbidden Das Sicherheitstoken ist für diesen Pfad und für diese Aktion ungültig.The security token is not valid for this path and for this action.
500500 Interner FehlerInternal Error Es ist ein Fehler im Dienst aufgetreten.Something went wrong in the service.
503503 Ungültiges GatewayBad Gateway Die Anforderung konnte nicht an einen Listener weitergeleitet werden.The request could not be routed to any listener.
504504 GatewaytimeoutGateway Timeout Die Anforderung wurde an einen Listener weitergeleitet, aber der Listener hat den Empfang nicht innerhalb des erforderlichen Zeitraums bestätigt.The request was routed to a listener, but the listener did not acknowledge receipt in the required time.

Nächste SchritteNext steps