Protocolo de Conexões Híbridas de Retransmissão do Azure

O Azure Relay é um dos principais pilares de capacidade da plataforma Azure Service Bus. A nova capacidade de Conexões Híbridas do Relay é uma evolução segura e de protocolo aberto baseada em HTTP e WebSockets. Ele substitui o primeiro, igualmente chamado recurso de Serviços BizTalk que foi construído sobre uma base de protocolo proprietário. A integração de Conexões Híbridas nos Serviços de Aplicativo do Azure continuará a funcionar como está.

As Conexões Híbridas permitem comunicação bidirecional, solicitação-resposta e fluxo binário, além de fluxo de datagrama simples entre dois aplicativos em rede. Qualquer uma ou ambas as partes podem estar por trás de NATs ou firewalls.

Este artigo descreve as interações do lado do cliente com a retransmissão de conexões híbridas para conectar clientes nas funções de ouvinte e remetente. Ele também descreve como os ouvintes aceitam novas conexões e solicitações.

Modelo de interação

O relé de Conexões Híbridas conecta duas partes fornecendo um ponto de encontro na nuvem do Azure que as partes podem descobrir e se conectar da perspetiva de sua própria rede. O ponto de encontro é chamado de "Conexão híbrida" nesta e em outra documentação, nas APIs e também no portal do Azure. O ponto de extremidade do serviço Conexões Híbridas é chamado de "serviço" para o restante deste artigo.

O serviço permite a retransmissão de conexões Web Socket e solicitações e respostas HTTP(S).

O modelo de interação se apoia na nomenclatura estabelecida por muitas outras APIs de rede. Há um ouvinte que primeiro indica a prontidão para lidar com conexões de entrada e, posteriormente, as aceita quando elas chegam. Por outro lado, um cliente se conecta com o ouvinte, esperando que essa conexão seja aceita para estabelecer um caminho de comunicação bidirecional. "Conectar", "Ouvir" e "Aceitar" são os mesmos termos que você encontra na maioria das APIs de soquete.

Qualquer modelo de comunicação retransmitida tem qualquer uma das partes fazendo conexões de saída para um ponto de extremidade de serviço. Isso torna o "ouvinte" também um "cliente" no uso coloquial, podendo também causar outras sobrecargas terminológicas. A terminologia precisa, portanto, usada para conexões híbridas é a seguinte:

Os programas em ambos os lados de uma conexão são chamados de "clientes", uma vez que são clientes do serviço. O cliente que espera e aceita conexões é o "ouvinte", ou seja, está no "papel de ouvinte". O cliente que inicia uma nova conexão com um ouvinte por meio do serviço é chamado de "remetente" ou está na "função de remetente".

Interações com ouvintes

O ouvinte tem cinco interações com o serviço; Todos os detalhes do fio são descritos mais adiante neste artigo na seção Referência.

As mensagens Ouvir, Aceitar e Solicitar são recebidas do serviço. As operações Renovar e Ping são enviadas pelo ouvinte.

Ouvir mensagem

Para indicar a prontidão para o serviço de que um ouvinte está pronto para aceitar conexões, ele cria uma conexão WebSocket de saída. O handshake de conexão carrega o nome de uma Conexão Híbrida configurada no namespace Relay e um token de segurança que confere o direito "Listen" a esse nome.

Quando o WebSocket é aceito pelo serviço, o registro é concluído e o WebSocket estabelecido é mantido vivo como o "canal de controle" para permitir todas as interações subsequentes. O serviço permite até 25 ouvintes simultâneos para uma conexão híbrida. A cota para AppHooks deve ser determinada.

Para Conexões Híbridas, se houver dois ou mais ouvintes ativos, as conexões de entrada serão balanceadas entre eles em ordem aleatória; a distribuição equitativa é tentada com o melhor esforço.

Aceitar mensagem

Quando um remetente abre uma nova conexão no serviço, o serviço escolhe e notifica um dos ouvintes ativos na Conexão Híbrida. Essa notificação é enviada ao ouvinte pelo canal de controle aberto como uma mensagem JSON. A mensagem contém a URL do ponto de extremidade WebSocket ao qual o ouvinte deve se conectar para aceitar a conexão.

