Agendar tarefas com cron.yaml

O serviço cronológico do App Engine permite-lhe configurar tarefas agendadas regularmente que funcionam em horários definidos ou em intervalos regulares. Estas tarefas são frequentemente conhecidas como tarefas cron. Estas tarefas cron são acionadas automaticamente pelo serviço cron do App Engine. Por exemplo, pode usar esta funcionalidade para enviar um email de relatório diariamente, atualizar alguns dados em cache a cada 10 minutos ou atualizar algumas informações de resumo uma vez por hora.

Uma tarefa cron faz um pedido HTTP GET agendado para o ponto final especificado na mesma app onde a tarefa cron está configurada. O controlador desse ponto final executa a lógica quando é chamado.

O serviço Cron do App Engine não pode ser usado para chamar pontos finais da Web fora da app de anfitrião do App Engine. Não pode ser usado para chamar pontos finais do App Engine a partir de outras apps além da app de anfitrião.

Os pedidos de tarefas cron estão sujeitos aos mesmos limites que outros pedidos HTTP . As aplicações gratuitas podem ter até 20 tarefas agendadas. As aplicações pagas podem ter até 250 tarefas agendadas.

Para implementar ou atualizar programações, a sua conta requer uma das seguintes funções de gestão de identidades e acessos:

Pode definir a autorização na página IAM na Google Cloud consola.

Acerca do ficheiro de configuração cron

Para todos os tempos de execução, exceto o Java, um ficheiro cron.yaml no diretório raiz da sua aplicação (juntamente com app.yaml) configura tarefas agendadas para a sua app.

Para o Java, um ficheiro cron.yaml no diretório WEB-INF da sua aplicação (juntamente com apppengine-web.xml) configura tarefas agendadas para a sua app.

Segue-se um exemplo de um ficheiro 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 ficheiro cron.yaml usa a sintaxe YAML e consiste em definições para cada uma das suas tarefas cron. Uma definição de tarefa tem de ter um url e um schedule. Também pode especificar opcionalmente um description, timezone, target e retry_parameters:

url
Obrigatório. O URL na sua app para o qual quer que o serviço Cron envie pedidos de tarefas.
schedule
Obrigatório. Define o horário em que quer que a tarefa seja executada. Veja a sintaxe abaixo.
description
Opcional. Descreve a sua tarefa cron, que é visível a partir da Google Cloud consola.
timezone
Opcional. O nome do fuso horário, ou "zoneinfo", que quer usar para a programação da tarefa. Se não especificar um fuso horário, a programação usa UTC, que também é conhecido como GMT.
target
Opcional. O nome de um serviço específico na sua app. Quando target é especificado, o serviço Cron destina o pedido de tarefa a esse serviço na sua app. Os pedidos de tarefas são encaminhados para as versões no serviço especificado que estão configuradas para tráfego. Saiba como os pedidos são encaminhados.

Considerações importantes para target:

  • Se tiver a divisão de tráfego ativada, os pedidos de tarefas não são divididos entre as versões que configurou:
    • Divisão de endereços IP: os pedidos de tarefas do serviço Cron são sempre enviados a partir do mesmo endereço IP e, por isso, são encaminhados para a mesma versão sempre.
    • Divisão de cookies: os pedidos de tarefas não incluem um cookie com o pedido e, por isso, não são encaminhados para outras versões.
  • Se usar um ficheiro de expedição, os seus trabalhos podem ser reencaminhados quando o mesmo URL também estiver configurado no dispatch.yaml. Por exemplo, se o URL /tasks/hello_service2 estiver definido nos ficheiros cron.yaml e dispatch.yaml, os pedidos de tarefas são enviados para service2, mesmo que target: 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
retry_parameters
Opcional. Especifica a nova execução de tarefas com falhas. Veja a sintaxe abaixo.

Definir a tarefa cron schedule

As tarefas cron são agendadas em intervalos recorrentes e são especificadas através de um formato simples semelhante ao inglês. Pode definir uma programação para que a tarefa seja executada várias vezes por dia ou em dias e meses específicos.

Intervalos inferiores a um dia

