Formato e fuso horário do cron job

Os cron jobs são programados em intervalos recorrentes e especificados usando um formato baseado em unix-cron. É possível definir uma programação para que o job seja executado diversas vezes por dia ou em dias e meses determinados. Embora não recomendemos mais o uso, o agendamento de um job criando um arquivo cron.yaml ainda é aceito para jobs existentes.

O Cloud Scheduler também oferece suporte à programação de jobs usando um formato mais legível. Para mais informações, consulte Formato de job alternativo neste documento.

Formato do cron job

Você pode usar o console do Google Cloud, a CLI do Google Cloud ou a API REST do Cloud Scheduler para definir sua programação.

Uma programação é definida usando o formato de string unix-cron (* * * * *), que é um conjunto de cinco campos em uma linha, indicando quando o job deve ser executado.

Os campos de hora têm o formato e os valores possíveis a seguir e precisam seguir esta ordem:

|------------------------------- Minute (0-59)
|     |------------------------- Hour (0-23)
|     |     |------------------- Day of the month (1-31)
|     |     |     |------------- Month (1-12; or JAN to DEC)
|     |     |     |     |------- Day of the week (0-6; or SUN to SAT; or 7 for Sunday)
|     |     |     |     |
|     |     |     |     |
*     *     *     *     *
Campo Valores válidos
Minuto 0-59
Hora 0-23
dia do mês 1-31
Mês 1 a 12 (ou JAN a DEZ)
Dia da semana 0-6 (ou DOM a SÁB; ou 7 para domingo)

  • Minuto:indica quanto tempo depois do início da hora o job é executado, em minutos. Por exemplo, se o minuto for definido como 0, o job será executado no início da hora (porque é 0 minuto após a hora). Portanto, se a hora for 8h, o job será executado às 8h.

  • Hora:indica quanto tempo depois da meia-noite o job é executado, em horas (arredondamento para baixo para a hora mais próxima, porque os minutos restantes são indicados no campo minute). A meia-noite é 0 e o meio-dia é 12. Por exemplo, se a hora estiver definida como 0, o job será executado à meia-noite (porque é 0 hora após a meia-noite).

  • Dia do mês:indica a data do mês. Por exemplo, 1 para o primeiro dia do mês. O Cloud Scheduler não aceita L como o último dia do mês.

  • Mês:indica o mês. Especifique o número do mês ou as três primeiras letras do nome do mês em maiúsculas. Por exemplo, 1 para janeiro ou JAN.

  • Dia da semana:indica o dia da semana. Por exemplo, segunda-feira é 1 e terça-feira é 2. 0ou 7 podem indicar domingo. Especifique o dia da semana por número ou pelas três primeiras letras do nome do dia da semana em letras maiúsculas (por exemplo, SUN para domingo).

    • Esse campo é avaliado como um OR inclusivo com o campo day of the month, a menos que um desses campos seja marcado como ilimitado pelo asterisco (*). Por exemplo, se o dia do mês for definido como 1 e o dia da semana for definido como SAT, o job será executado no primeiro dia do mês e em todos os sábados do mês, mesmo que o primeiro dia do mês não seja um sábado. Se o dia da semana não tiver restrição (definido como *), o job será executado apenas no primeiro dia do mês.

Corresponder a todos os valores

Para corresponder a todos os valores de um campo, use o asterisco: *. Quando um campo é definido como asterisco, ele corresponde a todos os valores válidos para esse campo sempre que as demais condições do campo forem atendidas. A definição de um campo como asterisco às vezes é chamada de deixar o campo irrestrito, porque ele não é restringido a um valor específico.

Confira dois exemplos em que o campo de minutos não tem restrições:

  • * 0 1 1 1: o job é executado a cada minuto da meia-noite em 1º de janeiro e às segundas-feiras.
  • * * * * *: o job é executado a cada minuto (de cada hora, de cada dia do mês, de cada mês, de cada dia da semana, porque cada um desses campos também não tem restrição).

O asterisco é equivalente a um caso especial de um intervalo, em que o intervalo começa no primeiro valor válido do campo e termina no último valor válido do campo (por exemplo, 0-59 para o campo de minutos).

Corresponder a um intervalo

Para corresponder a um intervalo de valores, especifique os valores de início e de término, separados por um hifen (-). Não inclua espaços no intervalo. Os intervalos são inclusivos. O primeiro número precisa ser menor que o segundo. Se você estiver usando nomes abreviados para o mês ou o dia da semana (por exemplo, JAN em vez de 1 para o primeiro mês do ano), o primeiro valor precisa ser anterior ao segundo no mês ou na semana.

Os exemplos equivalentes a seguir são executados à meia-noite nas segundas, terças, quartas, quintas e sextas-feiras (em todos os meses):

  • 0 0 * * 1-5
  • 0 0 * * MON-FRI

Como fazer a correspondência com uma lista

As listas podem conter qualquer valor válido para o campo, incluindo intervalos. Especifique seus valores separados por vírgula (,). Não inclua espaços na lista.

Exemplos:

  • 0 0,12 * * *: o job é executado à meia-noite e ao meio-dia.
  • 0-5,30-35 * * * *: o job é executado nos primeiros cinco minutos de cada meia hora (no início e no meio da hora).

