Partilhar via

Importar uma API WebSocket

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

Com a solução WebSocket API da API Management, os editores de APIs podem rapidamente adicionar uma API WebSocket na API Management através do portal 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. Também pode testar APIs WebSocket usando as consolas de teste de APIs tanto no portal Azure como no portal de programadores. 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

  • Uma instância de gerenciamento de API existente. Crie um, caso ainda não o tenha feito.
  • Uma API WebSocket.
  • CLI do Azure

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 ligações cliente-backend consistem em mapeamentos um-para-um. A mesma sessão WebSocket não pode ser distribuída por múltiplos backends.

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

  • Portais
    1. No portal Azure, navegue até à sua instância de Gestão de APIs.

  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 as funcionalidades padrão de Gestão de API e Azure Monitor para monitorar APIs WebSocket:

  • Ver métricas 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 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 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.
  • As ligações WebSocket não podem ser distribuídas ou balanceadas por carga entre múltiplos backends porque, uma vez estabelecidas, cada ligação é mantida um para um entre o cliente e o backend.

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

  • Limitações de importação de API
  • Importar uma especificação de OpenAPI
  • Importar uma API SOAP
  • Importe uma API SOAP e converta-a em REST
  • Importar uma API do Serviço de Aplicativo
  • Importar uma API de aplicativo de contêiner
  • Importar uma API WebSocket
  • Importar uma GraphQL API
  • Importar um esquema de GraphQL e configurar resolveres de campos
  • Importar uma API de aplicativo de função
  • Importar uma API de aplicativo lógico
  • Importar um serviço do tipo Service Fabric
  • Importar uma API Microsoft Foundry
  • Importar uma API Azure OpenAI
  • Importar uma API LLM
  • Importar uma API OData
  • Exportar uma API REST como um servidor MCP
  • Expor um servidor MCP existente
  • Importar uma API de agente A2A
  • Importar metadados do SAP OData
  • Importar uma API gRPC
  • Editar uma API
  • Last updated on