Use um intervalo inferior a um dia para executar uma tarefa várias vezes por dia numa programação repetitiva. Pode definir um intervalo de tempo de fim ou um intervalo de tempo de início:

  • Intervalo de tempo de fim: define o tempo entre a "hora de fim" de uma tarefa e o início da tarefa seguinte, em que a "hora de fim" é a hora em que a tarefa é concluída ou expira. O serviço Cron executa tarefas neste tipo de intervalo ao longo do dia de 24 horas, começando um intervalo após a hora de criação/atualização da tarefa e aguarda o intervalo especificado entre cada tarefa.

    Exemplo: para a programação every 5 minutes, a tarefa é executada diariamente com um intervalo de 5 minutos. Se uma instância de uma tarefa que está a ser executada neste horário for concluída às 02:01, a tarefa seguinte aguarda 5 minutos e começa novamente às 02:06.

  • Intervalo de tempo de início: define um intervalo de tempo regular para o serviço Cron iniciar cada tarefa. Ao contrário do intervalo de tempo de fim, o intervalo de tempo de início executa cada tarefa independentemente de quando a tarefa anterior é concluída ou atinge o limite de tempo. Pode definir um intervalo de tempo no qual quer que a tarefa seja executada ou executar tarefas 24 horas por dia, a partir do início do intervalo de tempo especificado.

    Uma vez que a hora de início de uma tarefa é rigorosa, se uma instância de uma tarefa for executada durante mais tempo do que o intervalo de tempo definido, o serviço Cron pode ignorar uma tarefa. Pode ignorar uma hora de início individual no intervalo se a tarefa anterior não tiver sido concluída ou se expirar o tempo.

    Exemplo: para a every 5 minutes from 10:00 to 14:00programação, a primeira tarefa começa a ser executada às 10:00 e, em seguida, a cada 5 minutos. Se essa primeira tarefa for executada durante 7 minutos, a tarefa 10:05 é ignorada e, por isso, o serviço Cron não executa outra instância desta tarefa até 10:10.

Intervalo personalizado

Pode usar um intervalo personalizado para definir um agendamento em que a tarefa pode ser executada uma vez por dia num ou mais dias selecionados e num ou mais meses selecionados. As tarefas executadas num horário personalizado são executadas durante todo o ano, apenas na hora específica nos dias e meses selecionados.

Exemplo: para a programação 1,2,3 of month 07:00, a tarefa é executada uma vez às 07:00 nos primeiros três dias de cada mês.

Considerações importantes para schedule:

  • Tem de decidir se quer usar um intervalo inferior a um dia ou um intervalo personalizado. Não pode misturar nem usar elementos dos vários tipos de intervalos. Segue-se um exemplo de uma definição de agendamento inválida: schedule: every 6 hours mon,wed,fri.
  • Só deve executar uma única instância de uma tarefa em qualquer altura. O serviço cronológico foi concebido para fornecer uma entrega "pelo menos uma vez"; ou seja, se uma tarefa for agendada, o App Engine envia o pedido de tarefa, pelo menos, uma vez. Em algumas circunstâncias raras, é possível pedir várias instâncias da mesma tarefa. Por isso, o seu controlador de pedidos deve ser idempotente, e o seu código deve garantir que não existem efeitos secundários prejudiciais se isto ocorrer.

Formatar o schedule

Para especificar quando a tarefa é executada, tem de definir o elemento schedule com a seguinte sintaxe:

schedule: [TYPE] [INTERVAL_VALUE] [INTERVAL_SCOPE]

Escolha um tipo de intervalo para definir o elemento schedule:

Intervalo de tempo de fim
  • [TYPE]: os intervalos diários têm de 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 ou mins
    • hours
  • [INTERVAL_SCOPE]: não aplicável. Para definir uma hora de início específica ou um intervalo no qual quer que os seus trabalhos sejam executados, consulte a sintaxe do intervalo de tempo de início ou do intervalo personalizado.
Exemplos de intervalos de tempo final
Use os seguintes exemplos para ajudar a compreender como definir agendamentos de tarefas que usam um intervalo de tempo de fim:
  • Aguarda 5 minutos após a implementação para ser executado pela primeira vez. Após cada tarefa terminar, o serviço Cron aguarda 5 minutos antes de executar a tarefa seguinte: 
    schedule: every 5 minutes
  • Aguarda 30 minutos após a implementação para ser executado pela primeira vez. Depois de cada trabalho terminar, o serviço Cron aguarda 30 minutos antes de executar o trabalho seguinte: 
    schedule: every 30 mins
