Gerenciar cron jobs

Destino Pub/Sub

Se você escolher o tipo de destino Pub/Sub:

1. especifique o nome do tópico em que o job será publicado. Deve ser um tópico do Pub/Sub já configurado no seu projeto.

2. Especifique a mensagem para enviar ao tópico. Ele é enviado como o parâmetro data na mensagem do Pub/Sub. Para ver um exemplo que faz isso, consulte o Guia de início rápido.

3. Adicione os atributos de mensagem necessários.

4. Defina qualquer outra configuração usando a seção Configure optional settings.

O Cloud Scheduler vai publicar mensagens nesse tópico como uma conta de serviço das APIs do Google.

OK

Destino HTTP do App Engine

Se você escolher o tipo de destino HTTP do App Engine, use o aplicativo do App Engine e a região associada ao projeto atual. Se você quiser usar outro aplicativo do App Engine fora do projeto atual, escolha HTTP como destino, não HTTP do App Engine. As regras de firewall de destino precisam permitir solicitações do intervalo de IP 0.1.0.2/32.

Defina o formulário da seguinte maneira:

1. Na lista Tipo de destino, selecione HTTP do App Engine.

2. Especifique o nome do serviço do App Engine que está executando o gerenciador do job do Cloud Scheduler. Se omitido, o serviço default será usado. Se você quiser defini-lo, encontre os nomes dos serviços no console doGoogle Cloud .

3. Você também pode especificar a versão. Se ela não for definida, será usada a versão disponibilizada no momento. As versões disponíveis estão no console doGoogle Cloud .

4. Também é possível especificar a instância. Se não for definido, qualquer instância disponível poderá ser usada. As versões disponíveis estão no console doGoogle Cloud .

