Como ler expressões cron
Uma expressão cron descreve um agendamento recorrente em alguns campos separados por espaços. A ideia é simples, mas a ordem dos campos e os caracteres especiais variam entre sistemas. Este guia mostra como ler os formatos mais comuns.
Os cinco campos do Unix
O cron clássico do Unix e do Linux usa cinco campos, lidos da esquerda para a direita:
minuto hora dia-do-mês mês dia-da-semana
Assim, 30 9 * * 1-5 significa "às 09:30, de segunda a sexta". Os minutos vão de 0 a 59, as horas de 0 a 23, os dias do mês de 1 a 31 e os meses de 1 a 12. O dia da semana vai de 0 a 6, com 0 significando domingo (muitas implementações também aceitam 7 para domingo). A maioria das versões também aceita nomes como JAN ou MON e macros como @daily ou @hourly.
Formatos Spring, Quartz e AWS
Outros agendadores acrescentam campos, e essa é a causa mais comum de confusão ao copiar uma expressão de um sistema para outro.
| Formato | Campos | Dia da semana |
|---|---|---|
| Unix / Linux | 5: minuto hora dia mês dia-da-semana | 0–6, domingo = 0 |
| Spring | 6: segundo minuto hora dia mês dia-da-semana | 0–7, domingo = 0 ou 7 |
| Quartz | 6 ou 7: segundo minuto hora dia mês dia-da-semana [ano] | 1–7, domingo = 1 |
| AWS EventBridge | 6: minuto hora dia mês dia-da-semana ano | 1–7, domingo = 1 |
Os mesmos dígitos podem ter significados diferentes: 0 0 12 * * ? é "todo dia ao meio-dia" no Quartz, mas não seria válido em uma leitura de 5 campos. A numeração dos dias da semana também muda: no Quartz e no AWS, 2 é segunda-feira, mas no cron do Unix é terça-feira. Nomes de dias como MON evitam essa ambiguidade onde são aceitos.
Caracteres especiais
*todos os valores do campo.,uma lista, ex.:1,15.-um intervalo, ex.:9-17ouMON-FRI./um passo:*/15no campo de minutos significa a cada 15 minutos;5/15começa em 5 (não é aceito pelo cron clássico do Unix, em que se usa um intervalo como5-59/15).?"sem valor específico"; Quartz e AWS o exigem no dia do mês ou no dia da semana.Lúltimo:Lno dia do mês é o último dia do mês; no Quartz,6Lno dia da semana é a última sexta-feira.Wdia útil mais próximo:15Wé o dia útil mais próximo do dia 15.#n-ésimo dia da semana do mês:6#3é a terceira sexta-feira na numeração do Quartz e do AWS.
L, W e # são extensões que o cron clássico do Unix não aceita.
Dia do mês vs dia da semana
Quando os dois campos de dia são restringidos, os sistemas divergem sobre como combiná-los. No cron clássico do Unix, a tarefa é executada quando qualquer um dos campos corresponde: 0 9 13 * 5 é executado no dia 13 de todo mês e em todas as sextas-feiras, e não só na sexta-feira 13. O Spring exige que os dois correspondam. Quartz e AWS evitam a questão exigindo ? em um dos dois campos.
O Analisador cron do LeedyBox aplica a regra do formato escolhido e explica no resumo se basta um dos dias ou se os dois precisam corresponder.
Fusos horários e horário de verão
Uma expressão cron não inclui fuso horário. Ela é executada no fuso horário do sistema ou serviço que a executa, que pode ser a hora local do servidor ou UTC. Uma tarefa escrita para as 09:00 no horário local pode ser executada em outra hora se o servidor usar UTC.
O horário de verão acrescenta outros casos extremos. Quando os relógios são adiantados, um horário como 02:30 pode não existir naquele dia; quando são atrasados, pode ocorrer duas vezes. Dependendo da implementação, uma tarefa nesse intervalo pode ser pulada, executada com atraso ou executada duas vezes. Agendar tarefas importantes fora do intervalo da mudança, ou em UTC, reduz as surpresas. O Analisador cron permite escolher um fuso horário e lista as próximas execuções para que você confira as datas próximas a uma mudança.
Perguntas frequentes
Como executo uma tarefa a cada 5 minutos?
No cron do Unix, use */5 * * * *. No Spring, acrescente um campo de segundos no início: 0 */5 * * * *.
Por que minha expressão do Quartz falha no crontab do Linux?
As expressões do Quartz começam com um campo de segundos e podem usar ? ou L, que o crontab não aceita. Reescreva a expressão no formato de 5 campos.
As próximas execuções mostradas pelo analisador são exatas?
Elas são calculadas no seu navegador para o formato e o fuso horário selecionados. Confirme o agendamento no sistema que vai executar a tarefa, pois as implementações podem diferir.