Intervalo de tempo de início
  • [TYPE]: os intervalos diários têm de 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 ou mins
    • hours
  • [INTERVAL_SCOPE] Especifica uma cláusula que corresponde a [INTERVAL_VALUE]. Pode definir um intervalo de tempo personalizado ou usar a opção 24 horas synchronized.
    • Inclua a cláusula from [HH:MM] to [HH:MM] para definir uma hora de início e um intervalo específicos nos quais quer executar tarefas.

      Tem de especificar os valores de tempo no formato de 24 horas, HH:MM, onde:

      • HH são números inteiros de 00 a 23.
      • MM são números inteiros de 00 a 59.
    • Use synchronized para especificar um intervalo de tempo de 24 horas (from 00:00 to 23:59) que é dividido igualmente pelo valor [INTERVAL_VALUE].

      Importante: o [INTERVAL_VALUE] tem de dividir 24 por um número inteiro. Caso contrário, ocorre um erro. Os valores válidos para [INTERVAL_VALUE] incluem: 1, 2, 3, 4, 6, 8, 12 ou 24.

Exemplos de intervalos de tempo de início
Use os seguintes exemplos para ajudar a compreender como definir agendamentos de tarefas que usam um intervalo de tempo de início:
  • É executado a cada 5 minutos das 10:00 às 14:00, todos os dias: 
    schedule: every 5 minutes from 10:00 to 14:00
  • É executado uma vez por hora das 08:00 às 16:00, todos os dias: 
    schedule: every 1 hours from 08:00 to 16:00
  • É executado uma vez a cada duas horas, todos os dias, a partir das 00:00: 
    schedule: every 2 hours synchronized
Intervalo personalizado
  • [TYPE]: os intervalos personalizados podem incluir o prefixo every para definir um intervalo repetitivo ou pode definir uma lista específica de dias num mês:
    • Para definir um intervalo repetitivo, pode usar o prefixo every.

      Exemplos: 

      schedule: every day 00:00
schedule: every monday 09:00

    • Para definir dias específicos, tem de usar números ordinais. Os valores válidos vão do 1.º dia de um mês até ao número máximo de dias desse mês. Por exemplo:
      • 1st ou first
      • 2nd ou second
      • 3rd ou third
      • E até: 31st ou thirtyfirst

      Exemplo: 

      schedule: 1st,3rd tuesday
