Formato da tarefa cron e fuso horário

As tarefas cron são agendadas em intervalos recorrentes, especificados através de um formato baseado no unix-cron. Pode definir uma programação para que a tarefa seja executada várias vezes por dia ou em dias e meses específicos. (Embora já não recomendemos a sua utilização, a agendamento de uma tarefa através da criação de um ficheiro cron.yaml continua a ser suportado para tarefas existentes.)

O Cloud Scheduler também suporta o agendamento de tarefas através de um formato mais legível para humanos. Para mais informações, consulte a secção Formato de trabalho alternativo neste documento.

Formato de tarefa cron

Pode usar a Google Cloud consola, a CLI do Google Cloud ou a API REST do Cloud Scheduler para definir a sua programação.

Uma programação é definida através do formato de string unix-cron (* * * * *), que é um conjunto de cinco campos numa linha, indicando quando a tarefa deve ser executada.

Os campos de tempo têm o seguinte formato e valores possíveis, e têm de 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 após o início da hora o seu trabalho é executado. Por exemplo, se o minuto estiver definido como 0, a tarefa é executada no início da hora (porque são 0 minutos após a hora). Assim, se a hora for 08:00, a tarefa é executada às 08:00.

• Hora: indica quanto tempo passou da meia-noite em que a tarefa foi executada, em horas (arredondado para baixo à 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, a tarefa é executada na hora da meia-noite (porque são 0 horas após a meia-noite).

• Dia do mês: indica a data do calendário do mês. Por exemplo, 1 para o primeiro dia do mês. O Cloud Scheduler não suporta L para significar 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, em alternativa, 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 maiúsculas (por exemplo, SUN para domingo).

  • Este campo é avaliado como um OR inclusivo com o campo day of the month, a menos que um destes campos esteja marcado como sem restrições pelo asterisco (*). Por exemplo, se o dia do mês estiver definido como 1 e o dia da semana estiver definido como SAT, a tarefa é executada 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 (estiver definido como *), a tarefa é executada 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 com o asterisco, o campo corresponde a todos os valores válidos para esse campo sempre que as outras condições do campo forem satisfeitas. A definição de um campo para o asterisco é, por vezes, denominada deixar o campo sem restrições, porque não está restrito a um valor específico.

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

• * 0 1 1 1: a tarefa é executada todos os minutos da hora da meia-noite a 1 de janeiro e às segundas-feiras.
• * * * * *: a tarefa é executada todos os minutos (de todas as horas, de todos os dias do mês, de todos os meses, todos os dias da semana, porque cada um destes campos também não tem restrições).

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).

Fazer corresponder um intervalo

Para fazer corresponder um intervalo de valores, especifique os valores inicial e final, separados por um hífen (-). Não inclua espaços no intervalo. Os intervalos são inclusivos. O primeiro número tem de ser inferior ao segundo número. Se estiver a usar 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 tem de ocorrer mais cedo no mês ou na semana do que o segundo valor.

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

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

Fazer corresponder 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 * * *: a tarefa é executada à meia-noite e ao meio-dia.
• 0-5,30-35 * * * *: a tarefa é executada nos primeiros cinco minutos de cada meia hora (no início da hora e às meias horas).

Ignorar valores num intervalo

Pode ignorar valores num intervalo especificando uma taxa de progressão no intervalo. Por vezes, isto é designado por usar uma função de degrau (ou valor de degrau ou expressão de taxa). Para o fazer, especifique o intervalo, seguido da barra (/) e da taxa à qual quer avançar no intervalo.

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

O valor do passo não pode ser superior ao maior valor possível para o campo. O passo predefinido é 1, pelo que a função de passo /1 é igual a não usar nenhuma função de passo.

Exemplos de intervalos que usam funções escalonadas:

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

• 0-12/2: esta é uma função de passo válida para os campos de minutos e horas. Corresponde a 0, 2, 4, ... , 12.

Exemplos de horários com funções escalonadas:

• */2 * * * *: a tarefa é executada a cada dois minutos.

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

Exemplos de agendas

A tabela seguinte mostra alguns exemplos de agendamentos de tarefas cron e a respetiva descrição:

Fuso horário

Pode selecionar o fuso horário para avaliar a programação naGoogle Cloud consola (na página Criar uma tarefa, selecione um fuso horário na lista) ou através da flag gcloud --time-zone quando cria a tarefa.

O valor deste campo tem de ser a abreviatura do fuso horário usada na base de dados tz. O fuso horário predefinido é UTC.

Para alguns fusos horários, o horário de verão pode fazer com que as tarefas sejam executadas ou não executadas inesperadamente. Isto deve-se ao facto de o Cloud Scheduler ser executado na hora do relógio de parede. Nos casos em que uma hora pode ocorrer duas vezes (como quando os relógios são atrasados) e a sua tarefa está agendada para esta hora, a tarefa agendada pode observar anomalias de execução.

Se o seu trabalho exigir uma cadência muito específica, recomendamos que considere escolher um fuso horário que não siga a mudança de hora. Especificamente, o UTC é recomendado para o Cloud Scheduler para evitar completamente o problema.

Formato de tarefa alternativo

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

Tenha em atenção que, quando especifica uma programação de tarefas com o groc, tem de usar a CLI gcloud ou fazer um pedido direto à API Cloud Scheduler.

Por exemplo, alguns eventos recorrentes podem ser difíceis de especificar com o cron, como "a terceira terça-feira de cada mês". Nesses casos, pode usar construções como os seguintes 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 minute

Para mais informações sobre a sintaxe, consulte o artigo Definir a programação da tarefa cron.

O que se segue?

• Alterar a região ou a zona predefinida
• Veja as regiões e as zonas disponíveis