Tarefas Agendadas do Orbit

Tarefas cron agendadas fazem pedidos HTTP recorrentes ao seu projeto implementado, para que uma limpeza noturna, uma sincronização por hora ou um resumo semanal seja executado no tempo certo sem que você tenha de configurar um agendador separado.

Onde as Tarefas Cron Residem

Abra Orbit, clique no projeto e escolha Crons no grupo Configure na fita de abas do projeto. A página é intitulada Cron jobs e descreve o que faz: agendar pedidos HTTP para a sua implementação de produção, usando sintaxe cron padrão de cinco campos em UTC, ou os aliases @hourly, @daily, @weekly e @monthly.

A página mostra o Target host que será chamado, para que possa confirmar à primeira vista que está apontando para a implementação certa.

Como Funciona

Orbit não executa o seu código num agendador. Chama um URL no seu próprio projeto numa agenda e o seu código faz o trabalho.

Isto significa que a coisa que agenda é uma rota ordinária na sua aplicação, por exemplo /api/cron/cleanup. Tudo aquilo que a sua aplicação consegue fazer em resposta a um pedido, consegue fazer numa agenda.

Criar uma Tarefa Cron

1. Clique em New cron.
2. Dê-lhe um Name, até 120 caracteres.
3. Defina o Path no seu projeto, começando com uma barra.
4. Escolha um Schedule nas predefinições ou escreva uma expressão.
5. Escolha um Method. GET é a predefinição.
6. Adicione um Request body se o método for POST, PUT ou PATCH.
7. Defina um Timeout entre 1 e 300 segundos. A predefinição é 30.
8. Deixe a opção Generate a Bearer secret marcada a menos que tenha a sua própria autenticação.
9. Clique em Create cron.

Predefinições de Agenda

Ou escreva a sua própria expressão de cinco campos: minuto, hora, dia do mês, mês, dia da semana.

Autenticar a Chamada

Deixar a opção Bearer secret marcada gera um token aleatório que é enviado como cabeçalho Authorization em cada execução. É mostrado uma vez, imediatamente após a criação, com a nota de que não será mostrado novamente.

Copie-o e verifique-o no seu manipulador:

export async function GET(req) {
  const auth = req.headers.get('authorization');
  if (auth !== `Bearer ${process.env.CRON_SECRET}`) {
    return new Response('Unauthorized', { status: 401 });
  }
  // do the work
}

Guarde o segredo usando as variáveis de ambiente do projeto: ver Variáveis de Ambiente em Orbit.

Pode também enviar os seus próprios cabeçalhos em alternativa, se a sua aplicação já tem um esquema de autenticação.

Ler a Lista de Tarefas

Cada tarefa mostra:

• Schedule, a expressão em que é executada.
• Next, quando será executada novamente.
• Last, quando foi executada pela última vez e como correu.
• Um contador ok / fail.
• Last error, onde a falha mais recente deixou uma mensagem.
• Um emblema PAUSED quando está desligada.

Quatro ações estão em cada linha: Run now, Pause ou Resume e Delete.

Run now executa a tarefa imediatamente, independentemente da sua agenda, e relata o resultado. É a forma correta de testar uma nova tarefa em vez de esperar pelo próximo ciclo.

Resultados de Execução

Cada execução é registada com o seu estado, código de resposta, duração, erro e o que a acionou, para que uma tarefa que falhe intermitentemente deixe um registo que pode ler em vez de um único "last error".

Escolher um Timeout

O timeout é por execução, entre 1 e 300 segundos, com predefinição de 30.

Defina-o um pouco acima do pior caso real da tarefa, não muito acima. Um timeout generoso numa tarefa que pendurou significa cinco minutos de um construtor à espera de nada. Um timeout apertado numa tarefa que legitimamente demora dois minutos significa uma falha permanente e um alerta enganoso.

Melhor ainda, mantenha o manipulador rápido: enfileire trabalho e retorne imediatamente, em vez de fazer o trabalho em linha. Uma tarefa cron que retorna em 200 milissegundos nunca sofre timeout.

Limites

Um projeto pode conter até 50 tarefas cron. Isto é por projeto, portanto uma conta com vários projetos tem mais no total.

Se precisar de agendar algo contra o staging em vez de produção, use Cron triggers em Settings em alternativa. Esse cartão permite que escolha o ambiente e é limitado a dez triggers por projeto. Ver Definições do Projeto Orbit.

Eliminar uma Tarefa

Clique em Delete e confirme. A confirmação nota que o histórico de execução também será removido, portanto se quiser um registo de como uma tarefa se comportou, capture-o antes de eliminar.

Pause em vez de eliminar quando está a parar temporariamente uma tarefa. Pausar mantém a configuração, o segredo e o histórico intactos.

Aconselhamento Prático

Torne os manipuladores idempotentes. Uma chamada cron pode ser repetida e Run now pode ser pressionado enquanto uma execução agendada já está em curso. O seu manipulador deve lidar com a execução duas vezes sem fazer o trabalho duas vezes.

Não agende tudo na hora certa. 0 * * * * em cada tarefa significa que cada tarefa está em competição no mesmo momento. Distribua-as: 7 * * * *, 23 * * * * e assim sucessivamente.

Registar dentro do seu manipulador. O registo de execução informa-lhe o código de resposta e a duração. O que realmente aconteceu é negócio da sua aplicação, e vai querer isso quando uma tarefa silenciosamente não faz nada.

Resolução de Problemas

Todas as execuções são FAILED com um 401. O seu manipulador está a rejeitar o pedido. Verifique se o segredo armazenado nas suas variáveis de ambiente corresponde ao gerado aqui, incluindo o prefixo Bearer na comparação.

Todas as execuções são FAILED com um 404. O caminho não existe no projeto implementado. Teste-o num navegador em relação ao anfitrião alvo mostrado na página.

Execuções sofrem TIMEOUT. O manipulador está a fazer demasiado em linha. Divida o trabalho ou aumente o timeout se o trabalho genuinamente demora esse tempo e não é um runaway.

Next nunca avança. A tarefa está pausada. Procure o emblema PAUSED.

A tarefa é executada na hora errada. Verifique UTC em relação à sua hora local. Esta é a surpresa mais comum com tarefas agendadas.

Para Onde Ir a Seguir

• Variáveis de Ambiente em Orbit para armazenar o segredo cron.
• Definições do Projeto Orbit para triggers cron por ambiente.
• Webhooks do Orbit para ser informado quando as coisas correm mal.