schedule: 2nd,third wednesday of month 09:00

  • [INTERVAL_VALUE]: os intervalos personalizados incluem uma lista dos dias específicos em que quer que a tarefa seja executada. A lista tem de ser definida numa lista separada por vírgulas e pode incluir qualquer um dos seguintes valores:
    • O valor inteiro do dia no mês até um máximo de 31 dias, por exemplo:
      • 1
      • 2
      • 3
      • E até: 31
    • O nome do dia numa combinação de qualquer um dos seguintes valores longos ou abreviados:
      • monday ou mon
      • tuesday ou tue
      • wednesday ou wed
      • thursday ou thu
      • friday ou fri
      • saturday ou sat
      • sunday ou sun
      • 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

  • [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 num ano, ou uma lista separada por vírgulas de vários meses. Também tem de definir uma hora específica para quando quer que a tarefa seja executada, por exemplo: of [MONTH] [HH:MM].

    Por predefinição, se a cláusula of for excluída, o intervalo personalizado é executado todos os meses.

    • [MONTH]: tem de especificar os meses numa lista separada por vírgulas e pode incluir uma combinação dos seguintes valores longos ou abreviados:
      • january ou jan
      • february ou feb
      • march ou mar
      • april ou apr
      • may
      • june ou jun
      • july ou jul
      • august ou aug
      • september ou sep
      • october ou oct
      • november ou nov
      • december ou dec
      • Use month para especificar todos os meses do ano.
    • [HH:MM]: tem de especificar os valores de tempo no formato de 24 horas, HH:MM, onde:
      • HH são números inteiros de 00 a 23.
      • MM são números inteiros de 00 a 59.

      • Exemplo: 

      schedule: 1st monday of sep,oct,nov 09:00
schedule: 1 of jan,april,july,oct 00:00

Exemplos de intervalos personalizados
Use os seguintes exemplos para ajudar a compreender como definir agendamentos de tarefas que usam um intervalo personalizado:
  • É executado todos os dias às 00:00: 
    schedule: every day 00:00
  • É executado todas as segundas-feiras às 09:00: 
    schedule: every monday 09:00
  • É executada uma vez na segunda quarta-feira de março às 17:00: 
    schedule: 2nd wednesday of march 17:00
  • É executado seis vezes em maio. Durante as primeiras duas semanas, é executado uma vez às segundas, quartas e sextas-feiras às 10:00: 
    schedule: 1st,second mon,wed,fri of may 10:00
  • É executado uma vez por semana. Todos os sete dias a partir do primeiro dia de cada mês, é executado uma vez às 09:00: 
    schedule: 1,8,15,22 of month 09:00
  • É executado a cada duas semanas. Na primeira e terceira segunda-feira de cada mês, é executado uma vez às 04:00: 
    schedule: 1st,third monday of month 04:00
  • É executada três vezes por ano. Na primeira segunda-feira de setembro, outubro e novembro, é executado uma vez às 09:00: 
    schedule: 1st monday of sep,oct,nov 09:00
  • É executado uma vez por trimestre. No primeiro dia de janeiro, abril, julho e outubro, é executado uma vez às 00:00: 
    schedule: 1 of jan,april,july,oct 00:00

Especificar novas tentativas

Se o controlador de pedidos de uma tarefa cron devolver um código de estado que não esteja no intervalo 200–299 (inclusive), o App Engine considera que essa tarefa falhou. Por predefinição, não são repetidas as tarefas com falhas. Pode fazer com que as tarefas com falhas sejam repetidas incluindo um bloco retry_parameters no ficheiro de configuração.

Segue-se um ficheiro cron.yaml de exemplo que contém uma única tarefa cron configurada para tentar novamente até cinco vezes com um recuo inicial de 2,5 segundos que duplica a cada vez.

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 de novas tentativas do Cron

Os parâmetros de repetição estão descritos na tabela abaixo.

Elemento Descrição
job_retry_limit Um número inteiro que representa o número máximo de tentativas para uma tarefa cron falhada. O valor mínimo é 0 e o valor máximo é 5. Se também especificar job_age_limit, o App Engine tenta novamente a tarefa cron até atingir ambos os limites. O valor predefinido de job_retry_limit é 0.
job_age_limit O limite de tempo para repetir uma tarefa cron com falha, medido a partir do momento em que a tarefa cron é executada 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 da tarefa cron. Se também especificar job_retry_limit, o App Engine tenta novamente a tarefa cron até atingir ambos os limites.
min_backoff_seconds O número mínimo de segundos a aguardar antes de tentar novamente uma tarefa cron após a falha.
max_backoff_seconds O número máximo de segundos a aguardar antes de tentar novamente uma tarefa cron depois de falhar.
max_doublings O número máximo de vezes que o intervalo entre as novas tentativas de tarefas cron falhadas é duplicado antes de o aumento se tornar constante. A constante é: 2**(max_doublings - 1) * min_backoff.

Validar pedidos cron

Pode querer validar se os pedidos aos seus URLs cron estão a ser enviados pelo App Engine e não por outra origem. Pode fazê-lo validando um cabeçalho HTTP e o endereço IP de origem do pedido:

  • Os pedidos do Cron Service contêm o seguinte cabeçalho HTTP:

    "X-Appengine-Cron": "true"

    Este e outros cabeçalhos são definidos internamente pelo App Engine. Se um cliente enviar estes cabeçalhos, são removidos do pedido.

  • O App Engine emite pedidos Cron a partir do endereço IP 0.1.0.2. Para tarefas cron criadas com versões mais antigas do gcloud (anteriores a 326.0.0), os pedidos cron vão ser enviados a partir de 0.1.0.1.

Para os tempos de execução Java, no Jetty ou no Tomcat, pode realizar esta validação num filtro.

Tempo limite de pedido

O tempo limite do pedido cron é de 60 minutos.

Para mais informações sobre os limites de tempo de pedidos por ambiente e tipo de escalabilidade, consulte o artigo Escolha um ambiente do App Engine.

Carregar tarefas cron

Para carregar as suas tarefas cron, tem de especificar o cron.yaml como um parâmetro para o seguinte comando gcloud:

gcloud app deploy cron.yaml

Eliminar tarefas cron

Para eliminar todas as tarefas cron, altere o ficheiro cron.yaml para que contenha apenas:

cron:

Suporte de cron na Google Cloud consola

Pode verificar as tarefas cron agendadas na Google Cloud consola página Tarefas cron.

Também pode visitar a página Registos para ver quando foram adicionadas ou removidas tarefas cron.