Formato do cron job e fuso horário

Os cron jobs são programados em intervalos recorrentes, especificados com um formato baseado em unix-cron. Defina uma programação para que o job seja executado várias vezes por dia ou em dias e meses específicos. Embora não seja mais recomendado usá-la, a sintaxe cron do App Engine legada ainda é compatível com os jobs atuais.

Formato do cron job

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

formato de string unix-cron

É possível usar o console do Google Cloud, a Google Cloud CLI ou a API REST do Cloud Scheduler para definir a programação.

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

Campo Valores válidos
Minuto 0-59
Hora 0-23
dia do mês 1-31
Mês 1-12 (ou JAN a DEZ)
Dia da semana 0-6 (ou SUN para SAT ou 7 para domingo)
  • Minuto: indica em minutos após a parte superior da hora em que o job é executado. Por exemplo, se o minuto estiver definido como 0, o job será executado na parte superior da hora (porque 0 minuto após a hora). Portanto, se a hora for 8h, o job será executado às 8h.

  • Hora:o hour indica quanto após a meia-noite seu job é executado, em horas (arredondadas para 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 estiver definida como 0, o job será executado à meia-noite (porque isso significa 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 é compatível com L para indicar 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 equivalente, JAN.

  • Dia da semana:indica o dia da semana. segunda é 1, terça-feira é 2 e assim por diante. Tanto 0 quanto 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 irrestrito pelo asterisco (*). Por exemplo, se o dia do mês for definido como 1 e o dia da semana for 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 for restrito (definido como *), o job será executado apenas no primeiro dia do mês.

Correspondência de 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 aquele campo sempre que as outras condições de campo forem atendidas. Às vezes, definir um campo com o asterisco significa deixar o campo sem restrições, porque ele não está restrito a um valor específico.

Veja dois exemplos em que o campo de minuto é deixado sem restrições:

  • * 0 1 1 1: o job é executado a cada minuto da meia-noite no dia 1o de janeiro e nas segundas-feiras.
  • * * * * *: o job é executado a cada minuto (de cada hora, de todos os dias do mês, de todos os meses, todos os dias da semana, porque cada um desses campos também não tem restrições).

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

Como fazer a correspondência de um intervalo

Para fazer a correspondência com um intervalo de valores, especifique os valores de início e parada, separados por 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 valor 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 (para todos os meses):

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

Como fazer a correspondência de uma lista

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

Exemplos:

  • 0 0,12 * * *: o job é executado à meia-noite e meio-dia.
  • 0-5,30-35 * * * *: o job é executado em cada um dos primeiros cinco minutos a cada meia hora (na parte superior da hora e na meia hora).

Como pular valores em um intervalo

Para pular valores em um intervalo, especifique uma taxa para percorrer o intervalo. Às vezes, isso é chamado de função de etapa, valor ou expressão de taxa de etapa. Para fazer isso, especifique o intervalo, seguido pela barra (/) e a taxa em que você quer pular o intervalo.

Você pode usar 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 de minuto, hora e dia da semana (domingo), e 1 para dia do mês e mês.

O valor do intervalo não pode ser maior do que o maior valor possível para o campo. A etapa padrão é 1. Portanto, a função de etapa /1 é o mesmo 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. No campo de minuto, corresponde a 0, 2, 4, ... , 58. Para a hora, corresponde a 0, 2, 4, ... , 22. No dia do mês, corresponde a 1, 3, 5, ... , 31 (para um mês com 31 dias). No mês, corresponde a 1, 3, 5, ... , 11. Para o dia da semana, corresponde a 0, 2, 4, 6.

  • 0-12/2: é uma função de etapa válida para os campos de minuto e hora. 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 corrida será ao meio-dia.

Exemplos de programação

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

Programação Formato do cron job Explicação
A cada minuto * * * * * Executa no minuto. Por exemplo, 9h, 9h01, h02h e assim por diante.
A cada hora 0 * * * * Executada na hora. Por exemplo, 9h, 10h, 11h e assim por diante.
Todos os dias 0 0 * * * É executado à 0h (00h no formato de 24 horas) todos os dias.
Todos os dias da semana
(de segunda a sexta-feira)
Os seguintes são equivalentes:
  • 0 0 * * 1-5
  • 0 0 * * MON-FRI
É executado à 0h (00h no formato de 24 horas) às segundas, terças, quartas, quintas-feiras e sextas-feiras.
Toda semana Os seguintes são equivalentes:
  • 0 0 * * 0
  • 0 0 * * 7
  • 0 0 * * SUN
É executado aos domingos à 0h (00h00 no formato de 24 horas).
Todo mês 0 0 1 * * É executado à 0h (00h 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 à 0h (00h no formato de 24 horas) no primeiro dia do trimestre, para uma programação trimestral padrão: 1o de janeiro, 1o de abril, 1o de julho e 1o de outubro.
Todo ano Os seguintes são equivalentes:
  • 0 0 1 1 *
  • 0 0 1 JAN *
É executado à 0h (00h no formato de 24 horas) no primeiro dia do primeiro mês do ano (1o de janeiro).

Fuso horário

É possível selecionar o fuso horário para avaliar a programação no console do Google Cloud (na página Criar um job, selecione uma opção de Fuso horário na lista) ou usando a sinalização gcloud --time-zone ao criar o job. O fuso horário padrão é Etc/UTC.

Em alguns fusos horários, o horário de verão pode fazer com que os jobs sejam executados ou não de forma inesperada. Isso ocorre porque o Cloud Scheduler é executado em tempo real. Nos casos em que um horário pode ocorrer duas vezes (como quando os relógios voltam para trás) e o job está programado nesse horário, o job programado pode observar anomalias de execução.

Caso seu job exija uma cadência muito específica, escolha um fuso horário que não siga o horário de verão. Especificamente, é recomendado usar o UTC do Cloud Scheduler para evitar o problema completamente.