Definir parâmetros de repetição para uma tarefa

Ao criar uma tarefa, é possível especificar o número máximo de vezes para tentar novamente uma tarefa com falha, definir um limite de tempo para as tentativas e controlar o intervalo entre elas usando o método projects.locations.queues.tasks.create (link em inglês). Depois que uma tarefa é executada, ela é removida da fila. Em todos os casos, o limite máximo de retenção de tarefas também se aplica.

Essa configuração de nova tentativa no nível da tarefa substitui a configuração de nova tentativa no nível da fila para a tarefa.

Configurar novas tentativas ao criar uma tarefa

O exemplo a seguir demonstra a definição de parâmetros de nova tentativa ao criar uma tarefa de destino HTTP enviando uma solicitação direta à API Cloud Tasks. É possível usar os mesmos parâmetros de nova tentativa ao criar uma tarefa do App Engine. Para mais detalhes sobre os parâmetros, consulte as configurações de RetryConfig do recurso Task.

Antes de usar os dados da solicitação abaixo, faça as substituições a seguir:

  • PROJECT_ID: obrigatório. O ID do projeto do projeto Google Cloud em que a tarefa será criada.
  • REGION: obrigatório. A região em que a fila é implantada, por exemplo, us-central1.
  • QUEUE_ID: obrigatório. O ID da fila a que a tarefa será adicionada.
  • URL: obrigatório. O URL totalmente qualificado para onde a solicitação será enviada. Essa string precisa começar com http:// ou https://. Por exemplo: https://www.example.com.
  • SERVICE_ACCOUNT_EMAIL: opcional. O e-mail da conta de serviço usado para gerar um token de autorização incluído na solicitação enviada ao destino ao executar a tarefa. A conta de serviço precisa estar no mesmo projeto que a fila. O autor da chamada precisa ter a permissão iam.serviceAccounts.actAs para a conta de serviço.

    Para gerar um token de acesso do OAuth2 em vez de um token do OpenID Connect, substitua o campo oidcToken por oauthToken para especificar o e-mail da conta de serviço.

  • MAX_ATTEMPTS: opcional. O número máximo de tentativas para uma tarefa, incluindo a primeira. Para permitir novas tentativas ilimitadas, defina isso como -1. MAX_RETRY_DURATION ainda se aplica mesmo que MAX_ATTEMPTS seja atingido ou definido como -1.
  • MAX_RETRY_DURATION: opcional. O tempo máximo para tentar de novo uma tarefa com falha, medido desde a primeira tentativa. O valor precisa ser uma string que termine em "s", como 5s. Para especificar uma duração ilimitada, defina como 0s. MAX_ATTEMPTS ainda se aplica mesmo que MAX_RETRY_DURATION seja atingido ou definido como 0s.
  • MIN_INTERVAL: opcional. O tempo mínimo de espera entre as tentativas. O valor precisa ser uma string que termine em "s", como 5s.
  • MAX_INTERVAL: opcional. O tempo máximo de espera entre novas tentativas. O valor precisa ser uma string que termine em "s", como 5s.
  • MAX_DOUBLINGS: opcional. O número máximo de vezes que o intervalo entre novas tentativas de tarefas com falha será dobrado antes que o aumento se torne constante. O intervalo de novas tentativas de uma tarefa começa em MIN_INTERVAL, depois dobra MAX_DOUBLINGS vezes, aumenta linearmente e, por fim, tenta novamente em intervalos de MAX_INTERVAL até MAX_ATTEMPTS vezes.

    Por exemplo, se MIN_INTERVAL for 10s, MAX_INTERVAL for 300s e MAX_DOUBLINGS for 3, o intervalo de repetição vai dobrar 3 vezes, aumentar linearmente em 2^3 * 10s e tentar novamente em intervalos de MAX_INTERVAL até que a tarefa seja tentada MAX_ATTEMPTS vezes: 10s, 20s, 40s, 80s, 160s, 240s, 300s, 300s e assim por diante.

  • SCHEDULE_TIME: opcional. O horário em que a tarefa está programada para ser executada, no formato RFC 3339. Por exemplo, 2026-10-02T15:01:23Z. Se o horário não estiver definido ou for no passado, o Cloud Tasks vai definir o horário atual.

Corpo JSON da solicitação:

{
  "task": {
    "httpRequest": {
      "url": "URL",
      "httpMethod": "POST",
      "oidcToken": {
        "serviceAccountEmail": "SERVICE_ACCOUNT_EMAIL"
      }
    },
    "retryConfig": {
      "maxAttempts": MAX_ATTEMPTS,
      "maxRetryDuration": "MAX_RETRY_DURATION",
      "minBackoff": "MIN_INTERVAL",
      "maxBackoff": "MAX_INTERVAL",
      "maxDoublings": MAX_DOUBLINGS
    },
    "scheduleTime": "SCHEDULE_TIME"
  }
}

Para enviar a solicitação, expanda uma destas opções:

Se a solicitação for bem-sucedida, o corpo da resposta vai conter a instância recém-criada do recurso Task. 

{
  "name": "projects/PROJECT_ID/locations/REGION/queues/QUEUE_ID/tasks/TASK_ID",
  "httpRequest": {
    "url": "URL",
    "httpMethod": "POST",
    "headers": {
      "User-Agent": "Google-Cloud-Tasks"
    },
    "oidcToken": {
      "serviceAccountEmail": "SERVICE_ACCOUNT_EMAIL",
      "audience": "URL"
    }
  },
  "retryConfig": {
    "maxAttempts": MAX_ATTEMPTS,
    "maxRetryDuration": "MAX_RETRY_DURATION",
    "minBackoff": "MIN_INTERVAL",
    "maxBackoff": "MAX_INTERVAL",
    "maxDoublings": MAX_DOUBLINGS
  },
  "scheduleTime": "SCHEDULE_TIME",
  "createTime": "2026-04-30T19:11:50Z",
  "dispatchDeadline": "600s",
  "view": "BASIC"
}

A seguir