O URL pode e deve ser usado diretamente pelo ouvinte sem qualquer trabalho extra. As informações codificadas só são válidas por um curto período de tempo, essencialmente enquanto o remetente estiver disposto a esperar que a conexão seja estabelecida de ponta a ponta. O máximo a assumir é de 30 segundos. O URL só pode ser usado para uma tentativa de conexão bem-sucedida. Assim que a conexão WebSocket com a URL de encontro é estabelecida, toda a atividade adicional neste WebSocket é retransmitida de e para o remetente. Este comportamento acontece sem qualquer intervenção ou interpretação por parte do serviço.

Solicitar mensagem

Além das conexões WebSocket, o ouvinte também pode receber quadros de solicitação HTTP de um remetente, se esse recurso estiver explicitamente habilitado na Conexão Híbrida.

Os ouvintes que se conectam a conexões híbridas com suporte HTTP DEVEM manipular o request gesto. Um ouvinte que não manipula request e, portanto, causa erros repetidos de tempo limite ao estar conectado PODE ser bloqueado pelo serviço no futuro.

Os metadados do cabeçalho do quadro HTTP são convertidos em JSON para um tratamento mais simples pela estrutura do ouvinte, também porque as bibliotecas de análise de cabeçalho HTTP são mais raras do que os analisadores JSON. Os metadados HTTP que são relevantes apenas para a relação entre o remetente e o gateway HTTP de retransmissão, incluindo informações de autorização, não são encaminhados. Os corpos de solicitação HTTP são transferidos de forma transparente como quadros binários WebSocket.

O ouvinte pode responder a solicitações HTTP usando um gesto de resposta equivalente.

O fluxo de solicitação/resposta usa o canal de controle por padrão, mas pode ser "atualizado" para um WebSocket de encontro distinto sempre que necessário. Conexões WebSocket distintas melhoram a taxa de transferência para cada conversa do cliente, mas sobrecarregam o ouvinte com mais conexões que precisam ser tratadas, o que pode não ser desejável para clientes leves.

No canal de controle, os órgãos de solicitação e resposta são limitados a, no máximo, 64 kB de tamanho. Os metadados do cabeçalho HTTP estão limitados a um total de 32 kB. Se a solicitação ou a resposta exceder esse limite, o ouvinte DEVE atualizar para um WebSocket de encontro usando um gesto equivalente a manipular o Accept.

Para solicitações, o serviço decide se encaminha as solicitações pelo canal de controle. Isso inclui, mas não pode ser limitado a casos em que uma solicitação excede 64 kB (cabeçalhos mais corpo) definitivamente, ou se a solicitação é enviada com codificação de transferência "em partes" e o serviço tem motivos para esperar que a solicitação exceda 64 kB ou a leitura da solicitação não seja instantânea. Se o serviço optar por entregar o pedido em vez do encontro, ele apenas passa o endereço do encontro para o ouvinte. O ouvinte então DEVE estabelecer o WebSocket de encontro e o serviço prontamente entrega a solicitação completa, incluindo corpos sobre o WebSocket de encontro. A resposta DEVE também usar o WebSocket de encontro.

Para solicitações que chegam pelo canal de controle, o ouvinte decide se deseja responder pelo canal de controle ou via encontro. O serviço DEVE incluir um endereço de encontro com cada solicitação roteada pelo canal de controle. Este endereço só é válido para atualizar a partir da solicitação atual.

Se o ouvinte optar por atualizar, ele se conecta e prontamente entrega a resposta através do soquete de encontro estabelecido.

Uma vez que o WebSocket de encontro tenha sido estabelecido, o ouvinte DEVE mantê-lo para tratamento adicional de solicitações e respostas do mesmo cliente. O serviço manterá o WebSocket enquanto a conexão do soquete HTTPS com o remetente persistir e roteará todas as solicitações subsequentes desse remetente pelo WebSocket mantido. Se o ouvinte optar por descartar o WebSocket de encontro de seu lado, o serviço também descartará a conexão com o remetente, independentemente de uma solicitação subsequente já estar em andamento.

Renovar operação

