Orbit
Trabajos Cron de Orbit
Cron jobs schedule recurring HTTP requests to your deployed project, so a nightly cleanup, an hourly sync or a weekly digest runs on time without you standing up a separate scheduler.
Los trabajos cron programan solicitudes HTTP recurrentes a tu proyecto implementado, para que una limpieza nocturna, una sincronización horaria o un resumen semanal se ejecuten a tiempo sin que tengas que mantener un programador separado.
Dónde viven los trabajos cron
Abre Orbit, haz clic en el proyecto y elige Crons bajo el grupo Configure en la pestaña del proyecto. La página se titula Cron jobs y describe qué hace: programar solicitudes HTTP a tu implementación de producción, usando la sintaxis cron estándar de cinco campos en UTC, o los alias @hourly, @daily, @weekly y @monthly.
La página muestra el Target host al que llamará, para que puedas confirmar de un vistazo que está apuntando a la implementación correcta.
Cómo funciona
Orbit no ejecuta tu código en un programador. Llama a una URL en tu propio proyecto según un programa, y tu código realiza el trabajo.
Eso significa que lo que programas es una ruta ordinaria en tu aplicación, por ejemplo /api/cron/cleanup. Cualquier cosa que tu aplicación pueda hacer en respuesta a una solicitud, puede hacerlo según un programa.
Crear un trabajo cron
- Haz clic en New cron.
- Dale un Name, hasta 120 caracteres.
- Establece el Path en tu proyecto, comenzando con una barra.
- Elige un Schedule de los valores predefinidos o escribe una expresión.
- Elige un Method.
GETes el predeterminado. - Añade un Request body si el método es POST, PUT o PATCH.
- Establece un Timeout entre 1 y 300 segundos. El predeterminado es 30.
- Deja la opción Generate a Bearer secret marcada a menos que tengas tu propia autenticación.
- Haz clic en Create cron.
Valores predefinidos de programación
| Valor predefinido | Expresión |
|---|---|
| Every 5 min | */5 * * * * |
| Every 15 min | */15 * * * * |
| Hourly | @hourly |
| Daily 09:00 UTC | 0 9 * * * |
| Daily midnight | @daily |
| Weekly Mon 09:00 | 0 9 * * 1 |
| Monthly 1st | @monthly |
O escribe tu propia expresión de cinco campos: minuto, hora, día del mes, mes, día de la semana.
Todos los programas están en UTC, sin ajuste de horario de verano. Un trabajo establecido para 0 9 * * * se ejecuta a las 9am UTC todo el año, lo que se desvía una hora respecto a la hora de Nueva Zelanda dos veces al año. Si un trabajo debe ejecutarse a una hora local específica, elige deliberadamente la hora UTC y anota en qué mitad del año optimizaste.
Autenticar la llamada
Dejar la opción de secreto Bearer marcada genera un token aleatorio que se envía como encabezado Authorization en cada ejecución. Se muestra una vez, inmediatamente después de la creación, con la nota de que no se mostrará de nuevo.
Cópialo y verifica lo en tu manejador:
export async function GET(req) {
const auth = req.headers.get('authorization');
if (auth !== `Bearer ${process.env.CRON_SECRET}`) {
return new Response('Unauthorized', { status: 401 });
}
// do the work
}
Almacena el secreto usando las variables de entorno del proyecto: consulta Environment Variables in Orbit.
Sin una verificación como esta, tu ruta cron es una URL pública que cualquiera puede llamar tan a menudo como quiera. Eso está bien para algo inofensivo y es grave para cualquier cosa que escriba, envíe correos electrónicos o cueste dinero. Añade la verificación antes de la primera ejecución, no después de que alguien encuentre el endpoint.
También puedes enviar tus propios encabezados, si tu aplicación ya tiene un esquema de autenticación.
Leer la lista de trabajos
Cada trabajo muestra:
- Schedule, la expresión en la que se ejecuta.
- Next, cuándo se ejecutará de nuevo.
- Last, cuándo se ejecutó por última vez y cómo resultó.
- Un contador de ok / fail.
- Last error, donde el fallo más reciente dejó un mensaje.
- Una insignia PAUSED cuando está desactivado.
Cuatro acciones se encuentran en cada fila: Run now, Pause o Resume, y Delete.
Run now ejecuta el trabajo inmediatamente, independientemente de su programa, e informa del resultado. Es la forma correcta de probar un nuevo trabajo en lugar de esperar el siguiente tick.
Resultados de ejecución
| Estado | Significado |
|---|---|
| OK | Tu endpoint devolvió una respuesta de éxito |
| FAILED | Tu endpoint devolvió un error, o no se pudo hacer la solicitud |
| TIMEOUT | Tu endpoint no respondió dentro del tiempo de espera |
| SKIPPED | La ejecución no se ejecutó |
Cada ejecución se registra con su estado, código de respuesta, duración, error y qué la activó, por lo que un trabajo que falla de forma intermitente deja un rastro que puedes leer en lugar de un único "último error".
Elegir un tiempo de espera
El tiempo de espera es por ejecución, entre 1 y 300 segundos, con un predeterminado de 30.
Establécelo un poco por encima del peor caso real del trabajo, no mucho por encima. Un tiempo de espera generoso en un trabajo que se ha quedado bloqueado significa cinco minutos de un constructor esperando nada. Un tiempo de espera ajustado en un trabajo que legítimamente toma dos minutos significa un fallo permanente y una alerta engañosa.
Mejor aún, mantén el manejador rápido: que encole trabajo y devuelva inmediatamente, en lugar de hacer el trabajo en línea. Un trabajo cron que devuelve en 200 milisegundos nunca se agota el tiempo de espera.
Límites
Un proyecto puede contener hasta 50 trabajos cron. Eso es por proyecto, por lo que una cuenta con varios proyectos tiene más en total.
Si necesitas programar algo contra la puesta en escena en lugar de producción, usa Cron triggers en Settings en su lugar. Esa tarjeta te permite elegir el entorno y está limitada a diez disparadores por proyecto. Consulta Orbit Project Settings.
Eliminar un trabajo
Haz clic en Delete y confirma. La confirmación anota que el historial de ejecución también se eliminará, por lo que si quieres un registro de cómo se comportó un trabajo, captura antes de eliminar.
Pausa en lugar de eliminar cuando estés deteniendo temporalmente un trabajo. Pausar mantiene la configuración, el secreto y el historial intactos.
Consejo práctico
Hacer que los manejadores sean idempotentes. Una llamada cron se puede reintentar, y Run now se puede presionar mientras una ejecución programada ya está en progreso. Tu manejador debe ser capaz de ejecutarse dos veces sin hacer el trabajo dos veces.
No programes todo en la hora. 0 * * * * en cada trabajo significa que cada trabajo compite en el mismo momento. Distribúyelos: 7 * * * *, 23 * * * *, y así sucesivamente.
Registra dentro de tu manejador. El registro de ejecución te dice el código de respuesta y la duración. Lo que realmente sucedió es el asunto de tu aplicación, y lo querrás cuando un trabajo silenciosamente no hace nada.
Solución de problemas
Cada ejecución es FAILED con un 401. Tu manejador está rechazando la solicitud. Verifica que el secreto almacenado en tus variables de entorno coincida con el generado aquí, incluyendo el prefijo Bearer en la comparación.
Cada ejecución es FAILED con un 404. La ruta no existe en el proyecto implementado. Pruébalo en un navegador contra el host de destino que se muestra en la página.
Las ejecuciones se TIMEOUT. El manejador está haciendo demasiado en línea. Divide el trabajo, o aumenta el tiempo de espera si el trabajo genuinamente toma tanto tiempo y no es un desbordamiento.
Next nunca avanza. El trabajo está pausado. Busca la insignia PAUSED.
El trabajo se ejecuta a la hora equivocada. Verifica UTC contra tu hora local. Esta es la sorpresa más común con trabajos programados.
A dónde ir después
- Environment Variables in Orbit para almacenar el secreto cron.
- Orbit Project Settings para disparadores cron por entorno.
- Orbit Webhooks para que te avisen cuando algo sale mal.