Use o arquivo cron.yaml
para definir tarefas programadas para o aplicativo.
Para saber mais sobre como programar tarefas, incluindo teste, implantação ou exclusão de cron jobs, consulte Como agendar tarefas com o cron.
Exemplo
Veja o exemplo de um 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
Sintaxe
O arquivocron.yaml
pode residir em qualquer lugar no código-fonte: cron.yaml
configura tarefas programadas para o aplicativo Java 8.
Para mais informações sobre o formato YAML, consulte o site do YAML.
Definições de cron jobs
Elemento | Descrição |
---|---|
description |
Opcional. A descrição está visível no Console do GCP e na interface de administração do servidor de desenvolvimento. Coloque o valor da descrição entre aspas. |
retry_parameters |
Opcional. Caso o gerenciador da solicitação de um cron job retorne um código de status HTTP fora do intervalo entre 200 e 299, o App Engine considerará o job com falha. Por padrão, os jobs com falha não serão executados novamente. Tente executar novamente os jobs com falha incluindo blocos de parâmetros de novas tentativas no arquivo de configuração.
Consulte a seção Novas tentativas do cron para mais informações. |
schedule |
Obrigatório. Define o programa de execução do cron job. Consulte a sintaxe abaixo. |
target |
A string
Se o nome de serviço especificado para
Ao utilizar um arquivo de expedição, o job pode ser roteado novamente. Por exemplo, com os seguintes arquivos, # 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 |
timezone |
timezone é o nome de um fuso horário zoneinfo (em inglês) padrão. Caso você não especifique um fuso horário, a programação será em UTC, também conhecido como GMT.
|
url |
Obrigatório.
O campo url especifica um URL no aplicativo a ser chamado pelo Cron Service. Para mais informações, consulte Como proteger URLs para cron.
|
Como definir o schedule
do cron job
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 de início do próximo, sendo que "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 às
00:00
e cumpre o período especificado entre cada job.Por exemplo: na programação
every 5 minutes
, o job é executado diariamente com um intervalo de cinco 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 independentemente de quando o job anterior é concluído ou expira. É possível configurar um intervalo de tempo em que você quer que o job seja executado ou executar jobs 24 horas por dia começando à
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 um job. No intervalo, um horário de início individual será ignorado se o job anterior não for concluído ou expirar.
Por exemplo: na programação
every 5 minutes from 10:00 to 14:00
, o primeiro job começa a ser executado às10:00
e depois a cada cinco minutos. Se esse primeiro job for executado por sete minutos, o job das10: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 constam de uma programação personalizada são executados durante todo o ano, apenas no horário específico, nos dias e meses selecionados.
Por exemplo: na programação
1,2,3 of month 07:00
, o job é executado uma vez às07:00
nos primeiros três 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 definição de uma programação inválida:
schedule: every 6 hours mon,wed,fri
. - Apenas uma instância do job será executada a qualquer momento. 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 do job 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 schedule
Para especificar o momento da execução do job, você precisa definir o elemento schedule
usando a seguinte sintaxe:
schedule: [TYPE] [INTERVAL_VALUE] [INTERVAL_SCOPE]
Escolha um tipo de intervalo para definir o 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 ou um intervalo específico para a 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 seguintes exemplos 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
synchronized
de 24 horas.- Inclua a cláusula
from [HH:MM] to [HH:MM]
para definir um intervalo e um horário de início específico em que você quer que os jobs sejam executados.Especifique os valores de tempo 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
, dividido de maneira uniforme pelo valor [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]: 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
- A 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 seguintes valores:
- 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 mistura 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 de um ano ou uma lista separada por vírgulas de vários meses. É preciso também definir um horário específico em que você quer que o job seja executado. 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 no ano.
- [HH:MM]: especifique os valores de tempo 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 seguintes exemplos 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, ele é executado uma vez à meia-noite:
schedule: 1 of jan,april,july,oct 00:00
- É executado todos os dias à meia-noite:
Novas tentativas do cron
Se o gerenciador da solicitação de um cron job retorna um código de status que não está no intervalo entre 200 e 299, o App Engine considera que o job falhou. Por padrão, os jobs que falham não são executados novamente. Inclua um bloco
no arquivo de configuração para executar novamente jobs com falha.retry_parameters
cron:
- description: "retry demo"
url: /retry
schedule: every 10 mins
retry_parameters:
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 |
O número máximo de novas tentativas de um cron job com falha não pode exceder a "5". Se o App Engine for especificado com , ele fará uma nova tentativa do cron job até que os dois limites sejam alcançados. Quando omitido nos parâmetros, o limite é "5", por padrão.
|
job_age_limit |
O limite de tempo para tentar novamente um cron job com falha. Ele é avaliado de acordo com o momento em que o cron job foi executado pela primeira vez. O valor é um número seguido de 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ê especificá-lo com job_retry_limit , o App Engine executará novamente o cron job até que ambos os limites sejam atingidos.
|
min_backoff_seconds |
O número mínimo de segundos para 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 .
|
Solicitações do Cron
Cabeçalhos das solicitações
As solicitações do Cron Service também contêm um cabeçalho HTTP:
X-Appengine-Cron: true
O cabeçalho X-Appengine-Cron
é configurado internamente pelo Google App Engine. Com esse cabeçalho, o gerenciador de solicitação assume que essa é uma solicitação do cron. No entanto, o cabeçalho será removido caso esteja presente em uma solicitação de usuário externo. Como exceção, temos as solicitações de administradores registrados do aplicativo, com autorização para configurar o cabeçalho para fins de testes.
Endereço IP de origem
O Google App Engine emite solicitações do Cron usando o endereço IP 0.1.0.1.
Prazos
O prazo para o tempo limite do cron depende da classe da instância e do tipo de escalonamento configurado para o aplicativo:
- Escalonamento automático
- O tempo limite é de cerca de 10 minutos.
- Escalonamento básico e manual
- O tempo limite pode ser de até 24 horas.
Para mais informações, consulte Tipos de escalonamento e classes de instâncias
Limites
Os aplicativos gratuitos podem ter até 20 tarefas programadas. e os pagos podem ter até 250.
Suporte para o Cron no servidor de desenvolvimento
O servidor de desenvolvimento não executa os cron jobs automaticamente. Use o cron local ou interface de tarefas programadas para acionar os URLs dos jobs com a ferramenta curl ou similar.
Como implantar cron jobs
É possível usar a ferramenta gcloud
para implantar os cron jobs no App Engine. Também é possível implantar com os plug-ins do Maven ou Gradle do App Engine, ou com IntelliJ ou Eclipse.
-
Para implantar os cron jobs especificados no arquivo de configuração
cron.yaml
, execute o seguinte comando:
Como excluir todos os cron jobs
Para excluir todos os cron jobs:
Edite o conteúdo do arquivo
cron.yaml
para:cron:
Implante o arquivo
cron.yaml
no App Engine.
Suporte para o Cron no Console do GCP
A página "Filas de tarefas" do console do GCP tem uma guia que mostra as tarefas que executam cron jobs.
Acesse também a página Registros para ver quando os cron jobs foram adicionados ou removidos.