Gerenciar filas e tarefas

O Cloud Tasks permite controlar a execução de cargas de trabalho assíncronas, pausar o processamento de filas e resolver problemas de fluxos de tarefas ativos. É possível configurar e manter suas filas e tarefas usando o console do Google Cloud , a Google Cloud CLI ou a API Cloud Tasks.

Antes de começar

  1. Verifique se você tem uma fila de tarefas do Cloud Tasks. Para mais informações, consulte Criar filas de tarefas do Cloud Tasks.
  2. Verifique se você tem os papéis do Identity and Access Management (IAM) necessários para gerenciar filas de tarefas, como Administrador do Cloud Tasks (roles/cloudtasks.admin), Administrador de fila de tarefas do Cloud Tasks (roles/cloudtasks.queueAdmin) ou Excluidor de tarefas do Cloud Tasks (roles/cloudtasks.taskDeleter).

Excluir uma tarefa de uma fila

É possível excluir uma tarefa se ela estiver agendada ou enviada. Por exemplo, talvez seja necessário excluir uma tarefa que não pode ser concluída, não importa quantas tentativas sejam feitas. Não é possível excluir uma tarefa se ela tiver sido concluída com sucesso ou se tiver esgotado as novas tentativas após falhas consistentes. Uma tarefa será excluída automaticamente se o limite de retenção máxima de tarefas for atingido.

Console

  1. No console do Google Cloud , acesse a página Cloud Tasks > Filas.

    Acessar filas

  2. Clique no nome da fila da tarefa que você quer excluir.

  3. Marque a caixa de seleção da tarefa que você quer excluir.

  4. Clique em Excluir tarefa.

  5. No prompt, clique em Excluir.

gcloud

Exclua uma tarefa usando o comando gcloud tasks delete:

gcloud tasks delete TASK_NAME \
    --queue=QUEUE_ID \
    --location=LOCATION

Substitua:

  • TASK_NAME: o ID ou o nome completo do recurso da tarefa que você quer excluir.
  • QUEUE_ID: o nome da fila a que a tarefa pertence
  • LOCATION: a região em que a fila é implantada, por exemplo, us-central1.

REST

Para excluir uma tarefa, use o método projects.locations.queues.tasks.delete.

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

  • QUEUE_ID: o nome da fila a que a tarefa pertence.
  • TASK_NAME: o nome da tarefa que você quer excluir
  • PROJECT_ID: o ID do projeto do Google Cloud.
  • LOCATION: a região em que a fila está, por exemplo, us-central1

O corpo da solicitação precisa estar vazio.

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

Se a solicitação for concluída, o corpo da resposta estará vazio.

Excluir um lote de tarefas de uma fila

É possível excluir um lote de tarefas de uma fila usando o método projects.locations.queues.tasks.batchDelete para excluir uma lista de nomes de tarefas.

Observe o seguinte:

  • Todas as tarefas precisam ser excluídas da mesma fila.

  • Há um limite de quantas tarefas podem ser excluídas em um único lote. Para mais informações, consulte Cotas e limites.

  • As solicitações em lote, que agregam operações individuais em uma única solicitação, não são atômicas porque é possível que algumas das operações contidas no lote falhem enquanto outras são bem-sucedidas.

  • Só é possível excluir uma tarefa se ela estiver agendada ou enviada. Não é possível excluir uma tarefa se ela tiver sido concluída com sucesso ou se tiver ficado sem novas tentativas após falhas consistentes. Uma tarefa será excluída automaticamente se o limite de retenção máxima de tarefas for atingido.

  • Também é possível criar um lote de tarefas. Para mais informações, consulte Criar um lote de tarefas.

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

  • TASK_NAME: o nome das tarefas a serem excluídas com o seguinte formato: projects/PROJECT_ID/locations/REGION/queues/QUEUE_ID/tasks/TASK_ID
  • PROJECT_ID: o ID do projeto do Google Cloud.
  • REGION: a região em que a fila está, por exemplo, us-central1
  • QUEUE_ID: o nome da fila a que as tarefas pertencem.

O corpo da solicitação contém uma lista de nomes de tarefas.

Corpo JSON da solicitação:

{
  "names": [
    "TASK_NAME"
  ]
}

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

Se funcionar, o corpo da resposta vai ter uma instância de Operation.

{
  "name": "projects/PROJECT_ID/locations/REGION/operations/OPERATION_ID",
  "metadata": {
    "@type": "type.googleapis.com/google.cloud.tasks.v2.BatchDeleteTasksMetadata"
  },
  "done": false
}

Limpar todas as tarefas de uma fila

É possível excluir todas as tarefas de uma fila ao limpá-las. Todas as tarefas criadas antes da chamada de limpeza são excluídas permanentemente. No entanto, as operações de limpeza podem levar até um minuto para entrar em vigor, e as tarefas podem ser enviadas antes que a limpeza seja concluída.