Ignorar valores em um intervalo

É possível pular valores em um intervalo especificando uma taxa de progressão pelo intervalo. Às vezes, isso é chamado de uso de uma função de etapa (ou valor de etapa ou expressão de taxa). Para fazer isso, especifique o intervalo, seguido pelo traço (/) e a taxa de omissão.

Use o asterisco (*) para indicar o intervalo de todos os valores do campo. Quando você usa o asterisco, o primeiro valor no intervalo é: 0 para os campos minuto, hora e dia da semana (domingo) e 1 para os campos dia do mês e mês.

O valor da etapa não pode ser maior que o maior valor possível para o campo. A etapa padrão é 1. Portanto, a função de etapa /1 é a mesma que não usar uma função de etapa.

Exemplos de intervalos que usam funções de etapa:

  • */2: é uma função de etapa válida para qualquer campo. Para o campo de minutos, ele corresponde a 0, 2, 4, ... , 58. Para a hora, ele corresponde a 0, 2, 4, ... , 22. Para o dia do mês, ele corresponde a 1, 3, 5, ... , 31 (para um mês com 31 dias). Para o mês, ele corresponde a 1, 3, 5, ... , 11. Para o dia da semana, ele corresponde a 0, 2, 4, 6.

  • 0-12/2: é uma função de etapa válida para os campos de minuto e hora. Ele corresponde a 0, 2, 4, ... , 12.

Exemplos de programação usando funções degrau:

  • */2 * * * *: o job é executado a cada dois minutos.

  • 0 0-12/2 * * *: o job é executado a cada duas horas, na hora certa. A primeira execução é à meia-noite. A última corrida é ao meio-dia.

Exemplos de programação

A tabela a seguir mostra alguns exemplos de programações de jobs cron e as respectivas descrições:

Programar Formato do cron job Explicação
A cada minuto * * * * * É executada no minuto. Por exemplo, 9h, 9h01, 9h02 e assim por diante.
A cada hora 0 * * * * É executado na hora. Por exemplo, 9h, 10h, 11h e assim por diante.
Todos os dias 0 0 * * * É executada às 12h (00:00 no formato de 24 horas) todos os dias.
Todos os dias úteis
(seg-sex)		 Os seguintes são equivalentes:
  • 0 0 * * 1-5
  • 0 0 * * MON-FRI
 É executado às 12h (00:00 no formato de 24 horas) às segundas, terças, quartas, quintas e sextas-feiras.
Toda semana Os seguintes são equivalentes:
  • 0 0 * * 0
  • 0 0 * * 7
  • 0 0 * * SUN
 É executado aos domingos às 12h (00:00 no formato de 24 horas).
Todo mês 0 0 1 * * É executado às 12h (00:00 no formato de 24 horas) no primeiro dia do mês.
Todo trimestre Os seguintes são equivalentes:
  • 0 0 1 1,4,7,10 *
  • 0 0 1 JAN,APR,JUL,OCT *
 É executado às 12h (00:00 no formato de 24 horas) no primeiro dia do trimestre, para uma programação trimestral padrão: 1º de janeiro, 1º de abril, 1º de julho e 1º de outubro.
Todo ano Os seguintes são equivalentes:
  • 0 0 1 1 *
  • 0 0 1 JAN *
 É executado às 12h (00:00 no formato de 24 horas) no primeiro dia do primeiro mês do ano (1º de janeiro).

Fuso horário

Você pode selecionar o fuso horário para avaliar a programação no Console do Google Cloud (na página Criar um job, selecione um Fuso horário da lista) ou usando a flag gcloud --time-zone ao criar o job.

O valor desse campo precisa ser a abreviação do fuso horário usado no banco de dados tz. O fuso horário padrão é UTC.

Em alguns fusos horários, o horário de verão pode fazer com que os jobs sejam executados ou não inesperadamente. Isso ocorre porque o Cloud Scheduler é executado no horário normal. Nos casos em que um horário pode ocorrer duas vezes (como no caso de relógios retrocederem) e seu job for agendado nesse momento, ele poderá observar anomalias de execução.

Se o seu trabalho exige uma cadência muito específica, considere escolher um fuso horário que não observe o horário de verão. Especificamente, o UTC é recomendado para o Cloud Scheduler para evitar o problema completamente.

Formato de trabalho alternativo

Você pode usar um formato de especificação de tempo mais legível por humanos, conhecido como groc, que oferece uma alternativa às expressões cron. Por exemplo, alguns eventos recorrentes podem ser difíceis de especificar usando o cron, como a "terça-feira de cada mês". Nesses casos, use construções como estes exemplos:

first sunday of month 12:00
2nd,3rd tue,wed,thu of feb,aug 13:50
every wed of december 00:00
1st friday of quarter 9:00
second,4th tue,thursday of 3rd month of quarter 18:30
1,3,4,7,11,18,29 of jan,jul 12:34
03 of month 12:34
every day 09:00
every sun,tue,thu 9:00
every 48 hours
every 5 minutes
every 60 minutes on mon,wed
every 60 seconds

Para mais informações sobre a sintaxe, consulte Como definir a programação do cron job.

Ao especificar uma programação de jobs usando o groc, use a CLI gcloud ou faça uma solicitação direta à API Cloud Scheduler.

A seguir