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

Ao criar uma tarefa, você pode especificar o número máximo de vezes para repetir uma tarefa com falha, definir um limite de tempo para novas tentativas e controlar o intervalo entre elas usando o método projects.locations.queues.tasks.create. 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 como definir 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 parâmetros, consulte as configurações de RetryConfig para o 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 tentativas ilimitadas, defina 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 repetir uma tarefa com falha, medido a partir da primeira tentativa da tarefa. 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 repetições das tentativas. O valor precisa ser uma string que termine em "s", como 5s.
  • MAX_INTERVAL: opcional. O tempo máximo de espera entre as repetições das 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 falhas será dobrado antes que o aumento se torne constante. O intervalo de repetição de uma tarefa começa em MIN_INTERVAL, depois duplica MAX_DOUBLINGS vezes, aumenta linearmente e, finalmente, 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