Agendar tarefas com o Cron para Java 8 (com base na CLI gcloud)

O serviço cronológico do App Engine permite-lhe configurar tarefas agendadas regularmente que funcionam em horários definidos ou 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 uma tarefa cron para enviar um relatório por email diariamente, atualizar alguns dados em cache a cada 10 minutos ou atualizar as 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.

Um pedido de tarefa cron está sujeito aos mesmos limites que os das filas de tarefas push.

Antes de começar

Para implementar ou atualizar programações, a sua conta requer uma das seguintes funções de IAM:

  • Proprietário
  • Editor

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

Criar um trabalho cron

  1. Crie o ficheiro cron.yaml no diretório raiz da sua aplicação (juntamente com app.yaml).

  2. Adicione uma ou mais entradas <cron> ao seu ficheiro e defina os elementos necessários para a sua tarefa, incluindo os elementos obrigatórios <url> e <schedule>. Reveja a sintaxe e as opções de cron.yaml para ver mais detalhes acerca dos elementos do ficheiro cron.yaml.

    O exemplo seguinte cria uma tarefa cron básica que é executada diariamente:

    cron:
- description: "daily summary job"
  url: /tasks/summary
  target: beta
  schedule: every 24 hours

    A especificação do destino é opcional e é o nome de um serviço/versão. Se estiver presente, o destino é adicionado antes do nome do anfitrião da sua app, o que faz com que a tarefa seja encaminhada para esse serviço/versão. Se não for especificado nenhum destino, a tarefa é executada nas versões do serviço configuradas para tráfego.default

  3. Crie um controlador para o URL da tarefa cron. O controlador deve executar todas as tarefas que quer agendar. O controlador deve responder com um código de estado HTTP entre 200 e 299 (inclusive) para indicar êxito. Podem ser devolvidos outros códigos de estado e podem ser usados para tentar novamente a tarefa cron.

O controlador pode ser tão simples como um Servlet na app. O mapeamento do URL do Servlet em web.xml deve ser igual ao URL da tarefa cron.

Testar tarefas cron no servidor de programação

O servidor de desenvolvimento local não executa automaticamente as suas tarefas cron. Pode fazer pedidos diretamente ao URL da tarefa cron para testar a sua funcionalidade. Pode usar a interface cron local ou de tarefas agendadas para acionar os URLs das suas tarefas com curl ou uma ferramenta semelhante.

Repetir tarefas cron que falham

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, a menos que seja devolvido um código de estado 503. Nesse caso, são feitas novas tentativas a cada minuto até que a tarefa seja bem-sucedida ou devolva um código de estado entre 200 e 299.

Para definir a repetição de tarefas com falhas:

  1. Inclua um bloco retry_parameters no ficheiro cron.yaml.

  2. Escolha e defina os parâmetros de repetição no bloco retry_parameters.

    Por exemplo, este ficheiro cron.yaml de amostra contém uma única tarefa cron que está configurada para repetir até cinco vezes (a predefinição) 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

Saiba mais sobre as opções de repetição do cron.

Implementar tarefas cron

Para implementar as tarefas cron especificadas no ficheiro de configuração cron.yaml, execute o seguinte comando:

gcloud

gcloud app deploy cron.yaml

Maven

mvn appengine:deployCron cron.yaml

Gradle

gradle appengineDeployCron cron.yaml

IDE

Se usar o IntelliJ ou o Eclipse, selecione os ficheiros de configuração individuais a implementar através do formulário de implementação.

Eliminar todas as tarefas cron

Para eliminar todas as tarefas cron:

  1. Edite o conteúdo do ficheiro cron.yaml para:

    cron:

  2. Implemente o ficheiro cron.yaml no App Engine.

Proteger URLs para o cron

Um controlador cron é apenas um controlador normal definido em app.yaml. Pode impedir que os utilizadores acedam a URLs usados por tarefas agendadas restringindo o acesso a contas de administrador. As tarefas agendadas podem aceder a URLs apenas para administradores. Pode restringir um URL adicionando login: admin à configuração do controlador em app.yaml.

Um exemplo pode ter o seguinte aspeto em app.yaml:

application: hello-cron
version: 1
runtime: java
api_version: 1

handlers:
- url: /report/weekly
  servlet: mysite.server.CronServlet
  login: admin

Para testar uma tarefa cron, inicie sessão como administrador e visite o URL do controlador no seu navegador.

Os pedidos do serviço Cron também contêm um cabeçalho HTTP:

X-Appengine-Cron: true

O cabeçalho X-Appengine-Cron é definido internamente pelo App Engine. Se o seu controlador de pedidos encontrar este cabeçalho, pode confiar que o pedido é um pedido cron. Se o cabeçalho estiver presente num pedido de um utilizador externo à sua app, é removido, exceto para pedidos de administradores com sessão iniciada da aplicação, que têm autorização para definir o cabeçalho para fins de teste.

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.

Chamar o Google Cloud Endpoints

Não pode especificar um ponto final do Google Cloud no campo url de uma tarefa cron. Se quiser que a tarefa cron chame um Google Cloud Endpoint, envie um pedido a um destino apresentado por um controlador na sua app e chame a classe e o método do ponto final a partir do código do controlador.

Visualizar tarefas cron na consola Google Cloud

Pode ver trabalhos cron agendados no separador Trabalhos cron do App Engine do Cloud Scheduler.

Também pode ver registos para saber quando foram adicionadas ou removidas tarefas cron.

Saiba mais

Consulte informações detalhadas sobre a definição de tarefas cron na referência cron.yaml.