Configurar WebSocket

Configurar WebSocket

Resumen

Una API WebSocket mantiene una conexión abierta entre el cliente y Vortex: el cliente se conecta una vez, manda los parámetros y recibe el resultado de la vista; después, en cada intervalo de consulta, recibe solo las filas nuevas. Sirve para tableros, cotizaciones o cualquier consumidor que necesite datos a medida que aparecen, sin volver a pedir todo. En esta guía crea la API, configura el dominio y el polling, y se conecta desde la línea de comandos.

Antes de comenzar

  • El tipo de API WebSocket aparece en Nueva API cuando está habilitado para la cuenta. Si no lo ves, consulte a soporte.
  • Necesita un subdominio para WebSocket con su registro CNAME apuntando a Vortex, igual que el del portal.
  • Una vista publicada sobre la que exponer el método, y una aplicación del portal con su llave de acceso.

Configurar el dominio WebSocket

En Workspace › Configuraciones › Dominios, complete el campo Websocket con el subdominio, por ejemplo ws.midominio.com, y haga clic en Guardar. Ese host es el que van a usar los clientes para conectarse; el portal lo muestra en el ejemplo de código del método como wss://ws.midominio.com.

Pestaña Dominios de Configuraciones con el campo Websocket

Crear la API y el método

El protocolo se elige al crear la API: desde APIs › Nueva API, elija WebSocket. El asistente es el mismo que el de una API REST: descripción, SLO si la cuenta lo tiene habilitado, límites y revisión.

Modal Nueva API con las opciones REST, WebSocket y SOAP

Después agregue el método sobre la vista, como en cualquier API. El editor oculta lo que no aplica al protocolo: el tipo de solicitud queda fijo, y no hay tipo de contenido, cabeceras de la respuesta, paginación ni ejecución asincrónica. Deje la Ruta en un solo segmento, por ejemplo ventas, porque la URL de conexión termina en la ruta y el formato. Guarde el método con Listo y publique la versión.

Editor del método de una API WebSocket, con el tipo de solicitud deshabilitado

Configurar el polling en el origen de datos

La frecuencia con la que Vortex vuelve a consultar el origen para mandar filas nuevas se define en el origen de datos, en el último paso del asistente, bloque Configuración de Polling, con la casilla Activar/Desactivar Polling. En los orígenes de base de datos y de colas puede además ajustar el Tiempo entre solicitudes en segundos, el Tiempo hasta timeout, que corta la conexión si no hay novedades en ese lapso, y la Columna de referencia, la que usa para reconocer qué filas son nuevas. En los demás orígenes se usan los valores por defecto: una consulta cada 15 segundos y una semana de timeout.

Bloque Configuración de Polling del último paso del origen de datos

Conectarse desde un cliente

La URL de conexión es wss://<dominio websocket>/<api>/v<versión>/<ruta>.<formato>/, con la barra final. La llave de acceso de la aplicación viaja en una cabecera, auth-key o Authorization, nunca en la URL. Con websocat:

websocat -H='auth-key: TU_LLAVE' wss://ws.midominio.com/demo-ventas/v1/ventas.json/

Con wscat:

wscat -c wss://ws.midominio.com/demo-ventas/v1/ventas.json/ -H "auth-key: TU_LLAVE"

Una vez conectado, el cliente manda un mensaje JSON con los parámetros del método en data. Con full en true la primera respuesta trae el resultado completo; si no, solo las filas nuevas desde la conexión:

{"data": {"region": "Norte"}, "full": true}

La respuesta es la salida del método con la plantilla del formato, igual que por REST. Después, en cada intervalo de polling, llegan las filas nuevas o {"polling": "No new data"} si no hay. El mismo canal acepta tres consultas de apoyo: {"resource": "params"} devuelve los parámetros del método, {"resource": "data_dict"} el diccionario de datos y {"resource": "swagger"} su definición.

Resultado esperado

El cliente se conecta con la llave en la cabecera, recibe el resultado de la vista con la plantilla del formato y, mientras la conexión siga abierta, las filas nuevas en cada intervalo de polling. El portal para desarrolladores muestra la URL wss:// y un ejemplo de cliente en la ficha del método.

Errores frecuentes

  • La conexión se rechaza con 404: falta la barra final de la URL, la ruta tiene más de un segmento, o el host no es el subdominio configurado en Dominios.
  • Conecta y se cierra enseguida con un mensaje Error: la llave no es válida o no viaja en la cabecera. El parámetro auth_key en la URL no se lee por WebSocket.
  • Error: Request data must be sent in an object: data tiene que ser un objeto JSON, aunque esté vacío: {"data": {}}.
  • Solo llega "No new data": la columna de referencia del polling no cambia entre consultas, o el origen devolvió un error. Revise la vista por REST para descartar el origen.
  • La salida llega como Error: el formato del método no es JSON. Por WebSocket use un formato JSON.

Artículos relacionados