Como programar tarefas com o Cron para Java 8

Python 2.7/3 |Java 8/11 |PHP 5/7 |Ruby |Go 1.11 / 1.12+ |Node.js

Aviso: nesta página, o Cron é usado com o arquivo de configuração cron XML que usa o conjunto de ferramentas que foi entregue com o SDK do App Engine autônomo. Esse SDK e as ferramentas dele, como o AppCfg, agora estão obsoletos, e você deve usar as ferramentas do SDK do Cloud, como a linha de comando gcloud, ou os plug-ins baseados no SDK do Cloud: Maven, Gradle, Eclipse ou IntelliJ. Para mais informações, consulte a versão YAML desta página.

Com o Cron Service do App Engine, é possível configurar 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 um cron job para enviar um relatório de e-mail diariamente, para atualizar dados armazenados em cache a cada 10 minutos ou para atualizar informações de resumo uma vez a cada hora.

Um cron job realiza uma solicitação GET de HTTP a um URL conforme programado. O gerenciador desse URL executa a lógica quando ele é chamado. Uma solicitação de cron job está sujeita aos mesmos limites das filas de tarefas push.

Antes de começar

Para implantar ou atualizar programações, sua conta requer uma das seguintes funções do IAM:

• Proprietário
• Editor

Defina a permissão na página do IAM no Console do Google Cloud.

Como criar um cron job

1. Crie o arquivo cron.xml no diretório WEB-INF/ do aplicativo (com appengine-web.xml).

2. Adicione uma ou mais entradas <cron> ao arquivo e defina os elementos necessários para o job, incluindo os elementos <url> e <schedule> obrigatórios.

   Este é um exemplo da criação de um cron job básico executado diariamente:

   <?xml version="1.0" encoding="UTF-8"?>
   <cronentries>
     <cron>
       <url>/tasks/summary</url>
       <target>beta</target>
       <description>daily summary job</description>
       <schedule>every 24 hours</schedule>
     </cron>
   </cronentries>
   

   A especificação do destino é opcional e é o nome de um serviço/uma versão. Se estiver presente, o destino será precedido pelo nome do host do aplicativo, fazendo com que o job seja roteado para esse serviço/essa versão. Se nenhum destino for especificado, o job será executado nas versões do serviço default que estão configuradas para o tráfego.

3. Crie um gerenciador para o URL do cron job. O gerenciador precisa executar todas as tarefas que você quiser agendar. O gerenciador precisa responder com um código de status HTTP entre 200 e 299 (inclusive) para indicar o êxito. Outros códigos de status podem ser retornados e usados para a repetição do cron job.

O gerenciador pode ser tão simples quanto um servlet no aplicativo. O mapeamento do URL do servlet em web.xml precisa ser igual ao URL do cron job. Saiba mais sobre a sintaxe e as opções do cron.xml.

Como testar cron jobs no servidor de desenvolvimento

O servidor de desenvolvimento local não executa automaticamente os cron jobs. Faça solicitações diretamente no URL do cron job para testar a funcionalidade. Use o cron local ou interface de tarefas programadas para acionar os URLs dos jobs com a ferramenta curl ou similar.

Como recuperar cron jobs com falha

Se o gerenciador da solicitação de um cron job retornar um código de status que não esteja no intervalo entre 200 e 299 (inclusive), o App Engine considerará que o job falhou. Por padrão, os jobs com falha não são repetidos a menos que um código de status 503 seja retornado. Nesse caso, ocorre uma nova tentativa a cada minuto até que a falha seja eliminada ou sejam retornados códigos de status entre 200 e 299.

Para definir que os jobs com falha sejam repetidos:

1. Inclua um bloco retry-parameters no arquivo cron.xml.

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

   Por exemplo, o arquivo de amostra cron.xml inclui um único cron job que está configurado para fazer no máximo cinco tentativas (padrão) com uma espera inicial de 2,5 segundos que dobra a cada vez.

   <cronentries>
     <cron>
       <url>/retry</url>
       <description>Retry on jsdk</description>
       <schedule>every 10 minutes</schedule>
       <retry-parameters>
         <min-backoff-seconds>2.5</min-backoff-seconds>
         <max-doublings>5</max-doublings>
       </retry-parameters>
     </cron>
   </cronentries>
   

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

Como implantar cron jobs

Opção 1: envie o aplicativo completo

Para fazer upload do aplicativo completo, o que também atualiza o serviço Cron com as entradas do arquivo cron.xml, execute o seguinte comando:

./appengine-java-sdk/bin/appcfg.sh -A your-app-id -V app-version update [YOUR_APP_DIR]

Opção 2: faça upload apenas das atualizações do cron

Para atualizar apenas a configuração do cron sem fazer upload do resto do aplicativo, execute o seguinte comando:

./appengine-java-sdk/bin/appcfg.sh -A your-app-id -V app-version update_cron [YOUR_APP_DIR]

Como excluir todos os cron jobs

Para excluir todos os cron jobs:

1. Edite o conteúdo do arquivo cron.xml para:

   <?xml version="1.0" encoding="UTF-8"?>
   <cronentries/>
   

2. Implante o arquivo cron.xml no App Engine.

Como proteger URLs para cron

Você pode impedir que usuários acessem URLs usados por tarefas programadas restringindo o acesso somente a contas administrativas. As tarefas programadas podem acessar URLs somente de administrador. Leia mais sobre como restringir URLs em Segurança e autenticação. Um exemplo que poderia ser usado em web.xml para restringir tudo que começa com /cron/ apenas para administradores é:

<security-constraint>
    <web-resource-collection>
        <web-resource-name>cron</web-resource-name>
        <url-pattern>/cron/*</url-pattern>
    </web-resource-collection>
    <auth-constraint>
        <role-name>admin</role-name>
    </auth-constraint>
</security-constraint>

Observação: embora os cron jobs possam usar caminhos de URL restritos com <role-name>admin</role-name>, eles não podem usar caminhos de URL restritos com <role-name>*</role-name> porque as tarefas agendadas pelo cron não são executadas como qualquer usuário. A restrição admin é atendida pela inclusão do cabeçalho X-Appengine-Cron descrito abaixo.

Para saber mais sobre o formato de web.xml, consulte a documentação sobre o descritor de implantação.

Para testar um cron job, faça login como administrador e acesse o URL do gerenciador no navegador.

Solicitações 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 gerenciador de solicitação encontrar esse cabeçalho, ele terá certeza de que a solicitação vem do cron. Se o cabeçalho estiver presente em uma solicitação de usuário externo no aplicativo, ele será removido, exceto em solicitações de administradores registrados do aplicativo, que têm autorização para definir o cabeçalho para fins de teste.

O App Engine emite solicitações de cron usando o endereço IP 0.1.0.2. Para jobs do cron criados com versões anteriores do gcloud (anteriores a 326.0.0), as solicitações do Cron virão de 0.1.0.1.

Como chamar os Google Cloud Endpoints

Não é possível especificar um Google Cloud Endpoint no campo url de um cron job. Se você quiser que o cron job chame um Google Cloud Endpoint, envie uma solicitação para um destino que seja veiculada por um gerenciador no aplicativo e chame o método e a classe do endpoint a partir do código do gerenciador.

Como visualizar cron jobs no Console do Cloud

É possível visualizar os cron jobs programados na guia Cron Jobs do App Engine no Cloud Scheduler.

Você também pode ver os registros para saber quando os cron jobs foram adicionados ou removidos.

Saiba mais

Veja informações detalhadas sobre como definir cron jobs na Referência do cron.xml.