Partilhar via

Importar uma API WebSocket

APLICA-SE A: Developer | Basic | Basic v2 | Standard | Standard v2 | Premium | Premium v2

Com a solução de API WebSocket do Gerenciamento de API, os editores de API podem adicionar rapidamente uma API WebSocket no Gerenciamento de API por meio do portal do Azure, CLI do Azure, Azure PowerShell e outras ferramentas do Azure.

As APIs do WebSocket podem ser protegidas aplicando as políticas de controle de acesso do Gerenciamento de API à operação inicial de handshake. Você também pode testar APIs WebSocket usando os consoles de teste de API no portal do Azure e no portal do desenvolvedor. Com base nos recursos de observabilidade existentes, o Gerenciamento de API fornece métricas e logs para monitoramento e solução de problemas de APIs WebSocket.

Neste artigo, você irá:

  • Entenda o fluxo de passagem do WebSocket.
  • Adicione uma API WebSocket à sua instância de Gerenciamento de API.
  • Teste sua API WebSocket.
  • Exiba as métricas e os logs da API WebSocket.
  • Conheça as limitações da API WebSocket.

Pré-requisitos

Passagem de WebSocket

O Gerenciamento de API suporta passagem WebSocket.

Ilustração visual do fluxo de passagem do WebSocket

Durante a passagem WebSocket, o aplicativo cliente estabelece uma conexão WebSocket com o gateway de Gerenciamento de API, que então estabelece uma conexão com os serviços de back-end correspondentes. Em seguida, o Gerenciamento de API atua como proxy para mensagens cliente-servidor WebSocket.

  1. O aplicativo cliente envia uma solicitação de handshake WebSocket para o gateway, invocando a operação onHandshake
  2. O gateway de Gerenciamento de API aplica políticas configuradas e envia solicitações de handshake WebSocket para o serviço de back-end correspondente.
  3. O serviço de back-end atualiza uma conexão para WebSocket.
  4. O gateway atualiza a conexão correspondente ao WebSocket.
  5. Depois que o par de conexões é estabelecido, o Gerenciamento de API intermede mensagens entre o aplicativo cliente e o serviço de back-end.
  6. O aplicativo cliente envia uma mensagem para o gateway.
  7. O gateway encaminha a mensagem para o serviço de back-end.
  8. O serviço de back-end envia uma mensagem para o gateway.
  9. O gateway encaminha a mensagem para o aplicativo cliente.
  10. Quando ambos os lados se desconectam, o Gerenciamento de API encerra a conexão correspondente.

Observação

As conexões do lado do cliente e do lado do back-end consistem em mapeamento um-para-um.

operação de aperto de mão

De acordo com o protocolo WebSocket, quando um aplicativo cliente tenta estabelecer uma conexão WebSocket com um serviço de back-end, ele primeiro envia uma solicitação de handshake de abertura. Cada API WebSocket no Gerenciamento de API tem uma operação onHandshake. onHandshake é uma operação do sistema imutável, irremovível e criada automaticamente. A operação onHandshake permite que os editores de API intercetem essas solicitações de handshake e apliquem políticas de gerenciamento de API a elas.

Exemplo de ecrã onHandshake

Adicionar uma API WebSocket

    1. No portal do Azure, navegue até sua instância de Gerenciamento de API.

  2. No menu à esquerda, selecione APIs>+ Add API.

  3. Em Definir uma nova API, selecione WebSocket.

  4. Na caixa de diálogo, selecione Completo e preencha os campos de formulário obrigatórios.

    Campo Descrição
    Nome de exibição O nome pelo qual sua API WebSocket é exibida.
    Nome Nome bruto da API WebSocket. Preenche automaticamente à medida que você digita o nome para exibição.
    O URL do WebSocket O URL base com o nome do websocket. Por exemplo: ws://example.com/your-socket-name
    Esquema de URL Aceitar o padrão
    Sufixo do URL de API Adicione um sufixo de URL para identificar essa API específica nesta instância de Gerenciamento de API. Ele deve ser exclusivo nesta instância de Gerenciamento de API.
    Produtos Associe sua API WebSocket a um produto para publicá-la.
    Portais Associe sua API WebSocket a gateways existentes.

  5. Clique em Criar.

Teste sua API WebSocket

  1. Navegue até a sua API WebSocket.

  2. Na API WebSocket, selecione a operação onHandshake.

  3. Selecione a guia Teste para acessar o console de teste.

  4. Opcionalmente, forneça os parâmetros de cadeia de caracteres de consulta necessários para o handshake WebSocket.

    exemplo de API de teste

  5. Clique em Conectar.

  6. Veja o status da conexão em Saída.

  7. Insira o valor em Payload.

  8. Clique em Enviar.

  9. Visualize as mensagens recebidas na Saída.

  10. Repita as etapas anteriores para testar cargas úteis diferentes.

  11. Quando o teste estiver concluído, selecione Desconectar.

Visualizar métricas e logs

Use os recursos padrão de Gerenciamento de API e Azure Monitor para monitorar APIs WebSocket:

  • Exibir métricas de API no Azure Monitor
  • De forma opcional, ative as definições de diagnóstico para recolher e visualizar os registos do gateway de gestão da API, que incluem operações da API WebSocket ou registos de ligação WebSocket.

Por exemplo, a captura de tela a seguir mostra respostas recentes da API WebSocket com código 101 da tabela ApiManagementGatewayLogs . Esses resultados indicam a mudança bem-sucedida das solicitações de TCP para o protocolo WebSocket.

Registos de consulta para pedidos de API WebSocket

Limitações

A seguir estão as restrições atuais do suporte a WebSocket no Gerenciamento de API:

  • As APIs WebSocket ainda não são suportadas na camada Consumo.
  • As APIs WebSocket suportam os seguintes tipos de buffer válidos para mensagens: Close, BinaryFragment, BinaryMessage, UTF8Fragment e UTF8Message.
  • Atualmente, a política set-header não suporta a alteração de determinados cabeçalhos conhecidos, incluindo Host cabeçalhos, em solicitações onHandshake.
  • Durante o handshake TLS com um back-end WebSocket, o Gerenciamento de API valida que o certificado do servidor é confiável e que seu nome de assunto corresponde ao nome do host. Com APIs HTTP, o Gerenciamento de API valida que o certificado é confiável, mas não valida essa correspondência de nome de host e assunto.

Para limites de conexão WebSocket, consulte Limites de gerenciamento de API.

Políticas sem suporte

As seguintes políticas não são suportadas e não podem ser aplicadas à operação onHandshake:

  • Resposta simulada
  • Obter a partir da cache
  • Armazenar em cache
  • Permitir chamadas entre domínios
  • CORS
  • JSONP
  • Definir método de solicitação
  • Configurar corpo
  • Converter XML em JSON
  • Converter JSON em XML
  • Transformar XML usando XSLT
  • Validar conteúdo
  • Validar parâmetros
  • Validar cabeçalhos
  • Validar código de estado

Observação

Se tiver aplicado as políticas em âmbitos mais altos (por exemplo, global ou produto) e elas são herdadas por uma API WebSocket através da política, são ignoradas durante a execução.

Conteúdo relacionado

  • Last updated on