O token de segurança que deve ser usado para registrar o ouvinte e manter o canal de controle pode expirar enquanto o ouvinte estiver ativo. A expiração do token não afeta as conexões contínuas, mas faz com que o canal de controle seja descartado pelo serviço no momento do vencimento ou logo após o vencimento. A operação "renovar" é uma mensagem JSON que o ouvinte pode enviar para substituir o token associado ao canal de controle, para que o canal de controle possa ser mantido por períodos prolongados.

Operação de ping

Se o canal de controle permanecer ocioso por um longo tempo, intermediários no caminho, como balanceadores de carga ou NATs podem descartar a conexão TCP. A operação "ping" evita isso, enviando uma pequena quantidade de dados no canal que lembra a todos na rota da rede que a conexão deve estar viva, e também serve como um teste "ao vivo" para o ouvinte. Se o ping falhar, o canal de controle deve ser considerado inutilizável e o ouvinte deve se reconectar.

Interação com o remetente

O remetente tem duas interações com o serviço: ele conecta um Web Socket ou envia solicitações via HTTPS. As solicitações não podem ser enviadas por um Web Socket da função de remetente.

Operação de conexão

A operação "connect" abre um WebSocket no serviço, fornecendo o nome da Conexão Híbrida e (opcionalmente, mas exigido por padrão) um token de segurança que confere permissão "Enviar" na cadeia de caracteres de consulta. Em seguida, o serviço interage com o ouvinte da maneira descrita anteriormente, e o ouvinte cria uma conexão de encontro que é unida a esse WebSocket. Depois que o WebSocket for aceito, todas as outras interações nesse WebSocket serão com um ouvinte conectado.

Solicitar operação

Para Conexões Híbridas para as quais o recurso foi habilitado, o remetente pode enviar solicitações HTTP amplamente irrestritas aos ouvintes.

Exceto para um token de acesso de retransmissão que está incorporado na cadeia de caracteres de consulta ou em um cabeçalho HTTP da solicitação, o relé é totalmente transparente para todas as operações HTTP no endereço de retransmissão e todos os sufixos do caminho de endereço de retransmissão, deixando o ouvinte totalmente no controle da autorização de ponta a ponta e até mesmo de recursos de extensão HTTP como CORS.

A autorização do remetente com o ponto de extremidade de retransmissão está ativada por padrão, mas é OPCIONAL. O proprietário da Conexão Híbrida pode optar por permitir remetentes anônimos. O serviço intercetará, inspecionará e removerá as informações de autorização da seguinte maneira:

1. Se a cadeia de caracteres de consulta contiver uma sb-hc-token expressão, a expressão será SEMPRE removida da cadeia de caracteres de consulta. Será avaliado se a autorização de retransmissão está ativada.
2. Se os cabeçalhos de solicitação contiverem um ServiceBusAuthorization cabeçalho, a expressão de cabeçalho será SEMPRE removida da coleção de cabeçalhos. Será avaliado se a autorização de retransmissão está ativada.
3. Somente se a autorização de retransmissão estiver ativada e se os cabeçalhos de solicitação contiverem um Authorization cabeçalho e nenhuma das expressões anteriores estiver presente, o cabeçalho será avaliado e removido. Caso contrário, o Authorizationé sempre passado como está.

Se não houver nenhum ouvinte ativo, o serviço retornará um código de erro 502 "Bad Gateway". Se o serviço não parecer lidar com a solicitação, o serviço retornará um "Tempo limite de gateway" 504 após 60 segundos.

Resumo da interação

O resultado desse modelo de interação é que o cliente remetente sai do handshake com um WebSocket "limpo", que é conectado a um ouvinte e que não precisa de mais preâmbulos ou preparação. Esse modelo permite que praticamente qualquer implementação de cliente WebSocket existente aproveite prontamente o serviço Conexões Híbridas, fornecendo uma URL construída corretamente em sua camada de cliente WebSocket.

O WebSocket de conexão de encontro que o ouvinte obtém através da interação accept também é limpo e pode ser entregue a qualquer implementação de servidor WebSocket existente com alguma abstração extra mínima que distingue entre operações de "aceitação" nos ouvintes de rede local de sua estrutura e operações de "aceitação" remota de Conexões Híbridas.

