Compartir a través de

Importación de WebSocket API

APLICABLE A: Desarrollador | Básico | Básico v2 | Estándar | Estándar v2 | Premium | Premium v2

Con la solución de API WebSocket de API Management, los publicadores de API pueden agregar rápidamente una API de WebSocket en API Management a través del portal de Azure, CLI de Azure, Azure PowerShell y otras herramientas de Azure.

Las APIs de WebSocket se pueden proteger aplicando las directivas de control de acceso de API Management a la operación de protocolo de enlace inicial. También puede probar las API de WebSocket mediante las consolas de prueba de API tanto en Azure portal como en el portal para desarrolladores. A través de las funcionalidades de observabilidad existentes, API Management proporciona métricas y registros para supervisar y solucionar problemas de las API de WebSocket.

En este artículo, usted podrá:

  • Comprenderá el flujo de tráfico de Websocket.
  • Agrega una API de WebSocket a tu instancia de administración de API.
  • Prueba tu API de WebSocket.
  • Visualizará las métricas y los registros de la API de WebSocket.
  • Conocerá las limitaciones de la API de WebSocket.

Requisitos previos

  • Una instancia existente de API Management. Cree uno si aún no lo ha hecho.
  • Una API de WebSocket.
  • CLI de Azure

Tráfico de WebSocket

API Management admite el paso directo de WebSocket.

Ilustración visual del flujo de tráfico de WebSocket

Durante el tráfico de WebSocket, la aplicación cliente establece una conexión de WebSocket con la puerta de enlace de API Management, que a su vez establece una conexión con los servicios back-end correspondientes. A continuación, API Management envía mediante proxy los mensajes entre cliente y servidor de WebSocket.

  1. La aplicación cliente envía una solicitud de enlace de WebSocket a la puerta de enlace, invocando la operación onHandshake.
  2. La puerta de enlace de API Management aplica directivas configuradas y envía solicitudes de protocolo de enlace de WebSocket al servicio back-end correspondiente.
  3. El servicio back-end actualiza una conexión a WebSocket.
  4. La puerta de enlace actualiza la conexión correspondiente a WebSocket.
  5. Una vez establecido el par de conexiones, API Management se encarga de intercambiar mensajes entre la aplicación cliente y el servicio backend.
  6. La aplicación cliente envía un mensaje a la puerta de enlace.
  7. La puerta de enlace reenvía el mensaje al servicio back-end.
  8. El servicio back-end envía un mensaje a la puerta de enlace.
  9. La puerta de enlace reenvía el mensaje a la aplicación cliente.
  10. Cuando cualquier lado se desconecta, API Management finaliza la conexión correspondiente.

Nota:

Las conexiones de cliente a backend constan de asignaciones uno-a-uno. La misma sesión de WebSocket no se puede distribuir entre varios back-end.

Operación onHandshake

Según el protocolo WebSocket, cuando una aplicación cliente intenta establecer una conexión WebSocket con un servicio backend, primero enviará una solicitud de inicio de comunicación. Cada API de WebSocket en API Management tiene una operación onHandshake. La operación onHandshake es una operación del sistema inmutable, que no se puede eliminar y que se crea automáticamente. La operación onHandshake permite a los publicadores de API interceptar estas solicitudes de handshake y aplicarles las directivas de API Management.

Ejemplo de pantalla de onHandshake

Adición de una API de WebSocket

  • Portal
    1. En el portal Azure, vaya a la instancia de API Management.

  2. En el menú izquierdo, seleccione API+Agregar API.

  3. En Definir una nueva API, seleccione WebSocket.

  4. En el cuadro de diálogo, seleccione Completo y rellene los campos necesarios del formulario.

    Campo Descripción
    Nombre para mostrar Nombre por el que se muestra la API de WebSocket.
    Nombre Nombre crudo de la API de WebSockets. Se rellena automáticamente a medida que escribe el nombre de visualización.
    URL de WebSocket Dirección URL base con el nombre de tu WebSocket. Por ejemplo: ws://example.com/your-socket-name
    Esquema URL Acepte el valor predeterminado.
    Sufijo de dirección URL de API Agregue un sufijo de URL para identificar esta API específica en esta instancia de API Management. Tiene que ser único en esta instancia de API Management.
    Productos Asocie la API de WebSocket a un producto para publicarla.
    Puertas de enlace Asocie la API de WebSocket a las puertas de enlace existentes.

  5. Haga clic en Crear.

