Formato e fuso horário do cron job

Os cron jobs são programados em intervalos recorrentes, 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 é compatível com jobs atuais.

O Cloud Scheduler também permite programar jobs usando um formato mais legível para humanos. Para mais informações, consulte Formato alternativo de job neste documento.

Formato de cron job

Você pode usar o console do Google Cloud , a Google Cloud CLI ou a API REST do Cloud Scheduler para definir seu agendamento.

Um planejamento é definido 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 data e hora têm o seguinte formato e valores possíveis, 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)
|     |     |     |     |
|     |     |     |     |
*     *     *     *     *

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

• Hora:indica quantas horas após a meia-noite seu job é executado (arredondado para baixo até a hora mais próxima, porque os minutos restantes são indicados no campo minute). Meia-noite é 0 e meio-dia é 12. Por exemplo, se a hora for definida como 0, o job será executado à meia-noite (porque esse é o horário 0 após a meia-noite).

• Dia do mês:indica a data do mês no calendário. 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, de maneira equivalente, JAN.

• Dia da semana:indica o dia da semana. Por exemplo, segunda-feira é 1 e terça-feira é 2. 0 ou 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 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 deles seja marcado como sem restrições pelo asterisco (*). Por exemplo, se o dia do mês for definido como 1 e o dia da semana 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ções (definido como *), o job será executado apenas no primeiro dia do mês.

Correspondência com todos os valores

Para corresponder a todos os valores de um campo, use o asterisco: *. Quando um campo é definido como o asterisco, ele corresponde a todos os valores válidos para esse campo sempre que as outras condições de campo são atendidas. Definir um campo como asterisco às vezes é chamado de deixar o campo sem restrições, porque ele não é restrito 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 do dia 1º de janeiro e das 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 é irrestrito).

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

Correspondência de um intervalo

Para corresponder a um intervalo de valores, especifique os valores de início e fim, separados por um hífen (-). 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 dia da semana (por exemplo, JAN em vez de 1 para o primeiro mês do ano), o primeiro valor precisa vir antes do segundo no mês ou na semana.

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

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

Correspondência de uma lista

As listas podem conter qualquer valor válido para o campo, incluindo intervalos. Especifique os valores separados por uma 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 da hora e na meia hora).

Ignorar valores em um intervalo

É possível pular valores em um intervalo especificando uma taxa de incremento. Às vezes, isso é chamado de usar uma função de etapa (ou valor de etapa ou expressão de taxa). Para fazer isso, especifique o intervalo, seguido da barra (/) e da taxa em que você quer pular o intervalo.

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 coisa que não usar uma função de etapa.

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

• */2: essa é 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ções usando funções de etapa:

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

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

Exemplos de programação

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

Fuso horário

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

O valor desse campo precisa ser a abreviação do fuso horário usada 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 de maneira inesperada. 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 job exigir 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 alternativo de job

Você pode usar um formato de especificação de tempo mais legível, conhecido como groc, que oferece uma alternativa às expressões cron.

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

Por exemplo, alguns eventos recorrentes podem ser difíceis de especificar usando cron, como "terceira terça-feira de cada mês". Nesses casos, use construções como os exemplos a seguir:

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 minute

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

A seguir

• Como mudar a região ou a zona padrão
• Conferir regiões e zonas disponíveis