5. Especifique o URL relativo do endpoint do App Engine que o job vai contatar. Se você usar o valor padrão /, o job vai usar PROJECT-ID.appspot.com, em que PROJECT-ID é o ID do projeto atual.

   Observação : se você não estiver usando o serviço padrão, o URL de destino exibido na UI do console do Google Cloud será no formato SERVICE.PROJECT-ID.r.appspot.com/*. O mesmo URL exibido na janela do terminal usando a CLI tem o formato https://SERVICE-dot-PROJECT-ID.r.appspot.com/. As duas formas são equivalentes.

6. Defina o método HTTP que você quer usar ao executar o job. O padrão é POST.

7. Adicione os cabeçalhos necessários à solicitação.

8. Se quiser, especifique os dados do corpo a serem enviados ao destino. Esses dados são enviados no corpo da solicitação como bytes quando o método HTTP POST ou PUT é selecionado.

Os endpoints de destino do App Engine precisam estar no mesmo projeto e podem ser protegidos com login: admin no elemento handlers no arquivo app.yaml.

OK

Destino HTTP

Se você escolher o tipo de destino HTTP:

1. especifique o URL completo do ponto de extremidade com que o job entrará em contato.

2. Especifique o método HTTP. O padrão é POST.

3. Opcional: especifique os dados que serão enviados ao destino. Esses dados são enviados no corpo da solicitação como bytes quando o método HTTP POST ou PUT é selecionado.

4. Opcional: adicione os cabeçalhos necessários. Se o endpoint de destino exigir uma chave de API no cabeçalho, use o nome do cabeçalho que o serviço de destino espera, como x-api-key ou X-Goog-Api-Key. O uso de api_key como nome de cabeçalho pode resultar em falhas de autenticação.

5. Para criar um job de destino HTTP que exija autenticação, consulte Usar autenticação com destinos HTTP.

Os pontos de extremidade HTTP de destino precisam estar publicamente acessíveis.

Observação: ao usar um destino HTTP, o Cloud Scheduler pode informar um erro de falha na solicitação, mesmo que o destino tenha sido retornado com sucesso. Isso pode acontecer quando há uma incompatibilidade entre as configurações de tempo limite do serviço de destino e as do Cloud Scheduler. Consulte a descrição de Job para definir o campo attempt_deadline.

OK

Use o Cloud Scheduler para configurar unidades de trabalho programadas, conhecidas como cron jobs, que são enviadas para destinos em uma programação recorrente, também chamada de intervalo ou frequência do job.

Apenas uma única instância de um job deve ser executada por vez. Em raras circunstâncias, é possível que várias instâncias do mesmo job sejam solicitadas. Como resultado, o gerenciador de solicitações precisa ser idempotente, e o código precisa garantir que não haja efeitos colaterais prejudiciais se isso ocorrer.

Se um job ainda estiver em execução ou aguardando uma resposta do destino, outras execuções programadas dele serão ignoradas até que a execução atual seja concluída ou expire. Para mais informações, consulte As execuções de jobs subsequentes não estão sendo iniciadas.

Observação: o Cloud Scheduler fornece cabeçalhos que podem ajudar na eliminação de duplicação de solicitações de jobs, tornando o gerenciador de solicitações idempotente. É possível identificar uma solicitação de job de maneira exclusiva usando o nome dela e o cabeçalho X-CloudScheduler-ScheduleTime. Esse cabeçalho contém o horário de invocação programado original e permanece constante em todas as tentativas.

O Cloud Scheduler é destinado a jobs repetidos. Se você precisar executar um job apenas uma vez, use o Cloud Tasks, que pode programar uma tarefa com até 30 dias de antecedência.

Antes de começar

Verifique se você configurou o ambiente para o Cloud Scheduler.

Escolha um tipo de segmentação

O Cloud Scheduler pode invocar os seguintes tipos de destinos:

• Endpoints HTTP

• Tópicos do Pub/Sub

• Serviços do App Engine

Invocar serviços de destino restritos à entrada interna

O Cloud Scheduler pode invocar os seguintes serviços internamente:

• Cloud Run functions
• Cloud Run (no URL run.app, não em domínios personalizados)

Para invocar esses destinos internamente, o destino precisa estar no mesmo projeto doGoogle Cloud ou no perímetro do VPC Service Controls que o job do Cloud Scheduler.

Para saber como proteger destinos restringindo a entrada, consulte Como restringir a entrada (para o Cloud Run) e Como definir as configurações de rede (para as funções do Cloud Run).

Criar um job

É possível criar um job usando o console do Google Cloud ou a Google Cloud CLI.

Console

1. No console Google Cloud , acesse a página Cloud Scheduler.

   Acessar o Cloud Scheduler

2. Clique em Criar job.

3. No campo Nome, forneça um nome para o job que seja exclusivo para o projeto.

   Depois de excluir o job associado, é possível reutilizar o nome dele em um projeto.

4. Na lista Região, selecione uma região.

   Se você estiver usando um destino HTTP do App Engine, escolha a mesma região do seu aplicativo do App Engine. Para mais informações, consulte Regiões com disponibilidade por destino.

5. Opcional: forneça uma breve descrição do job, como um lembrete do que ele faz.

   Essa descrição aparece no console ao lado do nome do job.

6. Especifique a frequência com que o job será executado usando uma string de configuração.

   Por exemplo, a string 0 1 * * 0 executa o job uma vez por semana, à 1h, todos os domingos de manhã. A string fornecida aqui pode ser qualquer string compatível com o unix-cron. Para mais informações, consulte Configurar programações de cron job.

7. Na lista Fuso horário, escolha o fuso horário a ser usado na programação do job.

8. Clique em Continuar.

9. Especifique o Tipo de destino:

   • HTTP

   • Pub/Sub: é preciso especificar o nome do tópico do Pub/Sub que você já configurou no projeto e em que o job será publicado.

   • HTTP do App Engine: é preciso usar o aplicativo do App Engine e a região associada ao projeto atual.

10. Clique em Continuar.

11. Opcional: para configurar qualquer comportamento de nova tentativa, clique em Definir configurações opcionais. Para especificar a duração, use uma sequência de números inteiros não negativos decimais com os seguintes sufixos de unidade:

    • h: hora
    • m: minuto
    • s: segundo
    • ms: (milissegundos)
    • µ: microssegundo
    • ns: nanossegundo

    Não é permitido usar valores negativos e fracionários. O campo Max retry duration aceita apenas valores h, m e s. Tanto Min backoff duration quanto Max backoff duration aceitam o conjunto completo.

12. Opcional: para destinos HTTP e HTTP do App Engine, configure um prazo para as tentativas de job. Se o gerenciador de solicitações não responder até esse prazo, a solicitação será cancelada e a tentativa será marcada como falha. O Cloud Scheduler tenta executar o job novamente de acordo com a configuração de nova tentativa.

13. Para criar e salvar o job, clique em Criar.

    O job será executado na frequência especificada.

gcloud

Ao criar um job usando a CLI gcloud, você usa comandos diferentes para cada tipo de destino:

HTTP

Você pode enviar uma solicitação para qualquer ponto de extremidade HTTP ou HTTPS. Os endpoints HTTP de destino precisam ser acessíveis publicamente.

gcloud scheduler jobs create http JOB \
    --location=LOCATION \
    --schedule=SCHEDULE \
    --uri=URI

Substitua:

• JOB: um nome de job que precisa ser exclusivo no projeto. Não é possível reutilizar o nome de um job em um projeto, mesmo que você exclua o job associado.

• LOCATION: o local em que o job será executado.

• SCHEDULE: frequência ou intervalo em que o job será executado, por exemplo, every 3 hours. A string fornecida aqui pode ser qualquer string compatível com o unix-cron. Embora não recomendemos mais o uso, a sintaxe cron legada do App Engine ainda é compatível com jobs atuais.

  Para mais informações, consulte Configurar programações de cron job.

• URI: o URI totalmente qualificado do endpoint com que o job vai entrar em contato.

Outros parâmetros são descritos na referência da linha de comando gcloud:

• Opcional: especifique o método HTTP. O padrão é POST.

• Opcional: especifique os dados que serão enviados ao destino. Esses dados são enviados no corpo da solicitação como bytes quando o método HTTP POST ou PUT é selecionado.

• Opcional: use a flag --headers para incluir cabeçalhos de solicitação HTTP. Se o endpoint de destino exigir uma chave de API no cabeçalho, use o nome do cabeçalho que o serviço de destino espera, como x-api-key ou X-Goog-Api-Key. O uso de api_key como nome de cabeçalho pode resultar em falhas de autenticação.

• Opcional: defina os valores de repetição, que especificam como o job do App Engine será repetido em caso de falha. Na maioria dos casos, os padrões serão suficientes.

• Para criar um job de destino HTTP que exija autenticação, consulte Como usar a autenticação com destinos HTTP.

Exemplo

gcloud scheduler jobs create http my-http-job \
    --schedule "0 1 * * 0" \
    --uri "http://myproject/my-url.com" \
    --http-method GET

Observação: ao usar um destino HTTP, o Cloud Scheduler pode informar um erro de falha na solicitação, mesmo que o destino tenha sido retornado com sucesso. Isso pode acontecer quando há uma incompatibilidade entre as configurações de tempo limite do serviço de destino e as do Cloud Scheduler. Consulte a descrição de Job para definir o campo attempt_deadline.

Pub/Sub

É preciso usar um tópico do Pub/Sub que você já tenha configurado no projeto. O Cloud Scheduler vai publicar mensagens nesse tópico como uma conta de serviço da API do Google.

gcloud scheduler jobs create pubsub JOB \
    --location=LOCATION \
    --schedule=SCHEDULE \
    --topic=TOPIC

Substitua:

• JOB: um nome de job que precisa ser exclusivo no projeto. Não é possível reutilizar o nome de um job em um projeto, mesmo que você exclua o job associado.

• LOCATION: o local em que o job será executado.

• SCHEDULE: frequência ou intervalo em que o job será executado, por exemplo, every 3 hours. A string fornecida aqui pode ser qualquer string compatível com o unix-cron. Embora não recomendemos mais o uso, a sintaxe cron legada do App Engine ainda é compatível com jobs atuais.

  Para mais informações, consulte Configurar programações de cron job.

• TOPIC: o nome do tópico em que o job será publicado. Use a flag --message-body ou --message-body-from-file para especificar uma mensagem a ser enviada ao tópico. Ele é enviado como o parâmetro data na mensagem do Pub/Sub. Para ver um exemplo que faz isso, consulte o guia de início rápido.

Outros parâmetros são descritos na referência da linha de comando gcloud.

Exemplo

gcloud scheduler jobs create pubsub myjob \
    --schedule "0 1 * * 0" \
    --topic cron-topic \
    --message-body "Hello"

HTTP do App Engine

O destino App Engine HTTP está disponível apenas para o aplicativo do App Engine associado ao projeto atual. Se você quiser usar outro app do App Engine fora do projeto atual, escolha HTTP como o destino, não App Engine HTTP. As regras de firewall de destino precisam permitir solicitações do intervalo de IP 0.1.0.2/32.

Os endpoints do App Engine podem ser protegidos com login: admin no elemento handlers no arquivo app.yaml.

gcloud scheduler jobs create app-engine \
    --JOB=JOB \
    --location=LOCATION \
    --schedule=SCHEDULE

Substitua:

• JOB: um nome de job que precisa ser exclusivo no projeto. Não é possível reutilizar o nome de um job em um projeto, mesmo que você exclua o job associado.

• LOCATION: o local em que o job será executado. Precisa ser o mesmo local do aplicativo do App Engine.

• SCHEDULE: frequência ou intervalo em que o job será executado, por exemplo, every 3 hours. A string fornecida aqui pode ser qualquer string compatível com o unix-cron. Embora não recomendemos mais o uso, a sintaxe cron legada do App Engine ainda é compatível com jobs atuais.

  Para mais informações, consulte Configurar programações de cron job.

Outros parâmetros são descritos na referência da linha de comando gcloud:

• Especifique o URL relativo do endpoint do App Engine que o job vai contatar. Se você usar o valor padrão /, o job vai usar PROJECT-ID.appspot.com, em que PROJECT-ID é o ID do projeto atual.

• Especifique o nome do serviço do App Engine que está executando o gerenciador do job do Cloud Scheduler. Se omitido, o serviço default será usado. Se você quiser defini-lo, encontre os nomes de serviço no console doGoogle Cloud .

• Opcional: defina o método HTTP que você quer usar quando o job for executado. O padrão é POST.

• Opcional: especifique a versão. Se não for definida, a versão em exibição será usada. As versões disponíveis estão no console doGoogle Cloud .

• Opcional: especifique a instância. Se não for definido, qualquer instância disponível poderá ser usada. As versões disponíveis estão no console doGoogle Cloud .

• Opcional: especifique os dados que serão enviados ao destino. Esses dados são enviados no corpo da solicitação como bytes quando o método HTTP POST ou PUT é selecionado.

• Opcional: defina os valores de repetição, que especificam como o job do App Engine será repetido em caso de falha. Na maioria dos casos, os padrões são suficientes.

Exemplo

gcloud scheduler jobs create app-engine my-appengine-job \
    --schedule "0 1 * * 0" \
    --relative-url "/cron-handler"

Observação : se você não estiver usando o serviço padrão, o URL de destino retornado para a janela do terminal terá o formato https://SERVICE-dot-PROJECT-ID.r.appspot.com/. O mesmo URL exibido na UI do console do Google Cloud está no formato SERVICE.PROJECT-ID.r.appspot.com/*. As duas formas são equivalentes.

Editar um job

É possível editar a configuração de um job.

Console

1. No console Google Cloud , acesse a página Cloud Scheduler.

   Acessar o Cloud Scheduler

2. Selecione o job que você quer editar.

3. Clique em Editar.

4. Siga as etapas para definir a programação, configurar a execução e definir as configurações opcionais ao criar um job.

gcloud

Ao editar um job usando a CLI gcloud, você usa comandos diferentes para cada tipo de destino:

HTTP

Você pode enviar uma solicitação para qualquer ponto de extremidade HTTP ou HTTPS. Os endpoints HTTP de destino precisam ser acessíveis publicamente.

gcloud scheduler jobs update http JOB \
    --location=LOCATION \
    --schedule=SCHEDULE \
    --uri=URI

Substitua:

• JOB: um nome de job que precisa ser exclusivo no projeto. Não é possível reutilizar o nome de um job em um projeto, mesmo que você exclua o job associado.

• LOCATION: o local em que o job é executado. Se você não especificar o local, a CLI gcloud vai usar o local padrão. Se o job que você quer editar estiver em um local diferente, especifique o local além do NAME para que o job seja identificado. Não é possível atualizar o local do job.

• SCHEDULE: frequência ou intervalo em que o job será executado, por exemplo, every 3 hours. A string fornecida aqui pode ser qualquer string compatível com o unix-cron. Embora não recomendemos mais o uso, a sintaxe cron legada do App Engine ainda é compatível com jobs atuais.

  Para mais informações, consulte Configurar programações de cron job.

• URI: o URI totalmente qualificado do endpoint com que o job vai entrar em contato.

Outros parâmetros são descritos na referência da linha de comando gcloud.

Exemplo

gcloud scheduler jobs update http my-http-job \
    --schedule "0 1 * * 0" \
    --uri "http://myproject/my-url.com" \
    --http-method GET

Observação: ao usar um destino HTTP, o Cloud Scheduler pode informar um erro de falha na solicitação, mesmo que o destino tenha sido retornado com sucesso. Isso pode acontecer quando há uma incompatibilidade entre as configurações de tempo limite do serviço de destino e as do Cloud Scheduler. Consulte a descrição de Job para definir o campo attempt_deadline.

Pub/Sub

É preciso usar um tópico do Pub/Sub que você já tenha configurado no projeto. O Cloud Scheduler vai publicar mensagens nesse tópico como uma conta de serviço da API do Google.

gcloud scheduler jobs update pubsub JOB \
    --location=LOCATION \
    --schedule=SCHEDULE \
    --topic=TOPIC

Substitua:

• JOB: um nome de job que precisa ser exclusivo no projeto. Não é possível reutilizar o nome de um job em um projeto, mesmo que você exclua o job associado.

• LOCATION: o local em que o job é executado. Se você não especificar o local, a CLI gcloud vai usar seu local padrão. Se o job que você quer editar estiver em um local diferente, especifique o local além do NAME para que o job seja identificado. Não é possível atualizar o local do job.

• SCHEDULE: frequência ou intervalo em que o job será executado, por exemplo, every 3 hours. A string fornecida aqui pode ser qualquer string compatível com o unix-cron. Embora não recomendemos mais o uso, a sintaxe cron legada do App Engine ainda é compatível com jobs atuais.

  Para mais informações, consulte Configurar programações de cron job.

• TOPIC: o nome do tópico em que o job será publicado. Use a sinalização --message-body ou --message-body-from-file para especificar uma mensagem a ser enviada ao tópico. Ele é enviado como o parâmetro data na mensagem do Pub/Sub. Para ver um exemplo que faz isso, consulte o guia de início rápido.

Outros parâmetros são descritos na referência da linha de comando gcloud.

Exemplo

gcloud scheduler jobs update pubsub myjob \
    --schedule "0 1 * * 0" \
    --topic cron-topic --message-body "Hello"

HTTP do App Engine

O destino App Engine HTTP está disponível apenas para o aplicativo do App Engine associado ao projeto atual. Se você quiser usar outro app do App Engine fora do projeto atual, escolha HTTP como o destino, não App Engine HTTP.

Os endpoints do App Engine podem ser protegidos com login: admin no elemento handlers no arquivo app.yaml.

gcloud scheduler jobs update app-engine JOB \
    --location=LOCATION \
    --schedule=SCHEDULE

Substitua:

• JOB: um nome de job que precisa ser exclusivo no projeto. Não é possível reutilizar o nome de um job em um projeto, mesmo que você exclua o job associado.

• LOCATION: o local em que o job é executado (é o mesmo local do app de destino do App Engine). Se você não especificar o local, a CLI gcloud vai usar o local padrão. Se o job que você quer editar estiver em um local diferente, especifique o local além do NAME para que o job seja identificado. Não é possível atualizar o local do job.

• SCHEDULE: frequência ou intervalo em que o job será executado, por exemplo, every 3 hours. A string fornecida aqui pode ser qualquer string compatível com o unix-cron. Embora não recomendemos mais o uso, a sintaxe cron legada do App Engine ainda é compatível com jobs atuais.

  Para mais informações, consulte Configurar programações de cron job.

Outros parâmetros são descritos na referência da linha de comando gcloud.

Exemplo

gcloud scheduler jobs update app-engine my-appengine-job \
    --schedule "0 1 * * 0" \
    --relative-url "/cron-handler"

Observação : se você não estiver usando o serviço padrão, o URL de destino retornado para a janela do terminal terá o formato https://SERVICE-dot-PROJECT-ID.r.appspot.com/. O mesmo URL exibido na UI do console do Google Cloud está no formato SERVICE.PROJECT-ID.r.appspot.com/*. As duas formas são equivalentes.

Pausar um job

É possível pausar a execução de um job.

Console

1. No console do Google Cloud , acesse o Cloud Scheduler.

   Acessar o Cloud Scheduler

2. Selecione o job que você quer pausar.

3. Clique em Pausar.

gcloud

1. Abra uma janela do terminal na máquina em que você instalou a CLI gcloud.

2. Execute o comando:

    gcloud scheduler jobs pause MY_JOB
   

   Substitua MY_JOB pelo nome do job que será pausado.

Enquanto um job estiver pausado, você também poderá editá-lo. Depois de editar o job, ele permanece pausado até que você o retome.

Retomar um job

É possível retomar a execução de um job pausado.

Console

1. No console do Google Cloud , acesse o Cloud Scheduler.

   Acessar o Cloud Scheduler

2. Selecione o job que você quer retomar.

   O job precisa estar pausado.

3. Clique em Retomar.

gcloud

1. Abra uma janela do terminal na máquina em que você instalou a CLI gcloud.

2. Execute o comando:

    gcloud scheduler jobs resume MY_JOB
   

   Substitua MY_JOB pelo nome do job que será retomado.

Excluir um job

É possível excluir um job.

Console

1. No console do Google Cloud , acesse o Cloud Scheduler.

   Acessar o Cloud Scheduler

2. Selecione o job que você quer excluir.

3. Clique em Excluir.

gcloud

1. Abra uma janela do terminal na máquina em que você instalou a CLI gcloud.

2. Execute o comando:

    gcloud scheduler jobs delete MY_JOB
   

   Substitua MY_JOB pelo nome do job a ser excluído.