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.
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.
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.
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.
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.
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.
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.
auth_key en la URL no se lee por WebSocket.data tiene que ser un objeto JSON, aunque esté vacío: {"data": {}}.