O modelo de solicitação/resposta HTTP fornece ao remetente uma área de superfície do protocolo HTTP amplamente irrestrita com uma camada de autorização OPCIONAL. O ouvinte obtém uma seção de cabeçalho de solicitação HTTP pré-analisada que pode ser transformada novamente em uma solicitação HTTP downstream ou tratada como está, com quadros binários carregando corpos HTTP. As respostas usam o mesmo formato. As interações com menos de 64 KB de corpo de solicitação e resposta podem ser tratadas em um único Web Socket compartilhado para todos os remetentes. Solicitações e respostas maiores podem ser tratadas usando o modelo de encontro.

Referência do protocolo

Esta seção descreve os detalhes das interações de protocolo descritas anteriormente.

Todas as conexões WebSocket são feitas na porta 443 como uma atualização do HTTPS 1.1, que é comumente abstraído por alguma estrutura WebSocket ou API. A descrição aqui manteve a implementação neutra, sem sugerir uma estrutura específica.

Protocolo de ouvinte

O protocolo de ouvinte consiste em dois gestos de conexão e três operações de mensagem.

Conexão do canal de controle do ouvinte

O canal de controle é aberto com a criação de uma conexão WebSocket para:

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

O namespace-address é o nome de domínio totalmente qualificado do namespace Azure Relay que hospeda a Conexão Híbrida, normalmente do formato {myname}.servicebus.windows.net.

As opções de parâmetro da cadeia de caracteres de consulta são as seguintes.

Parâmetro	Obrigatório	Descrição
sb-hc-action	Sim	Para a função de ouvinte, o parâmetro deve ser sb-hc-action=listen
{path}	Sim	O caminho de namespace codificado por URL da Conexão Híbrida pré-configurada para registrar esse ouvinte. Esta expressão é anexada à parte do caminho fixo $hc/ .
sb-hc-token	Sim*	O ouvinte deve fornecer um Token de Acesso Compartilhado do Service Bus válido e codificado por URL para o namespace ou Conexão Híbrida que confere o direito Ouvir .
sb-hc-id	Não	Esse ID opcional fornecido pelo cliente permite o rastreamento de diagnóstico de ponta a ponta.

Se a conexão WebSocket falhar devido ao caminho de conexão híbrida não estar registrado, ou um token inválido ou ausente, ou algum outro erro, o feedback de erro é fornecido usando o modelo de feedback de status HTTP 1.1 regular. A descrição de status contém uma id de rastreamento de erros que pode ser comunicada à equipe de suporte do Azure:

Código	Erro	Descrição
404	Não Encontrado	O caminho de conexão híbrida é inválido ou a URL base está malformada.
401	Não autorizado	O token de segurança está ausente ou malformado ou inválido.
403	Proibido	O token de segurança não é válido para este caminho para esta ação.
500	Erro interno	Algo correu mal no serviço.

Se a conexão WebSocket for intencionalmente desligada pelo serviço depois de ter sido configurada inicialmente, o motivo para fazer isso é comunicado usando um código de erro de protocolo WebSocket apropriado, juntamente com uma mensagem de erro descritiva que também inclui um ID de rastreamento. O serviço não desligará o canal de controle sem encontrar uma condição de erro. Qualquer desligamento limpo é controlado pelo cliente.

WS Status	Descrição
1001	O caminho de conexão híbrida foi excluído ou desativado.
1008	O token de segurança expirou, portanto, a política de autorização foi violada.
1011	Algo correu mal no serviço.

Aceitar aperto de mão

A notificação "aceitar" é enviada pelo serviço ao ouvinte através do canal de controle previamente estabelecido como uma mensagem JSON em um quadro de texto WebSocket. Não há resposta para esta mensagem.

A mensagem contém um objeto JSON chamado "accept", que define as seguintes propriedades no momento:

• address – a cadeia de caracteres de URL a ser usada para estabelecer o WebSocket para o serviço para aceitar uma conexão de entrada.
• id – o identificador exclusivo para esta conexão. Se o ID foi fornecido pelo cliente remetente, é o valor fornecido pelo remetente, caso contrário, é um valor gerado pelo sistema.
• connectHeaders – todos os cabeçalhos HTTP que foram fornecidos ao ponto de extremidade Relay pelo remetente, que também inclui os cabeçalhos Sec-WebSocket-Protocol e Sec-WebSocket-Extensions .