Console

  1. No console do Google Cloud , acesse a página Cloud Tasks > Filas.

    Acessar filas

  2. Clique no nome da fila das tarefas que você quer excluir.

  3. Clique em Limpar fila.

  4. No prompt, clique em Limpar.

gcloud

Limpe uma fila usando o comando gcloud tasks queues purge:

gcloud tasks queues purge QUEUE_ID \
    --location=LOCATION

Substitua:

  • QUEUE_ID: o nome da fila que você quer limpar.
  • LOCATION: a região em que a fila é implantada, por exemplo, us-central1.

REST

Para limpar uma fila, use o método projects.locations.queues.purge.

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

  • QUEUE_ID: o nome da fila que você quer limpar.
  • PROJECT_ID: o ID do projeto do Google Cloud.
  • LOCATION: a região em que a fila é implantada, por exemplo, us-central1

O corpo da solicitação precisa estar vazio.

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

Se houver êxito, o corpo da resposta conterá uma instância de Queue:

{
  "name": "projects/PROJECT_ID/locations/LOCATION/queues/QUEUE_ID",
  "rateLimits": {
    "maxDispatchesPerSecond": 500,
    "maxBurstSize": 100,
    "maxConcurrentDispatches": 1000
  },
  "retryConfig": {
    "maxAttempts": 100,
    "minBackoff": "0.100s",
    "maxBackoff": "3600s",
    "maxDoublings": 16
  },
  "state": "RUNNING",
  "purgeTime": "2025-03-28T13:06:30.110255Z"
}

Pausar ou retomar filas

É possível pausar ou retomar uma fila. Pausar uma fila interrompe a execução e a entrega de tarefas. Ainda é possível criar tarefas e enviá-las ou anexá-las à fila, mas elas não serão processadas até que a fila seja retomada. Quando você retoma uma fila, o Cloud Tasks começa a enviar tarefas em atraso sem uma ordem de execução definida. Se você estiver retomando filas de alto tráfego com um grande backlog, siga as orientações de aumento gradual para evitar a sobrecarga do destino.

Console

  1. No console do Google Cloud , acesse a página Cloud Tasks > Filas.

    Acessar filas

  2. Marque a caixa de seleção da fila que você quer pausar ou retomar.

  3. Para pausar a fila, clique em Pausar fila e em Pausar no prompt.

  4. Para retomar uma fila pausada, clique em Retomar fila.

gcloud

  1. Pause uma fila usando o comando gcloud tasks queues pause:

    gcloud tasks queues pause QUEUE_ID \
        --location=LOCATION

    Substitua:

    • QUEUE_ID: o nome da fila que você quer pausar.
    • LOCATION: a região em que a fila é implantada, por exemplo, us-central1.
  2. Retome uma fila usando o comando gcloud tasks queues resume:

    gcloud tasks queues resume QUEUE_ID \
        --location=LOCATION

REST

  1. Para pausar uma fila, use o método projects.locations.queues.pause.

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

    • QUEUE_ID: o nome da fila que você quer pausar
    • PROJECT_ID: o ID do projeto do Google Cloud.
    • LOCATION: a região em que a fila é implantada, por exemplo, us-central1

    O corpo da solicitação precisa estar vazio.

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

    Se houver êxito, o corpo da resposta conterá uma instância de Queue:

    {
      "name": "projects/PROJECT_ID/locations/LOCATION/queues/QUEUE_ID",
      "rateLimits": {
        "maxDispatchesPerSecond": 500,
        "maxBurstSize": 100,
        "maxConcurrentDispatches": 1000
      },
      "retryConfig": {
        "maxAttempts": 100,
        "minBackoff": "0.100s",
        "maxBackoff": "3600s",
        "maxDoublings": 16
      },
      "state": "PAUSED"
    }
    

  2. Para retomar uma fila, use o método projects.locations.queues.resume.

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

    • QUEUE_ID: o nome da fila que você quer retomar.
    • PROJECT_ID: o ID do projeto do Google Cloud.
    • LOCATION: a região em que a fila é implantada, por exemplo, us-central1

    O corpo da solicitação precisa estar vazio.

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

    Se houver êxito, o corpo da resposta conterá uma instância de Queue:

    {
      "name": "projects/PROJECT_ID/locations/LOCATION/queues/QUEUE_ID",
      "rateLimits": {
        "maxDispatchesPerSecond": 500,
        "maxBurstSize": 100,
        "maxConcurrentDispatches": 1000
      },
      "retryConfig": {
        "maxAttempts": 100,
        "minBackoff": "0.100s",
        "maxBackoff": "3600s",
        "maxDoublings": 16
      },
      "state": "RUNNING"
    }
    

Listar filas

