Com o Cron Service do App Engine, você configura tarefas programadas regularmente que operam em horários definidos ou em intervalos regulares. Essas tarefas são normalmente conhecidas como cron jobs. Eles são acionados automaticamente pelo Cron Service do App Engine. Por exemplo, use-os para enviar diariamente um relatório por e-mail, atualizar dados armazenados em cache a cada 10 minutos ou atualizar algumas informações de resumo a cada hora.
O cron job faz uma solicitação HTTP GET
programada para o endpoint especificado no mesmo aplicativo em que o cron job está configurado. O gerenciador desse endpoint executa a lógica quando ele é chamado.
O Cron Service do App Engine não pode ser usado para chamar endpoints da Web fora do aplicativo host do App Engine. Ela não pode ser usada para chamar endpoints do App Engine de outros apps além do app host.
As solicitações do cron job estão sujeitas aos mesmos limites de outras solicitações HTTP. Os aplicativos gratuitos podem ter até 20 tarefas programadas. e os pagos podem ter até 250.
Para implantar ou atualizar programações, sua conta requer uma das seguintes funções de gerenciamento de identidade e acesso:
- Proprietário
- Editor
- Administrador do Cloud Scheduler (
roles/cloudscheduler.admin
)
Defina a permissão na página do IAM no console do Google Cloud.
Sobre o arquivo de configuração cron
Para todos os ambientes de execução, exceto Java, um arquivo cron.yaml
no diretório raiz do aplicativo (junto com app.yaml
) configura
as tarefas programadas para seu app.
Para o Java, um arquivo cron.yaml
no diretório WEB-INF
do seu aplicativo (junto com app.yaml
) configura tarefas programadas
para seu app.
A seguir, um exemplo de arquivo cron.yaml
:
cron:
- description: "daily summary job"
url: /tasks/summary
schedule: every 24 hours
- description: "monday morning mailout"
url: /mail/weekly
schedule: every monday 09:00
timezone: Australia/NSW
- description: "new daily summary job"
url: /tasks/summary
schedule: every 24 hours
target: beta
O arquivo cron.yaml
usa a sintaxe YAML e consiste em definições para cada um dos cron jobs. Uma definição de job precisa ter um url
e um schedule
. Também é possível especificar opcionalmente description
, timezone
, target
e retry_parameters
:
url
- Obrigatório. O URL no app que você quer que receba as solicitações de job do Cron Service.
schedule
- Obrigatório. Define a programação de quando você quer que o job seja executado. Consulte a sintaxe abaixo.
description
- Opcional. Descreve o cron job, visível no Console do Google Cloud e na interface de administrador do servidor de desenvolvimento local.
timezone
-
Opcional. O nome do fuso horário, ou "zoneinfo", que você quer usar na programação do job. Se você não especificar um fuso horário, a programação usará o
UTC
, também conhecido comoGMT
. -
target
-
Opcional. O nome de um serviço específico no seu aplicativo. Quando
target
é especificado, o serviço Cron direciona a solicitação de job para esse serviço no aplicativo. As solicitações de job são roteadas para as versões no serviço especificado que estão configuradas para tráfego. Saiba como as solicitações são roteadas.Considerações importantes sobre
target
:- Se a divisão de tráfego estiver ativada, as solicitações de job não serão divididas entre as versões configuradas:
- Divisão de endereços IP: as solicitações de job do Cron Service são sempre enviadas pelo mesmo endereço IP. Assim, elas sempre são encaminhadas para a mesma versão.
- Divisão de cookies: as solicitações de job não incluem um cookie com a solicitação. Portanto, elas não são roteadas para outras versões.
-
Se você usar um arquivo de expedição, seus jobs poderão ser roteados quando o mesmo URL também estiver configurado no
dispatch.yaml
. Por exemplo, se o URL/tasks/hello_service2
estiver definido nos dois arquivoscron.yaml
edispatch.yaml
, as solicitações de job serão enviadas paraservice2
, mesmo quetarget: service1
esteja especificado:cron.yaml
:cron: - description: "test dispatch vs target" url: /tasks/hello_service2 schedule: every 1 mins target: service1
dispatch.yaml
:dispatch: - url: '*/tasks/hello_service2' service: service2
- Se a divisão de tráfego estiver ativada, as solicitações de job não serão divididas entre as versões configuradas:
retry_parameters
- Opcional. Especifica a nova execução de jobs com falha. Consulte a sintaxe abaixo.
Como definir o cron job schedule
Os cron jobs são programados em intervalos recorrentes e especificados usando um formato simples semelhante ao inglês. É possível definir uma programação para que o job seja executado diversas vezes por dia ou em dias e meses determinados.
- Intervalos subdiários
Use um intervalo subdiário para executar um job diversas vezes por dia em uma programação repetitiva. É possível definir um intervalo para o horário de término ou de início:
Intervalo de horário de término: define o período entre o horário de término de um job e o horário de início do próximo, em que o horário de término é o momento da conclusão ou expiração do job. O serviço Cron executa jobs nesse tipo de intervalo durante 24 horas começando à
00:00
e cumpre o período especificado entre cada job.Exemplo: para a programação
every 5 minutes
, o job é executado diariamente usando um intervalo de 5 minutos. Se a instância de um job em execução nessa programação for concluída às 2h01, o próximo job aguardará cinco minutos e recomeçará às 2h06.Intervalo de horário de início: define um intervalo de tempo regular para o serviço Cron iniciar cada job. Ao contrário do intervalo de horário de término, o de horário de início executa cada job sem considerar quando o job anterior é concluído ou expira. É possível configurar um intervalo de tempo para a execução do job ou executar jobs 24 horas por dia, começando às
00:00
.Como o horário de início de um job é rigoroso, quando a execução de uma instância dele é superior ao intervalo de tempo definido, o serviço Cron ignora o job. No intervalo, um horário de início individual será ignorado caso o job anterior não tenha sido concluído ou tenha expirado .
Exemplo: para a programação
every 5 minutes from 10:00 to 14:00
, o primeiro job começa a ser executado em10:00
e a cada cinco minutos depois disso. Se esse primeiro job for executado por sete minutos, o job de10:05
será ignorado e, portanto, o serviço Cron não executará outra instância desse job até10:10
.
- Intervalo personalizado
É possível usar um intervalo personalizado para definir uma programação em que o job seja executado uma vez por dia em um ou mais dias e em um ou mais meses selecionados. Os jobs que fazem parte de uma programação personalizada são executados durante todo o ano, apenas no horário específico, nos dias e meses selecionados.
Exemplo: para a programação
1,2,3 of month 07:00
, o job é executado uma vez em07:00
nos três primeiros dias de cada mês.
Considerações importantes sobre schedule
:
- É preciso decidir entre usar um intervalo subdiário ou personalizado. Não é possível misturar nem usar elementos dos diversos tipos de intervalos. Veja a seguir um exemplo de uma definição de programação inválida:
schedule: every 6 hours mon,wed,fri
. - Só é possível executar uma instância do job por vez. O serviço Cron foi projetado para fornecer a entrega "pelo menos uma vez". Ou seja, quando um job está programado, o App Engine envia a solicitação dele pelo menos uma vez. Em raras circunstâncias, é possível que sejam solicitadas diversas instâncias do mesmo job. Se isso acontecer, será necessário que o gerenciador de solicitações seja idempotente (em inglês) e que o código garanta que não haja efeitos colaterais prejudiciais.
Como formatar o schedule
Para especificar quando o job é executado, defina o elemento schedule
usando a seguinte sintaxe:
schedule: [TYPE] [INTERVAL_VALUE] [INTERVAL_SCOPE]
Escolha um tipo de intervalo para definir seu elemento schedule
:
- [TYPE]: intervalos diários precisam incluir o prefixo
every
.Exemplo:
schedule: every 12 hours
- [INTERVAL_VALUE]: um valor inteiro e a unidade de tempo correspondente. Valores válidos para a unidade de tempo:
minutes
oumins
hours
- [INTERVAL_SCOPE]: não aplicável. Para definir um horário de início específico ou um intervalo de execução dos jobs, consulte a sintaxe do Intervalo de horário de início ou do Intervalo personalizado.
- Exemplos de intervalo de horário de término
- Os exemplos a seguir ajudarão a entender como definir programações de jobs que usam um intervalo de horário de término:
- A execução começa todos os dias à meia-noite com intervalo de cinco minutos entre cada job. Após o término de cada job, o serviço Cron aguarda cinco minutos antes de executar o próximo:
schedule: every 5 minutes
- A execução começa todos os dias à meia-noite com intervalo de 30 minutos entre cada job. Após o término de cada um deles, o serviço Cron aguarda 30 minutos antes de executar o próximo:
schedule: every 30 mins
- A execução começa todos os dias à meia-noite com intervalo de cinco minutos entre cada job. Após o término de cada job, o serviço Cron aguarda cinco minutos antes de executar o próximo:
- [TYPE]: intervalos diários precisam incluir o prefixo
every
.Exemplo:
schedule: every 12 hours
- [INTERVAL_VALUE]: um valor inteiro e a unidade de tempo correspondente. Valores válidos para a unidade de tempo:
minutes
oumins
hours
- [INTERVAL_SCOPE] especifica uma cláusula que corresponde ao [INTERVAL_VALUE]. É possível definir um intervalo de tempo personalizado ou usar a opção 24 h
synchronized
.- Inclua a cláusula
from [HH:MM] to [HH:MM]
para definir um horário de início e um intervalo específicos para executar os jobs.É preciso especificar os valores de horário no formato 24 horas,
HH:MM
, em que:HH
são números inteiros de00
a23
.MM
são números inteiros de00
a59
.
- Use
synchronized
para especificar um intervalo de tempo de 24 horas (from 00:00 to 23:59
) que é igualmente dividido pelo valor de [INTERVAL_VALUE].Importante: o [INTERVAL_VALUE] precisa dividir 24 em um número inteiro, caso contrário ocorrerá um erro. Os valores válidos para o [INTERVAL_VALUE] incluem:
1
,2
,3
,4
,6
,8
,12
ou24
.
- Inclua a cláusula
- Exemplos de intervalos de horário de início
- Os exemplos abaixo ajudarão a entender como definir programações de jobs que usam um intervalo de horário de início:
- É executado a cada cinco minutos, das 10h às 14h, todos os dias:
schedule: every 5 minutes from 10:00 to 14:00
- É executado de hora em hora, das 08h às 16h, todos os dias:
schedule: every 1 hours from 08:00 to 16:00
- É executado a cada duas horas, a partir da meia-noite, todos os dias:
schedule: every 2 hours synchronized
- É executado a cada cinco minutos, das 10h às 14h, todos os dias:
- [TYPE]: os intervalos personalizados incluem o prefixo
every
para definir um intervalo repetitivo. Também é possível definir uma lista específica de dias em um mês:- Para definir um intervalo repetitivo, use o prefixo
every
.Exemplos:
schedule: every day 00:00 schedule: every monday 09:00
- Para definir dias específicos, use números ordinais. Os valores válidos partem do 1º dia de um mês até o número máximo de dias desse mês, por exemplo:
1st
oufirst
2nd
ousecond
3rd
outhird
- E até:
31st
outhirtyfirst
Exemplo:
schedule: 1st,3rd tuesday schedule: 2nd,third wednesday of month 09:00
- Para definir um intervalo repetitivo, use o prefixo
- [INTERVAL_VALUE]: intervalos personalizados incluem uma lista dos dias específicos em que você quer que o job seja executado. Ela precisa ser uma lista separada por vírgulas e pode incluir um dos valores a seguir:
- O valor inteiro do dia no mês até 31 dias no máximo, por exemplo:
1
2
3
- E até:
31
- O nome do dia em uma combinação de qualquer um dos valores abaixo, longos ou abreviados:
monday
oumon
tuesday
outue
wednesday
ouwed
thursday
outhu
friday
oufri
saturday
ousat
sunday
ousun
- Use
day
para especificar todos os dias da semana.
Exemplos:
schedule: 2nd monday,thu schedule: 1,8,15,22 of month 09:00 schedule: 1st mon,wednesday,thu of sep,oct,nov 17:00
- O valor inteiro do dia no mês até 31 dias no máximo, por exemplo:
- [INTERVAL_SCOPE]: especifica uma cláusula que corresponde ao [INTERVAL_VALUE] especificado. Os intervalos personalizados podem incluir a cláusula
of [MONTH]
, que especifica um único mês em um ano ou uma lista separada por vírgulas de vários meses. Também é preciso definir um horário específico de execução do job, por exemplo:of [MONTH] [HH:MM]
.Por padrão, se a cláusula
of
for excluída, o intervalo personalizado será executado todos os meses.- [MONTH]: você precisa especificar os meses em uma lista separada por vírgulas podendo incluir uma mistura dos valores abaixo, longos ou abreviados:
january
oujan
february
oufeb
march
oumar
april
ouapr
may
june
oujun
july
oujul
august
ouaug
september
ousep
october
ouoct
november
ounov
december
oudec
- Use
month
para especificar todos os meses do ano.
- [HH:MM]: é preciso especificar os valores de horário no formato 24 horas,
HH:MM
, em que:HH
são números inteiros de00
a23
.MM
são números inteiros de00
a59
.
Exemplo:
schedule: 1st monday of sep,oct,nov 09:00 schedule: 1 of jan,april,july,oct 00:00
- [MONTH]: você precisa especificar os meses em uma lista separada por vírgulas podendo incluir uma mistura dos valores abaixo, longos ou abreviados:
- Exemplos de intervalos personalizados
- Os exemplos a seguir ajudarão a entender como definir programações de jobs que usam um intervalo personalizado:
- É executado todos os dias à meia-noite:
schedule: every day 00:00
- É executado todas as segundas-feiras às 9h:
schedule: every monday 09:00
- É executado uma vez na segunda quarta-feira de março às 17h:
schedule: 2nd wednesday of march 17:00
- É executado seis vezes em maio. Durante as primeiras duas semanas, é executado uma vez em cada segunda, quarta e sexta-feira às 10h:
schedule: 1st,second mon,wed,fri of may 10:00
- É executado uma vez por semana. A cada sete dias a partir do primeiro dia de cada mês, é executado uma vez às 9h:
schedule: 1,8,15,22 of month 09:00
- É executado a cada duas semanas. Na primeira e terceira segundas-feiras de cada mês, é executado uma vez às 4h:
schedule: 1st,third monday of month 04:00
- É executado três vezes por ano. Na primeira segunda-feira de setembro, outubro e novembro, é executado uma vez às 9h:
schedule: 1st monday of sep,oct,nov 09:00
- É executado uma vez a cada trimestre. No primeiro dia de janeiro, abril, julho e outubro, é executado uma vez à meia-noite:
schedule: 1 of jan,april,july,oct 00:00
- É executado todos os dias à meia-noite:
Como especificar novas tentativas
Se o gerenciador de solicitações de um cron job retornar um código de status que não esteja no intervalo entre 200 e 299 (incluindo esses dois valores), o App Engine considera que o job falhou. Por padrão, não há novas tentativas para jobs com falha. Para fazer novas tentativas de jobs com falha, inclua um bloco retry_parameters
no seu arquivo de configuração.
Veja uma amostra de arquivo cron.yaml que contém um único cron job configurado para ser executado novamente até cinco vezes. Ele tem uma espera inicial de 2,5 segundos. Esse valor é dobrado a cada tentativa.
cron:
- description: "retry demo"
url: /retry
schedule: every 10 mins
retry_parameters:
job_retry_limit: 5
min_backoff_seconds: 2.5
max_doublings: 5
Sintaxe das novas tentativas do cron
Veja descrições sobre os parâmetros das novas tentativas na tabela abaixo:
Elemento | Descrição |
---|---|
job_retry_limit |
Um número inteiro que representa o número máximo de tentativas de repetição de um
cron job com falha. O valor mínimo é 0 , e o máximo
é 5 . Se você também especificar job_age_limit ,
o App Engine tentará o cron job novamente até atingir os dois limites.
O valor padrão de job_retry_limit é 0 .
|
job_age_limit |
O limite de tempo para novas tentativas de um cron job com falha, medido a
partir da primeira execução do cron job. O valor é um número seguido por uma unidade de
tempo, em que a unidade é s para segundos, m para
minutos, h para horas ou d para dias. Por
exemplo, o valor 5d especifica um limite de cinco dias após
a primeira tentativa de execução do cron job. Se você também especificar
job_retry_limit , o App Engine tentará o cron job novamente até
atingir os dois limites.
|
min_backoff_seconds |
O número mínimo de segundos a esperar antes de tentar novamente o cron job após a falha. |
max_backoff_seconds |
O número máximo de segundos para esperar antes de tentar novamente o cron job após a falha. |
max_doublings |
O número máximo de vezes que o intervalo entre as novas tentativas do cron job com falha será duplicado antes que o aumento se torne constante. A constante é: 2**(max_doublings - 1) * min_backoff .
|
Validar solicitações do cron
É possível verificar se as solicitações para os URLs do cron vêm do App Engine, e não de outra fonte. Faça isso validando um cabeçalho HTTP e o endereço IP de origem da solicitação:
As solicitações do Cron Service contêm o seguinte cabeçalho HTTP:
X-Appengine-Cron: true
Esse e outros cabeçalhos são definidos internamente pelo App Engine. Se um cliente enviar esses cabeçalhos, eles serão removidos da solicitação.
O App Engine emite solicitações de cron usando o endereço IP
0.1.0.2
. Para jobs do cron criados com versões anteriores do gcloud (anteriores a 326.0.0), as solicitações do Cron virão de0.1.0.1
.
Para os ambientes de execução do Java, no Jetty ou o Tomcat, é possível executar essa validação em um filtro.
Tempo limite da solicitação
O tempo limite da solicitação cron depende do tipo de escalonamento configurado para o aplicativo:- Escalonamento automático
- O tempo limite da solicitação é de 10 minutos.
- Escalonamento básico e manual
- Tempo limite da solicitação de 24 horas.
Para mais informações, consulte Como as instâncias são gerenciadas.
Para mais informações sobre tempos limite de solicitação por ambiente e tipo de escalonamento, consulte Escolher um ambiente do App Engine.
Fazer upload de cron jobs
Para fazer upload de cron jobs, é preciso especificar cron.yaml
como um parâmetro para o comando gcloud a seguir:
gcloud app deploy cron.yaml
Como excluir cron jobs
Para excluir todos os cron jobs, altere o arquivo cron.yaml
para conter apenas:
cron:
Suporte ao cron no console do Google Cloud
Verifique os cron jobs programados na página Cron jobs do console do Google Cloud.
Acesse também a página Registros para ver quando os cron jobs foram adicionados ou removidos.