{
    "accept" : {
        "address" : "wss://dc-node.servicebus.windows.net:443/$hc/{path}?...",
        "id" : "4cb542c3-047a-4d40-a19f-bdc66441e736",
        "connectHeaders" : {
            "Host" : "...",
            "Sec-WebSocket-Protocol" : "...",
            "Sec-WebSocket-Extensions" : "..."
        }
     }
}

A URL de endereço fornecida na mensagem JSON é usada pelo ouvinte para estabelecer o WebSocket para aceitar ou rejeitar o soquete do remetente.

Aceitar a tomada

Para aceitar, o ouvinte estabelece uma conexão WebSocket com o endereço fornecido.

Se a mensagem "accept" carrega um Sec-WebSocket-Protocol cabeçalho, espera-se que o ouvinte só aceite o WebSocket se ele suportar esse protocolo. Além disso, ele define o cabeçalho como o WebSocket é estabelecido.

O mesmo se aplica ao Sec-WebSocket-Extensions cabeçalho. Se a estrutura suportar uma extensão, ela deverá definir o cabeçalho para a resposta do lado do servidor do handshake necessário Sec-WebSocket-Extensions para a extensão.

A URL deve ser usada como está para estabelecer o soquete de aceitação, mas contém os seguintes parâmetros:

Parâmetro	Obrigatório	Descrição
sb-hc-action	Sim	Para aceitar um soquete, o parâmetro deve ser sb-hc-action=accept
{path}	Sim	(ver parágrafo seguinte)
sb-hc-id	Não	Ver descrição anterior do id.

{path} é o caminho de namespace codificado por URL da Conexão Híbrida pré-configurada na qual registrar esse ouvinte. Esta expressão é anexada à parte do caminho fixo $hc/ .

A path expressão pode ser estendida com um sufixo e uma expressão de cadeia de caracteres de consulta que segue o nome registrado após uma barra de separação para frente. Esse parâmetro permite que o cliente remetente passe argumentos de despacho para o ouvinte aceitante quando não for possível incluir cabeçalhos HTTP. A expectativa é que a estrutura do ouvinte analise a parte do caminho fixo e o nome registrado do caminho e disponibilize o restante, possivelmente sem argumentos de cadeia de caracteres de consulta prefixados por sb-, para o aplicativo decidir se aceita a conexão.

Para obter mais informações, consulte a seguinte seção "Protocolo do remetente".

Se houver um erro, o serviço pode responder da seguinte forma:

Código	Erro	Descrição
403	Proibido	O URL não é válido.
500	Erro interno	Algo correu mal no serviço

Depois que a conexão for estabelecida, o servidor desligará o WebSocket quando o WebSocket remetente for desligado ou com o seguinte status:

WS Status	Descrição
1001	O cliente remetente desliga a conexão.
1001	O caminho de conexão híbrida foi excluído ou desativado.
1008	O token de segurança expirou, portanto, a política de autorização foi violada.
1011	Algo correu mal no serviço.

Rejeitando o soquete

Rejeitar o soquete depois de inspecionar a accept mensagem requer um handshake semelhante para que o código de status e a descrição do status comunicando o motivo da rejeição possam fluir de volta para o remetente.

A escolha de design de protocolo aqui é usar um handshake WebSocket (que é projetado para terminar em um estado de erro definido) para que as implementações de cliente ouvinte possam continuar a depender de um cliente WebSocket e não precisem empregar um cliente HTTP nu extra.

Para rejeitar o soquete, o cliente obtém o URI de endereço da mensagem e acrescenta dois parâmetros de cadeia de caracteres de consulta a ele, da accept seguinte maneira:

Param	Obrigatório	Descrição
sb-hc-statusCode	Sim	Código de status HTTP numérico.
sb-hc-statusDescrição	Sim	Motivo legível humano para a rejeição.

O URI resultante é usado para estabelecer uma conexão WebSocket.