É possível listar filas. Ao listar filas, alguns detalhes de limitação de taxa e parâmetro de repetição são retornados. Os seguintes campos são equivalentes:

  • Taxa máxima (Console), MAX_RATE (gcloud), maxDispatchesPerSecond (REST)
  • Máximo simultâneo (Console), MAX_NUM_OF_TASKS (gcloud), maxConcurrentDispatches (REST)

Console

  1. No console do Google Cloud , acesse a página Cloud Tasks > Filas.

    Acessar filas

    Todas as filas no projeto do Google Cloud serão listadas.

  2. Para mais detalhes, clique no nome de uma fila e, em seguida, na guia Configuração.

    Os detalhes da limitação de taxa e do parâmetro de nova tentativa são exibidos.

gcloud

Liste as filas usando o comando gcloud tasks queues list:

gcloud tasks queues list \
    --location=LOCATION

Substitua LOCATION pela região em que a fila está implantada, por exemplo, us-central1. Se um local não for especificado, o local do aplicativo do App Engine do projeto do Google Cloud será usado, se houver. Caso contrário, será necessário especificar um local.

A saída será semelhante a esta:

QUEUE_NAME: my-queue
STATE: PAUSED
MAX_NUM_OF_TASKS: 1000
MAX_RATE (/sec): 500.0
MAX_ATTEMPTS: 100
...

REST

Para listar filas, use o método projects.locations.queues.list.

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

  • PROJECT_ID: o ID do projeto do Google Cloud.
  • LOCATION: a região em que as filas são criadas, por exemplo, us-central1.

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

Se bem-sucedido, o corpo da resposta conterá instâncias de recursos Queue e a resposta será semelhante a esta:

{
  "queues": [
    {
      "name": "projects/PROJECT_ID/locations/LOCATION/queues/QUEUE_ID",
      "rateLimits": {
        "maxDispatchesPerSecond": 500,
        "maxBurstSize": 100,
        "maxConcurrentDispatches": 1000
      },
      "retryConfig": {
        "maxAttempts": 100,
        "minBackoff": "0.100s",
        "maxBackoff": "3600s",
        "maxDoublings": 16
      },
      "state": "PAUSED",
      "purgeTime": "2025-03-28T13:37:32.292552Z"
    },
    ...
  ],
  "nextPageToken": "CjQKCHppcHBlcjIAEgwI9-GExAYQ_oDc1AMaGioLeWlrZXMtYWdhaW4yC3VzLWNlbnRyYWwx"
}

Excluir filas

É possível excluir qualquer fila quando ela não for mais necessária, exceto a fila default do App Engine. Depois de excluir uma fila, aguarde três dias antes de recriá-la com o mesmo nome. Esse período de espera se aplica a filas excluídas por qualquer interface, incluindo o console do Google Cloud , a CLI gcloud, a API REST ou RPC ou o Terraform. Isso evita comportamentos inesperados em tarefas que estão sendo executadas no momento da exclusão e evita falhas de processo interno durante o ciclo de exclusão e recriação.

Durante essa janela de tombstone de até três dias, uma solicitação de criação de fila pode parecer bem-sucedida sem recriar a fila. Para confirmar que uma fila com o mesmo nome foi recriada, recupere-a usando o comando gcloud tasks queues describe ou o método projects.locations.queues.get. Uma resposta bem-sucedida (200 OK) confirma que a fila foi recriada.

Para limpar tarefas, modificar configurações de fila ou gerenciar filas em pipelines de CI/CD sem perder a fila ou acionar o período de espera de três dias, use as seguintes alternativas em vez de excluir e recriar uma fila:

Para excluir uma fila, use o Google Cloud console, a CLI gcloud ou a API Cloud Tasks:

Console

  1. No console do Google Cloud , acesse a página Cloud Tasks > Filas.

    Acessar filas

  2. Marque a caixa de seleção da fila que você quer excluir.

  3. Clique em Excluir fila.

  4. No prompt, insira o nome da fila e clique em Confirmar.

gcloud

Exclua uma fila usando o comando gcloud tasks queues delete:

gcloud tasks queues delete QUEUE_ID \
    --location=LOCATION

Substitua:

  • QUEUE_ID: o ID ou identificador totalmente qualificado da fila que você quer excluir.
  • LOCATION: a região em que a fila é implantada, por exemplo, us-central1.

A CLI gcloud solicita confirmação antes de excluir a fila, a menos que você transmita a flag --quiet.

REST

Para excluir uma fila, use o método projects.locations.queues.delete.

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

  • QUEUE_ID: o nome da fila que você quer excluir.
  • PROJECT_ID: o ID do projeto do Google Cloud.
  • LOCATION: a região em que a fila é implantada, por exemplo, us-central1

O corpo da solicitação precisa estar vazio.

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

Se a solicitação for concluída, o corpo da resposta estará vazio.

A seguir