Importar uma API WebSocket

  • Artigo

APLICA-SE A: Desenvolvedor | Básico | Básico v2 | Standard | Standard v2 | Premium

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

Observação

Atualmente, esse recurso não está disponível em workspaces.

Você pode proteger as APIs do WebSocket aplicando políticas de controle de acesso existentes, como validação JWT. Você também pode testar as APIs WebSocket usando os consoles de teste de API no portal do Azure e no portal do desenvolvedor. Com base em recursos de observabilidade existentes, o Gerenciamento de API fornece métricas e logs para monitorar e solucionar problemas de APIs do WebSocket.

Neste artigo, você irá:

  • Entenda o fluxo de passagem do Websocket.
  • Adicione uma API do WebSocket à sua instância do aplicativo de Gerenciamento de API.
  • Testar a API do WebSocket.
  • Exibir as métricas e logs para a API do WebSocket.
  • Conheça as limitações da API do WebSocket.

Pré-requisitos

Passagem do WebSocket

Gerenciamento de API dá suporte à passagem do WebSocket.

Ilustração visual do fluxo de passagem do WebSocket

Durante a passagem do WebSocket, o aplicativo cliente estabelece uma conexão WebSocket com o Gateway de Gerenciamento de API, que estabelece uma conexão com os serviços de back-end correspondentes. Em seguida, o Gerenciamento de API cria proxies para mensagens cliente-servidor do WebSocket.

  1. O aplicativo cliente envia uma solicitação de handshake do WebSocket para o gateway de APIM, invocando a operação onHandshake.
  2. O gateway APIM envia a solicitação de handshake WebSocket para o serviço de back-end correspondente.
  3. O serviço de back-end atualiza uma conexão com o WebSocket.
  4. O gateway APIM atualiza a conexão correspondente ao WebSocket.
  5. Depois que o par de conexão for estabelecido, o APIM transmitirá as mensagens de volta e para trás entre o aplicativo cliente e o serviço de back-end.
  6. O aplicativo cliente envia a mensagem para o gateway APIM.
  7. O gateway APIM encaminha a mensagem para o serviço de back-end.
  8. O serviço de back-end envia uma mensagem para o gateway APIM.
  9. O gateway APIM encaminha a mensagem para o aplicativo cliente.
  10. Quando um dos lados se desconecta, o APIM encerra a conexão correspondente.

Observação

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

Operação de onHandshake

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 enviará uma solicitação de handshake de abertura. Cada API do WebSocket no Gerenciamento de API tem uma operação onHandshake. onHandshake é uma operação de sistema imutável, não removível, criada automaticamente. A operação onHandshake permite que os editores de API interceptem essas solicitações de handshake e apliquem políticas de Gerenciamento de API a elas.

Exemplo de tela de onHandshake

Adicionar uma API do WebSocket

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

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

  3. Em Definir uma nova API, selecione WebSocket.

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

    Campo Description
    Nome de exibição O nome pelo qual a API do WebSocket será exibida.
    Nome Nome bruto da API do WebSocket. Preenche automaticamente conforme você digita o nome de exibição.
    WebSocket URL A URL base com o nome do websocket. Por exemplo: ws://example.com/your-socket-name
    Esquema de URL Aceite o padrão
    Sufixo da URL da 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 APIM.
    Produtos Associe sua API do WebSocket a um produto para publicá-lo.
    Gateways Associe sua API do WebSocket a gateways existentes.

  5. Clique em Criar.

Testar a API do WebSocket

  1. Navegue até a API do 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 parâmetros de cadeia de caracteres de consulta necessários para o handshake do WebSocket.

    exemplo de API de teste

  5. Clique em Conectar.

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

  7. Insira o valor em Conteúdo.

  8. Clique em Enviar.

  9. Exibir mensagens recebidas em Saída.

  10. Repita as etapas anteriores para testar cargas diferentes.

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

Exibir métricas e logs

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

  • Ver métricas do API no Azure Monitor
  • Opcionalmente, habilite as configurações de diagnóstico para coletar e exibir os logs do gateway de Gerenciamento de API, que incluem operações da API 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.

Logs de consulta para solicitações da API WebSocket

Limitações

Abaixo estão as restrições atuais do suporte ao WebSocket no Gerenciamento de API:

  • Ainda não há suporte para as APIs do WebSocket na camada de consumo.
  • As APIs do WebSocket dão suporte aos seguintes tipos de buffer válidos para mensagens: Close, BinaryFragment, BinaryMessage, UTF8Fragment e UTF8Message.
  • Atualmente, a política de cabeçalho definida não dá suporte à alteração de determinados cabeçalhos conhecidos, incluindo cabeçalhos Host em solicitações onHandshake.
  • Durante o handshake do TLS com um back-end do WebSocket, o Gerenciamento de API valida que o certificado do servidor é confiável e que seu nome de entidade corresponde ao nome do host. Com as APIs HTTP, o Gerenciamento de API valida que o certificado é confiável, mas não valida que o nome do host e a entidade correspondem.

Para limites de conexão do WebSocket, confira limites de Gerenciamento de API.

Políticas sem suporte

As políticas a seguir não têm suporte no e não podem ser aplicadas à operação onHandshake:

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

Observação

Se você tiver aplicado as políticas em escopos mais altos (ou seja, global ou produto) e elas tiverem sido herdadas por uma API do WebSocket por meio da política, elas serão ignoradas no runtime.

Próximas etapas

Transformar e proteger uma API publicada