Ao completar corretamente, esse handshake falha intencionalmente com um código de erro HTTP 410, uma vez que nenhum WebSocket foi estabelecido. Se algo correr mal, os seguintes códigos descrevem o erro:

Código	Erro	Descrição
403	Proibido	O URL não é válido.
500	Erro interno	Algo correu mal no serviço.

Solicitar mensagem

A request mensagem é enviada pelo serviço para o ouvinte através do canal de controle. A mesma mensagem também é enviada através do WebSocket de encontro uma vez estabelecido.

O request consiste em duas partes: um cabeçalho e quadro(s) de corpo binário. Se não houver corpo, as armações corporais são omitidas. A propriedade boolean body indica se um corpo está presente na mensagem de solicitação.

Para uma solicitação com um corpo de solicitação, a estrutura pode ter esta aparência:

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

O ouvinte DEVE lidar com o recebimento do corpo da solicitação dividido em vários quadros binários (consulte Fragmentos WebSocket). A solicitação termina quando um quadro binário com o conjunto de sinalizadores FIN foi recebido.

Para uma solicitação sem corpo, há apenas um quadro de texto.

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

O conteúdo JSON para request é o seguinte:

• address - cadeia de caracteres URI. É o endereço de encontro a ser usado para essa solicitação. Se a solicitação de entrada for maior que 64 kB, o restante desta mensagem será deixado vazio e o cliente DEVE iniciar um handshake de encontro equivalente à accept operação descrita abaixo. O serviço colocará o completo request no soquete da Web estabelecido. Se se pode esperar que a resposta exceda 64 kB, o ouvinte DEVE também iniciar um handshake de encontro e, em seguida, transferir a resposta através do Web socket estabelecido.

• id – string. O identificador exclusivo para esta solicitação.

• requestHeaders – este objeto contém todos os cabeçalhos HTTP que foram fornecidos ao ponto de extremidade pelo remetente, com exceção das informações de autorização, conforme explicado acima, e cabeçalhos que se relacionam estritamente com a conexão com o gateway. Especificamente, TODOS os cabeçalhos definidos ou reservados em RFC7230, exceto Via, são removidos e não encaminhados:

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

• requestTarget – cadeia de caracteres. Esta propriedade contém o "Destino da solicitação" (RFC7230, Seção 5.3) da solicitação. Ele inclui a parte da cadeia de caracteres de consulta, que é despojada de TODOS os sb-hc- parâmetros prefixados.

• método - string. Este é o método do pedido, por RFC7231, Secção 4. O CONNECT método NÃO DEVE ser utilizado.

• corpo – booleano. Indica se um ou mais quadros binários de corpo seguem.

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

Responder a pedidos

O recetor DEVE responder. A falha repetida em responder às solicitações enquanto mantém a conexão pode resultar no bloqueio do ouvinte.

As respostas podem ser enviadas em qualquer ordem, mas cada solicitação deve ser respondida dentro de 60 segundos ou a entrega será relatada como tendo falhado. O prazo de 60 segundos é contado até que o response quadro tenha sido recebido pelo serviço. Uma resposta contínua com vários quadros binários não pode ficar ociosa por mais de 60 segundos ou é encerrada.

Se a solicitação for recebida pelo canal de controle, a resposta DEVE ser enviada no canal de controle de onde a solicitação foi recebida ou DEVE ser enviada por um canal de encontro.

A resposta é um objeto JSON chamado "response". As regras para lidar com o conteúdo do corpo são exatamente como com a request mensagem e com base na body propriedade.

• requestId – string. NECESSÁRIO. O id valor da propriedade da mensagem que está sendo respondida request .
• statusCode – número. NECESSÁRIO. um código de status HTTP numérico que indica o resultado da notificação. Todos os códigos de status de RFC7231, Seção 6 são permitidos, exceto para 502 "Bad Gateway" e 504 "Gateway Timeout".
• statusDescription - string. OPCIONAL. Frase de razão do código de status HTTP por RFC7230, Seção 3.1.2
• responseHeaders – cabeçalhos HTTP a serem definidos em uma resposta HTTP externa. Tal como acontece com o request, RFC7230 cabeçalhos definidos NÃO DEVEM ser usados.
• corpo – booleano. Indica se o(s) quadro(s) de corpo binário segue(m).

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

