Ejecutar un método en forma asincrónica

Ejecutar un método en forma asincrónica

Resumen

Con la ejecución asincrónica el gateway no retiene la llamada mientras el motor procesa la vista o el pipeline: responde enseguida 202 Accepted con un identificador de tarea, y el cliente vuelve a pedir el resultado con ese identificador cuando esté listo. Es la forma de exponer consultas largas sin que el consumidor espere con la conexión abierta. En esta guía activa la ejecución asincrónica en un método, ajusta la respuesta del 202 y hace las dos llamadas.

Antes de comenzar

  • Necesita un rol que pueda editar métodos y publicar versiones de la API.
  • Aplica a los métodos de las APIs REST sobre vistas y pipelines. Los métodos de las APIs WebSocket y de los servidores MCP siempre responden en la misma llamada.

Activar la ejecución asincrónica

En el editor del método, el bloque Ejecución Asincrónica tiene las opciones Activado y Desactivado. En un método sobre un pipeline viene activada; sobre una vista, desactivada. Elija Activado, guarde el método con Listo y publique la versión.

Bloque Ejecución Asincrónica del editor del método con la opción Activado

Las dos llamadas

Primera llamada: 202 y el identificador

La llamada al método es la de siempre. Mientras el motor trabaja, el gateway responde 202 Accepted con el identificador de la tarea en uuid:

{"message": "Response is not ready call later with uuid >> 30a412f3-53c6-4a0e-8c83-97382a16dc19", "code": 409, "uuid": "30a412f3-53c6-4a0e-8c83-97382a16dc19"}

Segunda llamada: el resultado con X-UUID

Para obtener el resultado, repita la misma URL con la cabecera X-UUID y el identificador. No hay una ruta aparte de consulta:

curl -H "X-UUID: 30a412f3-53c6-4a0e-8c83-97382a16dc19" "https://api.midominio.com/demo-ventas/v1/ventas.json?auth_key=TU_LLAVE"

Si el resultado está listo, la respuesta es la del método, con su formato y su plantilla. Si todavía no, vuelve el 202 con el mismo identificador, y el cliente reintenta más tarde. Las consultas con X-UUID no consumen los límites de solicitudes del método. El resultado queda disponible durante 24 horas; pasado ese plazo, o con un identificador que no existe, el gateway responde que el proceso venció.

Ajustar la respuesta del 202

El cuerpo del 202 se arma con la plantilla de error 409 - PIPELINE RESPONSE del método, que en los métodos sobre pipelines aparece como Plantilla de ejecución de la tarea asíncrona. Tiene disponibles result.uuid, result.error_code y result.error_message. Si no asigna ninguna, se usa la plantilla genérica del método o de la cuenta, que es la del ejemplo anterior. El código HTTP es siempre 202, aunque el bloque muestre otro.

Secciones 408 - REQUEST ACCEPTED y 409 - PIPELINE RESPONSE de las plantillas de error

La plantilla 408 - REQUEST ACCEPTED cubre otro caso: un método sobre una vista cuya consulta sigue en curso cuando el motor agota su espera. El gateway responde 408 con el mensaje Trabajando, por favor reintentar en unos minutos, y el cliente repite la misma llamada hasta recibir los datos.

Resultado esperado

La primera llamada vuelve enseguida con 202 y un identificador. La misma URL con la cabecera X-UUID devuelve los datos del método con su formato, o el 202 de nuevo mientras el motor sigue trabajando.

Errores frecuentes

  • Siempre responde 200 con datos: la ejecución asincrónica quedó desactivada, la versión no se publicó después del cambio, o el método tiene caché de respuesta y la llamada anterior ya dejó el resultado guardado.
  • Process has expired or UUID is unknown: el identificador tiene más de 24 horas, es de otro método, o está mal copiado. Haga la primera llamada de nuevo.
  • La cabecera no cambia nada: el nombre es exactamente X-UUID y va en la misma URL del método, con la misma llave de acceso.
  • No aparece el bloque Ejecución Asincrónica: la API es WebSocket o MCP; en esos protocolos no está disponible.

Artículos relacionados