Procesar lotes de archivos con concurrencia controlada

Por qué no conviene enviar todo a la vez

Al automatizar muchos archivos, enviar todas las solicitudes a la vez puede dificultar el seguimiento de lo completado, lo que sigue en curso y lo que falló. Una ráfaga tampoco permite saber con certeza qué ocurrió si el proceso se interrumpe. Diseñar una cola con un límite de tareas activas y un estado por archivo puede ayudar a organizar el trabajo, pero son decisiones de tu integración, no un comportamiento garantizado por cualquier API.

Las APIs ofrecen modelos distintos. La [API Batch de OpenAI](https://help.openai.com/es-es/articles/9197833-batch-api-faq) permite enviar solicitudes para su procesamiento asíncrono. Microsoft documenta solicitudes por lotes para consultas y operaciones en la [API REST/OData de SharePoint Online](https://learn.microsoft.com/es-es/sharepoint/dev/sp-add-ins/make-batch-requests-with-the-rest-apis). Estos ejemplos tienen alcances distintos y no establecen una regla común de concurrencia para otros servicios.

• Consulta primero la documentación del endpoint que utilizarás.
• Mantén identificada cada tarea por archivo.
• Separa las funciones documentadas por la API de las decisiones de tu cola.

Antes de empezar: leer el contrato de la API

Revisa qué entradas acepta el endpoint, qué respuestas devuelve y si el resultado llega directamente o se procesa de forma asíncrona. Busca también si la documentación especifica límites, identificadores para consultar el progreso o condiciones para repetir una operación. Si no define una conducta, no la supongas: consulta al proveedor o diseña una prueba controlada.

Anota estas condiciones en una ficha de integración y distingue la aceptación de una solicitud de la finalización del trabajo. Apification permite integrar Cloud y sus servicios mediante REST API, OpenAPI y webhooks; eso no significa que todos los servicios compartan límites, estados o políticas de reintento. Consulta la referencia del servicio concreto.

• Registrar endpoint, método, formato de entrada y respuesta esperada.
• Anotar únicamente límites y reglas de reintento que estén especificados.
• Identificar qué respuesta confirma aceptación y cuál confirma finalización.

Diseñar una cola con estado por archivo

Como decisión de diseño de tu aplicación, puedes representar cada archivo como una tarea independiente. Guarda un identificador interno, la referencia al archivo y sus parámetros; registra también el estado local, los intentos y el resultado o error relevante. Si la API devuelve un identificador remoto, conservarlo puede facilitar el seguimiento cuando el servicio documente una consulta de estado.

Usa estados locales con significados claros, por ejemplo: pendiente, en curso, completado y requiere revisión. No los presentes como estados del proveedor salvo que su documentación así los defina. Persistirlos permite que tu aplicación identifique tareas incompletas tras una interrupción, pero no determina por sí solo si una operación remota llegó a ejecutarse. Protege los secretos y credenciales al guardar registros.

• Registra el resultado de cada tarea, no solo un total del lote.
• Distingue los estados locales de los estados devueltos por la API.
• Conserva el contexto necesario para investigar sin registrar secretos.

Elegir y ajustar la concurrencia

No hay una cifra inicial universal que pueda recomendarse sin conocer la API y sus condiciones. Como pauta de diseño, haz configurable el número de tareas simultáneas y prueba primero con una carga pequeña. Observa las respuestas y cualquier restricción comunicada por el proveedor; aumenta o reduce el límite solo de acuerdo con las reglas documentadas y los resultados de tus pruebas.

El tamaño total del lote y las tareas simultáneas son conceptos distintos: un lote grande puede procesarse en grupos más pequeños. Si tu arquitectura utiliza varios consumidores, decide cómo se coordinará el límite agregado; no des por hecho que cada consumidor dispone por separado de toda la capacidad que la API permita.

• Empieza con pocos elementos y un límite configurable.
• Ajusta el límite según la documentación y las respuestas observadas.
• Considera la actividad conjunta de todos los consumidores.

Clasificar errores y limitar los reintentos

Clasifica los errores según las respuestas y reglas de la API concreta. Algunos pueden requerir corregir el archivo o los parámetros; otros podrían justificar una nueva tentativa si la documentación lo permite. No deduzcas una política universal por el texto del error. Guarda el código y el contexto relevante para el diagnóstico, sin exponer datos sensibles.

Como decisión de diseño, puedes establecer un máximo de intentos y una espera entre ellos para los casos que admitan reintento. Si una operación queda en estado incierto, un timeout no demuestra que el servicio no la haya procesado: evita reenviarla a ciegas. Si la API documenta un mecanismo de idempotencia, sigue sus condiciones; de lo contrario, no asumas que repetir sea seguro.

• Decide para cada error si corresponde repetir, corregir o revisar.
• Registra cada intento y evita ciclos de reintento indefinidos.
• Trata con cautela las solicitudes cuyo resultado sea incierto.

Reanudar un lote interrumpido

Al reiniciar tu aplicación, carga el estado persistido y conserva las tareas completadas. Para las que quedaron en curso, consulta si la API ofrece una forma documentada de verificar su estado mediante un identificador. Si no hay forma de resolver la incertidumbre, define una política explícita para esos casos o envíalos a revisión, en lugar de reenviarlos automáticamente.

Mantén una identidad estable para cada tarea y registra cambios de archivo o parámetros como trabajos distinguibles. Apification permite revisar el historial de elementos de Cloud, descargar versiones anteriores y restaurar contenido. Estas funciones ayudan a revisar cambios en Cloud, pero no sustituyen el seguimiento de solicitudes ni garantizan que una operación de API sea idempotente.

• Omite tareas completadas y revisa las que quedaron en curso.
• No interpretes una respuesta perdida como prueba de que la operación falló.
• Registra cambios de entrada o parámetros para distinguir trabajos.

Flujo operativo y pruebas

Un flujo posible es validar los archivos, crear una tarea persistida por elemento, procesar las tareas con el límite que hayas definido y registrar cada respuesta. Al cierre, muestra los resultados y separa las tareas completadas, las que requieren corrección y las que siguen inciertas. Estas son decisiones de diseño para tu integración, no garantías sobre el funcionamiento de una API externa.

Antes de usar el flujo en producción, prueba interrupciones y respuestas inciertas, como un timeout o una caída entre el envío y el registro del resultado. Verifica que la aplicación conserve contexto para investigar y que su política no reenvíe automáticamente tareas completadas o de resultado desconocido. Ajusta cada caso a las capacidades documentadas del servicio. Apification ofrece un asistente guiado para procesar documentos, imágenes, vídeo, audio y datos, además de opciones de integración por API; consulta la documentación del servicio para confirmar qué operaciones están disponibles por API.

• Valida las entradas y define qué significa completar cada tarea.
• Prueba interrupciones y estados inciertos sin asumir cómo responde el proveedor.
• Al cerrar el lote, identifica pendientes, errores corregibles y tareas para revisión.

Preguntas frecuentes