Responder via rendezvous

Para respostas que excedam 64 kB, a resposta DEVE ser entregue através de um soquete de encontro. Além disso, se a solicitação exceder 64 kB, e o único contiver o campo de endereço, um soquete de encontro deve ser estabelecido para obter o requestrequest. Uma vez que um soquete de encontro tenha sido estabelecido, as respostas ao respetivo cliente e solicitações subsequentes desse respetivo cliente DEVEM ser entregues através do soquete de encontro enquanto ele persistir.

A address URL no request deve ser usada como está para estabelecer o soquete de encontro, mas contém os seguintes parâmetros:

Parâmetro	Obrigatório	Descrição
sb-hc-action	Sim	Para aceitar um soquete, o parâmetro deve ser sb-hc-action=request

Se houver um erro, o serviço pode responder da seguinte forma:

Código	Erro	Descrição
400	Pedido inválido	Ação não reconhecida ou URL não válido.
403	Proibido	O URL expirou.
500	Erro interno	Algo correu mal no serviço

Depois que a conexão for estabelecida, o servidor desligará o WebSocket quando o soquete HTTP do cliente for desligado ou com o seguinte status:

WS Status	Descrição
1001	O cliente remetente desliga a conexão.
1001	O caminho de conexão híbrida foi excluído ou desativado.
1008	O token de segurança expirou, portanto, a política de autorização foi violada.
1011	Algo correu mal no serviço.

Renovação do token do ouvinte

Quando o token de ouvinte está prestes a expirar, ele pode substituí-lo enviando uma mensagem de quadro de texto para o serviço através do canal de controle estabelecido. A mensagem contém um objeto JSON chamado renewToken, que define a seguinte propriedade neste momento:

• token – um token de Acesso Compartilhado do Service Bus codificado por URL válido para o namespace ou Conexão Híbrida que confere o direito de Escutar .

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

Se a validação do token falhar, o acesso será negado e o serviço de nuvem fechará o canal de controle WebSocket com um erro. Caso contrário, não há resposta.

WS Status	Descrição
1008	O token de segurança expirou, portanto, a política de autorização foi violada.

Protocolo de conexão de soquete da Web

O protocolo do remetente é efetivamente idêntico à forma como um ouvinte é estabelecido. O objetivo é a máxima transparência para o WebSocket de ponta a ponta. O endereço ao qual se conectar é o mesmo que para o ouvinte, mas a "ação" difere e o token precisa de uma permissão diferente:

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

O namespace-address é o nome de domínio totalmente qualificado do namespace Azure Relay que hospeda a Conexão Híbrida, normalmente do formato {myname}.servicebus.windows.net.

A solicitação pode conter cabeçalhos HTTP adicionais arbitrários, incluindo cabeçalhos definidos pelo aplicativo. Todos os cabeçalhos fornecidos fluem para o ouvinte e podem ser encontrados no connectHeader objeto da mensagem de controle accept .

As opções de parâmetro da cadeia de caracteres de consulta são as seguintes:

Param	Necessário?	Descrição
sb-hc-action	Sim	Para a função de remetente, o parâmetro deve ser sb-hc-action=connect.
{path}	Sim	(ver parágrafo seguinte)
sb-hc-token	Sim*	O ouvinte deve fornecer um Token de Acesso Compartilhado do Service Bus válido e codificado por URL para o namespace ou Conexão Híbrida que confere o direito Enviar .
sb-hc-id	Não	Uma ID opcional que permite o rastreamento de diagnóstico de ponta a ponta e é disponibilizada para o ouvinte durante o handshake de aceitação.

O {path} é o caminho de namespace codificado por URL da Conexão Híbrida pré-configurada na qual registrar esse ouvinte. A path expressão pode ser estendida com um sufixo e uma expressão de cadeia de caracteres de consulta para se comunicar ainda mais. Se a Conexão Híbrida estiver registrada sob o caminho hyco, a path expressão poderá ser hyco/suffix?param=value&... seguida pelos parâmetros da cadeia de caracteres de consulta definidos aqui. Uma expressão completa pode então ser a seguinte:

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

