Os cinco campos
O cron clássico, usado no crontab do Linux, nos CronJobs do Kubernetes e no GitHub Actions, lê cinco campos da esquerda para a direita. Cada campo lista os valores em que o job pode rodar, e o job roda sempre que todos os campos batem com o horário atual. Um asterisco significa qualquer valor.
| Posição | Campo | Valores permitidos | Nomes |
|---|---|---|---|
| 1 | Minuto | 0 a 59 | |
| 2 | Hora | 0 a 23 | |
| 3 | Dia do mês | 1 a 31 | |
| 4 | Mês | 1 a 12 | JAN a DEC |
| 5 | Dia da semana | 0 a 7 (0 e 7 são domingo) | SUN a SAT |
Experimente aqui: Gerador de expressão cron
Abrir a página completa da ferramentaCaracteres especiais
Quatro caracteres resolvem quase todo agendamento. Eles podem ser combinados dentro de um campo, por exemplo 1-5,10 ou 0-30/10. Os nomes de meses e dias são sempre em inglês, como JAN ou MON.
| Caractere | Significado | Exemplo | Resultado |
|---|---|---|---|
| * | Qualquer valor | * no campo hora | A cada hora |
| , | Uma lista de valores | 0,30 no campo minuto | Nos minutos 0 e 30 |
| - | Um intervalo | 9-17 no campo hora | A cada hora, das 9 às 17 |
| / | Um passo | */15 no campo minuto | A cada 15 minutos: 0, 15, 30, 45 |
| / depois de um valor | Passo a partir de um início | 5/20 no campo minuto | Nos minutos 5, 25 e 45 |
| Atalho com @ | Um agendamento com nome | @daily | Igual a 0 0 * * * |
Agendamentos comuns
Estas expressões foram conferidas com o gerador desta página. Copie a que mais se aproxima do que você precisa e ajuste os números.
| Expressão | Roda |
|---|---|
| * * * * * | A cada minuto |
| */5 * * * * | A cada 5 minutos |
| */15 * * * * | A cada 15 minutos |
| 0 * * * * | No início de cada hora |
| 30 * * * * | No minuto 30 de cada hora |
| 0 */6 * * * | A cada 6 horas: 0:00, 6:00, 12:00, 18:00 |
| 0 0 * * * | Todo dia à meia-noite |
| 0 9 * * * | Todo dia às 9:00 |
| 0 9,17 * * * | Todo dia às 9:00 e às 17:00 |
| 0 9 * * 1-5 | Às 9:00, de segunda a sexta |
| */10 9-17 * * 1-5 | A cada 10 minutos no horário comercial, em dias úteis |
| 0 22 * * 0,6 | Às 22:00 no sábado e no domingo |
| 0 9 * * 1 | Toda segunda-feira às 9:00 |
| 0 0 1 * * | No primeiro dia de cada mês, à meia-noite |
| 0 0 1,15 * * | Nos dias 1 e 15 de cada mês |
| 0 0 1 */3 * | No primeiro dia a cada três meses (trimestral) |
| 0 0 1 1 * | Uma vez por ano, em 1º de janeiro à meia-noite |
| 15 2 * * * | Toda madrugada às 2:15 |
| 0 12 * 6-8 * | Todo dia ao meio-dia em junho, julho e agosto |
| 0 8 1-7 * 1 | Cuidado: dias 1 a 7 ou qualquer segunda-feira, veja abaixo |
Dia do mês e dia da semana juntos
Esta é a regra que mais pega gente. Quando os dois campos de dia estão restritos, o cron clássico roda nos dias que batem com qualquer um deles, não com os dois. Então 0 8 1-7 * 1 não significa a primeira segunda-feira do mês: ele roda nos dias 1 a 7 e também em toda segunda-feira. Do mesmo jeito, 0 0 13 * 5 roda em todo dia 13 e em toda sexta-feira, não só na sexta-feira 13.
Tem mais um detalhe: se um dos dois campos começa com asterisco, como em */2, o cron trata esse campo como não restrito para essa regra, e os dois campos precisam bater. Por isso 0 0 */2 * 1 roda só nas segundas-feiras que caem num dia ímpar do mês. O gerador desta página aponta os dois casos na explicação.
Para rodar na primeira segunda-feira no cron clássico, agende o job para as segundas-feiras e faça o script sair se o dia do mês for maior que 7. O Quartz expressa isso diretamente com 2#1.
Fusos horários e horário de verão
O cron roda no fuso horário da máquina ou do serviço que o executa. Muitos servidores e serviços em nuvem usam UTC, os agendamentos do GitHub Actions são sempre em UTC, e os CronJobs do Kubernetes usam o fuso do controlador, a menos que você defina o campo timeZone. Alguns daemons de cron também leem uma variável CRON_TZ no crontab. No Brasil, lembre que o horário de Brasília é UTC-3: 0 9 * * * num servidor em UTC roda às 6:00 em Brasília.
Em fusos com horário de verão, uma noite por ano não tem 2:30 e outra tem 1:30 duas vezes. A maioria dos daemons de cron do Linux roda os jobs da hora pulada logo depois da mudança e roda jobs de horário fixo só uma vez na hora repetida, enquanto jobs que rodam a cada hora rodam nas duas. Outros agendadores podem pular a execução. Se um job precisa rodar exatamente uma vez por dia, agende fora do intervalo entre 1:00 e 3:00, ou rode o agendador em UTC. A lista de execuções do gerador marca cada execução que cai numa mudança de horário.
Segundos, Quartz e Spring
Agendadores Java e alguns de JavaScript acrescentam um campo de segundos no início, então as expressões deles têm seis campos: 0 */5 * * * * roda a cada cinco minutos, no segundo 0. O Quartz vai além e muda várias regras, por isso uma expressão clássica muitas vezes falha nele.
- O Quartz tem 6 ou 7 campos: segundos, minuto, hora, dia do mês, mês, dia da semana e um ano opcional.
- Os dias da semana são numerados de 1 a 7 começando pelo domingo, então MON é 2. Nomes como MON-FRI evitam a confusão.
- Um dos dois campos de dia precisa ser ?, que significa nenhum valor específico. 0 0 9 ? * MON-FRI roda às 9:00 em dias úteis.
- L significa último: L no campo dia do mês é o último dia do mês, 6L no campo dia da semana é a última sexta-feira.
- W escolhe o dia útil mais próximo: 15W roda no dia útil mais perto do dia 15, LW no último dia útil do mês.
- # escolhe a enésima ocorrência de um dia da semana: 6#3 é a terceira sexta-feira do mês.
- O @Scheduled do Spring também usa seis campos com os segundos primeiro, mas numera os dias da semana de 0 a 7 como o cron clássico e não exige ?.
Erros para evitar
- Escrever * * * * * quando você quer uma vez por dia. O primeiro campo é o minuto, então isso roda 1440 vezes por dia.
- Achar que */7 no campo dia do mês significa a cada sete dias. Significa os dias 1, 8, 15, 22 e 29, e recomeça no dia 1.
- Agendar para o dia 31, 30 ou 29. Meses sem esse dia são pulados, não passam para o último dia.
- Esquecer o fuso horário. 0 9 * * * num servidor em UTC roda às 9:00 UTC, o que pode ser madrugada onde estão os seus usuários.
- Usar recursos do Quartz como L ou ? num crontab do Linux, ou uma expressão de cinco campos no Quartz. O gerador converte entre as sintaxes quando você troca.