Referência cron.yaml

Use o ficheiro cron.yaml para definir tarefas agendadas para a sua aplicação.

Para saber mais sobre a programação de tarefas, incluindo como testar, implementar ou eliminar tarefas cron, consulte o artigo Programar tarefas com o Cron.

Exemplo

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

Sintaxe

O ficheiro cron.yaml deve residir no diretório raiz da sua aplicação juntamente com app.yaml: cron.yaml configura tarefas agendadas para a sua aplicação Python 2.

Para mais informações sobre o formato YAML, consulte o Website do YAML.

Definições de tarefas cron

Elemento Descrição
description Opcional. A descrição é visível na Google Cloud consola e na interface de administração do servidor de desenvolvimento. Coloque o valor da descrição entre aspas.
retry_parameters Opcional. Se o controlador de pedidos de uma tarefa cron devolver um código de estado HTTP que não esteja no intervalo de 200 a 299 (inclusive), o App Engine considera que a 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 de parâmetros de repetição no ficheiro de configuração.

Consulte a secção Voltas a tentar do Cron para mais informações.

schedule Obrigatório. Define a programação de quando a tarefa cron é executada, veja a sintaxe abaixo.
target

A string target é adicionada ao início do nome do anfitrião da sua app. Normalmente, é o nome de um serviço. A tarefa cron será encaminhada para a versão do serviço com nome configurada para tráfego.

Se o nome do serviço especificado para target não for encontrado, o pedido Cron é encaminhado para o serviço default ou para a versão da sua app que está configurada para receber tráfego.Para mais informações sobre o encaminhamento, consulte Como os pedidos são encaminhados.

Se usar um ficheiro de expedição, a sua tarefa pode ser reencaminhada. Por exemplo, dados os seguintes ficheiros cron.yaml e dispatch.yaml, a tarefa é executada em service2, mesmo que o destino seja service1: 

# 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 O valor timezone deve ser o nome de um fuso horário zoneinfo padrão. Se não especificar um fuso horário, o horário vai estar em UTC (também conhecido como GMT).
url Obrigatório. O campo url especifica um URL na sua aplicação que vai ser invocado pelo serviço Cron. Consulte o artigo Proteger URLs para o Cron para mais informações.

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 às 00:00, e aguarda a duração especificada 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 das 00:00.

    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:
  • Começa a ser executado todos os dias às 00:00 e aguarda 5 minutos entre cada tarefa. Após o fim de cada tarefa, o serviço Cron aguarda 5 minutos antes de executar a tarefa seguinte: 
    schedule: every 5 minutes
  • Começa a ser executado todos os dias às 00:00 e aguarda 30 minutos entre cada tarefa. Após cada tarefa terminar, o serviço Cron aguarda 30 minutos antes de executar a tarefa 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

Voltas a tentar do Cron

Se o controlador de pedidos de uma tarefa cron devolver um código de estado que não esteja no intervalo 200 a 299 (inclusive), o App Engine considera que a tarefa falhou. Por predefinição, não são feitas novas tentativas de 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 exemplo de um ficheiro cron.yaml que contém uma única tarefa cron configurada para tentar novamente até cinco vezes (o predefinido) 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:
    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 O número máximo de tentativas para uma tarefa cron falhada não deve exceder 5. Se for especificado com job_age_limit, o App Engine volta a tentar a tarefa cron até atingir ambos os limites. Quando omitido dos parâmetros, o limite é definido como 5 por predefinição.
job_age_limit O limite de tempo para repetir uma tarefa cron com falha, medido a partir do momento em que a tarefa cron foi 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 for especificado com job_retry_limit, o App Engine tenta novamente a tarefa cron até ambos os limites serem atingidos.
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.

Pedidos cron

Cabeçalhos do pedido

Os pedidos do serviço Cron contêm um 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. A exceção são os pedidos de administradores com sessão iniciada de apps antigas, que podem definir o cabeçalho para fins de teste.

Endereço IP de origem

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.

Tempo limite de pedido

O limite de tempo da solicitação cron depende do tipo de escalabilidade configurado para a sua app:

Escala automática
Tempo limite de pedido de 10 minutos.
Dimensionamento básico e dimensionamento manual
Limite de tempo do pedido de 24 horas.

Para mais informações, consulte o artigo Como as instâncias são geridas.

Limites

As aplicações gratuitas podem ter até 20 tarefas agendadas. As aplicações pagas podem ter até 250 tarefas agendadas.