A path expressão é passada para o ouvinte no endereço URI contido na mensagem de controle "accept".

Se a conexão WebSocket falhar devido ao caminho de conexão híbrida não estar registrado, um token inválido ou ausente ou algum outro erro, o feedback de erro será fornecido usando o modelo de feedback de status HTTP 1.1 regular. A descrição de status contém uma ID de controle de erros que pode ser comunicada à equipe de suporte do Azure:

Código	Erro	Descrição
404	Não Encontrado	O caminho de conexão híbrida é inválido ou a URL base está malformada.
401	Não autorizado	O token de segurança está ausente ou malformado ou inválido.
403	Proibido	O token de segurança não é válido para este caminho e para esta ação.
500	Erro interno	Algo correu mal no serviço.

Se a conexão WebSocket for intencionalmente desligada pelo serviço depois de ter sido inicialmente configurada, o motivo para fazer isso é comunicado usando um código de erro de protocolo WebSocket apropriado, juntamente com uma mensagem de erro descritiva que também inclui uma ID de rastreamento.

WS Status	Descrição
1000	O ouvinte desliga o soquete.
1001	O caminho de conexão híbrida foi excluído ou desativado.
1008	O token de segurança expirou, portanto, a política de autorização foi violada.
1011	Algo correu mal no serviço.

Protocolo de solicitação HTTP

O protocolo de solicitação HTTP permite solicitações HTTP arbitrárias, exceto atualizações de protocolo. As solicitações HTTP são apontadas para o endereço de tempo de execução regular da entidade, sem a incorreção de $hc usada para clientes WebSocket de conexões híbridas.

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

O namespace-address é o nome de domínio totalmente qualificado do namespace Azure Relay que hospeda a Conexão Híbrida, normalmente do formato {myname}.servicebus.windows.net.

A solicitação pode conter cabeçalhos HTTP adicionais arbitrários, incluindo cabeçalhos definidos pelo aplicativo. Todos os cabeçalhos fornecidos, exceto os diretamente definidos em RFC7230 (consulte Mensagem de solicitação) fluem para o ouvinte e podem ser encontrados no requestHeader objeto da mensagem de solicitação.

As opções de parâmetro da cadeia de caracteres de consulta são as seguintes:

Param	Necessário?	Descrição
sb-hc-token	Sim*	O ouvinte deve fornecer um Token de Acesso Compartilhado do Service Bus válido e codificado por URL para o namespace ou Conexão Híbrida que confere o direito Enviar .

O token também pode ser transportado ServiceBusAuthorization no cabeçalho HTTP ou Authorization HTTP. O token pode ser omitido se a Conexão Híbrida estiver configurada para permitir solicitações anônimas.

Como o serviço atua efetivamente como um proxy, mesmo que não seja um proxy HTTP verdadeiro, ele adiciona um Via cabeçalho ou anota o cabeçalho existente Via compatível com RFC7230, Seção 5.7.1. O serviço adiciona o nome de host do namespace de retransmissão ao Via.

Código	Mensagem	Descrição
200	OK	A solicitação foi tratada por pelo menos um ouvinte.
202	Aceite	O pedido foi aceito por pelo menos um ouvinte.

Se houver um erro, o serviço pode responder da seguinte forma. Se a resposta se origina do serviço ou do ouvinte pode ser identificado através da presença do Via cabeçalho. Se o cabeçalho estiver presente, a resposta é do ouvinte.

Código	Erro	Descrição
404	Não Encontrado	O caminho de conexão híbrida é inválido ou a URL base está malformada.
401	Não autorizado	O token de segurança está ausente ou malformado ou inválido.
403	Proibido	O token de segurança não é válido para este caminho e para esta ação.
500	Erro interno	Algo correu mal no serviço.
503	Gateway Inválido	A solicitação não pôde ser encaminhada para nenhum ouvinte.
504	Tempo limite do gateway	A solicitação foi encaminhada para um ouvinte, mas o ouvinte não acusou o recebimento no tempo necessário.

Próximos passos

• FAQ de Reencaminhamento
• Criar um espaço de nomes
• Introdução ao .NET
• Introdução ao Node