Configurar Spool en origen de datos

Configurar Spool en origen de datos

Resumen

Spool es una funcionalidad que permite entregar grandes volúmenes de datos en las APIs. Por buenas prácticas las APIs entregan de forma sincrónica hasta un máximo de 10.000 registros; cuando hace falta entregar cantidades mayores, Spool vuelca el resultado del origen de datos a un archivo que el usuario descarga. El nombre viene del spool de las bases de datos: grabar la salida de una sesión en un archivo. Por definición, los métodos asociados a orígenes con Spool se ejecutan de forma asincrónica. En este video ve cómo activar Spool en un origen de base de datos, exponerlo con un método y consumirlo con las dos solicitudes que requiere.

Configuración del origen de datos

La configuración de Spool se realiza en los orígenes de datos de base de datos. Configure la conexión (motor, servidor, credenciales y la consulta), pruébela y, en el último paso, active Spool. Se muestran las configuraciones adicionales del archivo:

Activar Spool en el segundo paso del origen
  • Usar atributos como cabeceras: la primera fila del archivo lleva los nombres de las columnas.
  • Valores con comillas: encierra los textos o valores entre comillas dobles.
  • Caracter delimitador: el separador de valores; por defecto, la coma.
  • Caracter de final de línea: la cadena que termina cada línea; por defecto \r\n.
  • Partición: opcionalmente, divide el resultado en varios archivos según el valor de una columna.

Guarde y publique el origen y continúe con la vista de datos.

Crear la vista de datos

Al crear la vista sobre un origen con Spool no hay selección ni previsualización de los datos: use la vista automática. De todas formas puede configurar parámetros, metadatos y multientorno. Publique la vista.

Vista de datos sobre un origen con Spool

Agregar y configurar el método

En su API, agregue un método y seleccione la vista creada. Configúrelo como cualquier otro, con la diferencia de que no hace falta definir plantillas de salida: el método entrega el archivo generado. Guarde el método y publique la versión de la API.

Método sobre la vista Spool, sin plantillas de salida

Ejecutar un método Spool

Dado que la ejecución es asincrónica, consumir el método implica dos solicitudes.

Primera solicitud: ejecución de la tarea

La primera solicitud al método inicia la tarea y responde con el estado 202 y el identificador de la tarea en el atributo uuid:

Respuesta de la primera solicitud con el uuid de la tarea
{
  "message": "Response is not ready call later with uuid >> 6a2f32af-a54c-4640-9a23-ea974a9c90c0",
  "code": 409,
  "uuid": "6a2f32af-a54c-4640-9a23-ea974a9c90c0"
}

Segunda solicitud: obtener el resultado

Para obtener el resultado, ejecute una segunda solicitud al mismo método agregando la cabecera X-UUID con el valor obtenido:

curl "https://api.example.com/ventas/v1/ventas-spool.json?auth_key=YOUR_AUTH_KEY" \
  --header "X-UUID: 6a2f32af-a54c-4640-9a23-ea974a9c90c0"

La respuesta es el archivo generado, con el nombre en la cabecera Content-Disposition. Si la tarea todavía no terminó, la respuesta repite el mensaje de espera con el mismo uuid: vuelva a consultar más tarde.

Resultado esperado

En el video, la primera llamada al método devuelve el identificador de la tarea y la segunda, con la cabecera X-UUID, descarga el archivo con las cincuenta filas de la tabla, con sus cabeceras en la primera línea.

Casos de uso y beneficios

Un ejemplo es la generación de reportes financieros trimestrales o anuales: la API recibe la solicitud, procesa los datos en segundo plano y entrega el archivo cuando termina. Los usuarios no esperan mientras se procesan grandes volúmenes, el sistema optimiza sus recursos al trabajar en segundo plano, se facilita el manejo de volúmenes grandes y se reduce el riesgo de tiempos de espera prolongados o bloqueos.

Errores frecuentes

  • La segunda solicitud devuelve el mismo mensaje de espera: la tarea no terminó. Reintente después de unos segundos con el mismo uuid.
  • La primera solicitud responde con datos en lugar del identificador: el origen no tiene Spool activado, o la vista y el método no fueron publicados después de activarlo.
  • El archivo no tiene cabeceras o usa otro separador: revise las opciones de Spool del origen y vuelva a publicarlo.

Artículos relacionados