Como programar jobs com cron.yaml

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 chama um URL usando uma solicitação HTTP GET em um determinado horário do dia. Uma solicitação HTTP chamada por cron pode ser executada por até 60 minutos, mas está sujeita aos mesmos limites de outras solicitações HTTP.

Os aplicativos gratuitos podem ter até 20 tarefas programadas, e os pagos podem ter até 250.

Sobre o arquivo de configuração cron

Um arquivo cron.yaml no diretório raiz do aplicativo, junto com app.yaml, configura as tarefas programadas do aplicativo .NET. Este é um arquivo cron.yaml de exemplo:

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 de cada cron job. Uma definição de job precisa ter um url e um schedule. Também é possível especificar os parâmetros 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 GCP.
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, o agendamento usará o UTC, que também é conhecido como GMT.
target
Opcional. O nome de um serviço específico no app. Quando target é especificado, o Cron Service direciona a solicitação do job para esse serviço no app. As solicitações de job são encaminhadas para as versões no serviço especificado, que estão configuradas para tráfego. Saiba como as solicitações são encaminhadas.

Considerações importantes sobre target:

  • Se a divisão de tráfego estiver habilitada, 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, não são encaminhadas para outras versões.
  • Ao usar um arquivo de expedição, os jobs serão reencaminhados assim que o mesmo URL também for configurado no arquivo dispatch.yaml. Por exemplo, se o URL /tasks/hello_service2 for definido nos arquivos cron.yaml e dispatch.yaml, as solicitações de job serão enviadas para service2, mesmo que o target: service1 tenha sido 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 reexecução de jobs com falha. Consulte a sintaxe abaixo.

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 de horário de término ou de horário de início:

  • Intervalo de horário de término: define o tempo entre o "horário de término" de um job e o de início do próximo. O "horário de término" é o momento da conclusão ou expiração de um job. O serviço Cron executa jobs nesse tipo de intervalo durante 24 horas começando à 00:00 e aguarda o período especificado entre cada job.

    Por exemplo: na programação every 5 minutes, o job é executado diariamente com 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á 5 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 às 10:00 e depois a cada 5 minutos. Se esse primeiro job for executado por 7 minutos, o job das 10: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 às 07: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, 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:

Intervalo de horário de término
  • [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 ou mins
    • hours
  • [INTERVAL_SCOPE]: não aplicável. Para configurar um intervalo ou um horário de início específicos na 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 à 0h com intervalo de 5 minutos entre cada job. Após o término de cada job, o serviço Cron aguarda 5 minutos antes de executar o próximo:
    schedule: every 5 minutes
  • A execução começa todos os dias à 0h 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
Intervalo de horário de início
  • [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 ou mins
    • 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 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, 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 ou 24.

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 5 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 0h, todos os dias:
    schedule: every 2 hours synchronized
Intervalo personalizado
  • [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 ou first
      • 2nd ou second
      • 3rd ou third
      • a até: 31st ou thirtyfirst

      Exemplo:

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

  • [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 ou mon
      • tuesday ou tues
      • wednesday ou wed
      • thursday ou thurs
      • friday ou fri
      • saturday ou sat
      • sunday ou sun
      • Use day para especificar todos os dias da semana.

    Exemplos:

    schedule: 2nd monday,thurs
    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 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 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 no ano.
    • [HH:MM]: especifique os valores de tempo no formato 24 horas, HH:MM, em que:
      • 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
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, é executado uma vez à meia-noite:
    schedule: 1 of jan,april,july,oct 00:00

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 (inclusive), o App Engine considera que o job falhou. Por padrão, não há novas tentativas para jobs com falha. Faça com que jobs com falha sejam executados de novo incluindo um bloco retry_parameters no 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, que é o padrão. 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:
    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 "5". Se você especificá-lo com job_age_limit, o App Engine executará o cron job novamente até que ambos os limites sejam atingidos. 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 por uma unidade de tempo: s para segundos, m para minutos, h para horas e 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.

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:

  • Solicitações do serviço Cron 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ções confirma que ela é uma solicitação cron. O X- é eliminado dos cabeçalhos pelo App Engine quando eles vêm de fontes externas. Assim, você pode confiar nesse cabeçalho.

  • O Google App Engine emite solicitações cron usando o endereço IP 10.0.0.1.

Como fazer o upload de cron jobs

Para fazer isso, é necessário especificar o cron.yaml como um parâmetro no seguinte comando da gcloud:

gcloud beta app deploy cron.yaml

Excluir cron jobs

Para excluir todos os cron jobs, altere o arquivo cron.yaml para conter somente:

cron:

Como exibir informações do job

É possível exibir a versão analisada dos cron jobs, incluindo os horários em que eles serão executados. Basta usar o comando appcfg.py cron_info.

O appcfg.py cron_info não computará corretamente as programações se for especificado um fuso horário que não seja UTC.

Suporte do cron no Console do Google Cloud Platform

Verifique os cron jobs agendados na página de Cron jobs do Console do GCP.

Acesse também a página Registros para ver quando os cron jobs foram adicionados ou removidos.

Esta página foi útil? Conte sua opinião sobre:

Enviar comentários sobre…

Ambiente flexível do App Engine para documentos .NET