Prueba de la API de WebSocket

  1. Navegue hasta la API de WebSocket.

  2. En la API de WebSocket, seleccione la operación onHandshake.

  3. Seleccione la pestaña Prueba para acceder a la consola Prueba.

  4. De ser necesario, proporcione los parámetros de cadena de consulta requeridos para el protocolo de enlace WebSocket.

    Ejemplo de API de prueba

  5. Haga clic en Conectar.

  6. Vea el estado de la conexión en Salida.

  7. Escriba el valor en Carga.

  8. Haga clic en Enviar.

  9. Vea los mensajes recibidos en Salida.

  10. Repita los pasos anteriores para probar diferentes cargas.

  11. Cuando se complete la prueba, seleccione Desconectar.

Visualización de métricas y registros

Use las características estándar de API Management y Azure Monitor para monitor APIs de WebSocket:

  • Visualización de métricas de API en Azure Monitor
  • Opcionalmente, habilite la configuración de diagnóstico para recopilar y ver registros de puerta de enlace de API Management, que incluyen operaciones de API de WebSocket o registros de conexión de WebSocket.

Por ejemplo, en la siguiente captura de pantalla se muestran las respuestas recientes de la API de WebSocket con código de la tabla ApiManagementGatewayLogs. Estos resultados indican el cambio correcto de las solicitudes de TCP al protocolo WebSocket.

Consulta de registros para solicitudes de API de WebSocket

Limitaciones

A continuación se muestran las restricciones actuales de compatibilidad con WebSocket en API Management:

  • Las API de WebSocket no se admiten aún en el nivel de consumo.
  • Las API WebSocket admiten los siguientes tipos de búferes válidos para mensajes: Close, BinaryFragment, BinaryMessage, UTF8Fragment y UTF8Message.
  • Actualmente, la política set-header no admite el cambio de ciertos encabezados bien conocidos, incluidos los encabezados , en las solicitudes onHandshake.
  • Durante el handshake TLS con un backend WebSocket, la API Management valida que el certificado del servidor sea de confianza y que su nombre de sujeto coincida con el nombre del host. Con las API de HTTP, API Management valida que el certificado es de confianza, pero no valida que el nombre de host y el asunto coincidan.
  • Las conexiones de WebSocket no se pueden distribuir ni equilibrar la carga entre varios back-end porque, una vez establecida, cada conexión se mantiene de uno a uno entre el cliente y el back-end.

Para conocer los límites de conexión de WebSocket, consulte límites de API Management.

Directivas no admitidas

Las siguientes directivas no son compatibles con la operación onHandshake y no se pueden aplicar a ella:

  • Respuesta simulada
  • Obtener de caché
  • Almacenar en caché
  • Permitir llamadas entre dominios
  • CORS
  • JSONP
  • Establecimiento de método de solicitud
  • Definir cuerpo
  • Convertir XML a JSON
  • Convertir JSON a XML
  • Transformar XML mediante XSLT
  • Validar contenido
  • Validación de parámetros
  • Validación de encabezados
  • Validación de código de estado

Nota:

Si aplicaste las directivas en ámbitos superiores (por ejemplo, a nivel global o de producto) y una API WebSocket las heredó mediante la directiva, se omitirán en tiempo de ejecución.

Contenido relacionado

  • Limitaciones de importación de API
  • Importación de una especificación de OpenAPI
  • Importación de una API de SOAP
  • Importar una API de SOAP y convertir en REST
  • Importar una API de servicio de aplicaciones
  • Importación de una API de aplicación de contenedor
  • Importación de WebSocket API
  • Importación de GraphQL API
  • Importación de un esquema GraphQL y configuración de solucionadores de campos
  • Importación de una API de aplicación de funciones
  • Importación de una API de aplicación lógica
  • Importación de un servicio Service Fabric
  • Importación de una API de Microsoft Foundry
  • Importar una API de OpenAI Azure
  • Importación de una API de LLM
  • Importación de una API de OData
  • Exportación de una API REST como servidor MCP
  • Exposición de un servidor MCP existente
  • Importación de una API de agente de A2A
  • Importación de metadatos de SAP OData
  • Importación de una API de gRPC
  • Edición de una API
  • Last updated on