Importar uma API WebSocket

APLICA-SE A: Developer | Básico | Básico v2 | Padrão | Padrão v2 | Prémio

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.

Você pode proteger APIs WebSocket aplicando políticas de controle de acesso existentes, como validação JWT. 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, vai:

• 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.

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

1. O aplicativo cliente envia uma solicitação de handshake WebSocket para o gateway 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 para WebSocket.
4. O gateway APIM atualiza a conexão correspondente ao WebSocket.
5. Depois que o par de conexões for estabelecido, o APIM intermediará mensagens entre o aplicativo cliente e o serviço de back-end.
6. O aplicativo cliente envia 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.

Nota

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

operação 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 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.

Adicionar uma API WebSocket

Portal

1. 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
   Display name	O nome pelo qual sua API WebSocket será exibida.
   Nome	Nome bruto da API WebSocket. Preenche automaticamente à medida que você digita o nome para exibição.
   WebSocket URL	O URL base com o nome do websocket. Por exemplo: ws://example.com/your-socket-name
   Esquema do URL	Aceite a predefinição
   Sufixo do URL de API	Adicione um sufixo de URL para identificar essa API específica nesta instância de Gerenciamento de API. Tem de ser exclusivo nesta instância de APIM.
   Produtos	Associe sua API WebSocket a um produto para publicá-la.
   Gateways	Associe sua API WebSocket a gateways existentes.

5. Clique em Criar.

Teste sua API WebSocket

1. Navegue até 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.

   

5. Clique em Ligar.

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
• Opcionalmente, habilite as configurações de diagnóstico para coletar e exibir logs de gateway de Gerenciamento de API, que incluem operações de 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.

Limitações

Abaixo 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
• Definir 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

Nota

Se você aplicou as políticas em escopos mais altos (ou seja, global ou produto) e elas foram herdadas por uma API WebSocket por meio da política, elas serão ignoradas em tempo de execução.

Tópicos relacionados

• Limitações de importação de API
• Importar uma especificação de OpenAPI
• Importar uma API SOAP
• Importar uma API de SOAP e converter 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 resoluções de campos
• Importar uma Aplicação de Função do Azure
• Importar uma Aplicação Lógica do Azure
• Importar um serviço do Service Fabric
• Importar uma API OData
• Importar metadados do SAP OData
• Importar uma API gRPC
• Editar uma API

Próximos passos

Transformar e proteger a sua API