Criar tarefas do Cloud Tasks

É possível usar o Cloud Tasks para criar itens de trabalho assíncronos chamados tarefas. Este documento demonstra como criar tarefas de destino HTTP e do App Engine.

As tarefas de destino HTTP são solicitações encaminhadas a um worker localizado em qualquer endpoint HTTP genérico com um endereço IP externo, como Cloud Run, Google Kubernetes Engine, Compute Engine ou um servidor da Web local.

Para destinos do App Engine, o Cloud Tasks encaminha solicitações de tarefa para um gerenciador no App Engine. Todas as filas que segmentam handlers do App Engine precisam ter um aplicativo do App Engine. Os handlers precisam ser executados na região em que o aplicativo do App Engine é executado. Essa região também serve como o parâmetro REGION para suas solicitações do Cloud Tasks.

É possível criar uma tarefa de destino HTTP das seguintes maneiras:

  • No console do Google Cloud
  • Usando a Google Cloud CLI no terminal ou no Cloud Shell
  • Enviando uma solicitação direta para a API Cloud Tasks

Para saber como adicionar programaticamente uma tarefa de destino HTTP a uma fila do Cloud Tasks, consulte Criar tarefas de destino HTTP de forma programática.

É possível criar uma tarefa do App Engine das seguintes maneiras:

  • Usando a Google Cloud CLI no terminal ou no Cloud Shell
  • Enviando uma solicitação direta para a API Cloud Tasks

Para saber como adicionar programaticamente uma tarefa do App Engine a uma fila do Cloud Tasks, consulte Criar tarefas do App Engine de maneira programática.

Antes de começar

Verifique se você já criou uma fila do Cloud Tasks. Para mais informações, consulte Criar filas do Cloud Tasks.

Criar uma tarefa de destino HTTP

Ao criar uma tarefa, é possível especificar um nome para ela. Se o nome for idêntico ao de uma tarefa atual ou de uma tarefa excluída ou concluída recentemente, a chamada vai falhar. Se você não especificar um nome de tarefa, um ID aleatório e exclusivo será gerado.

Como há um custo de pesquisa extra para identificar nomes de tarefas duplicados, as tarefas criadas com IDs especificados pelo usuário têm uma latência significativamente maior. Recomendamos usar strings hash para o ID da tarefa ou para o prefixo dele. Para mais informações, consulte Deduplicação de tarefas.

Console

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

    Acessar "Filas"

  2. Clique no nome da fila em que você quer adicionar a tarefa.

  3. Clique em Criar tarefa HTTP.

  4. Se quiser, especifique o Nome da tarefa.

  5. Em URL, especifique o URL totalmente qualificado para onde a solicitação será enviada. O caminho precisa começar com http:// ou https://. Por exemplo: https://www.example.com.

  6. Se quiser, especifique o método HTTP a ser usado na solicitação. O padrão é POST.

  7. Opcional: em Corpo da solicitação, forneça os dados do corpo HTTP a serem enviados ao worker que processa a tarefa.

  8. Se quiser, especifique um ou mais cabeçalhos de solicitação HTTP clicando em Adicionar um cabeçalho.

  9. Em Cabeçalho de autenticação, selecione uma das seguintes opções de autorização para especificar como a solicitação enviada ao destino é autenticada ao executar a tarefa:

    • Nenhum: nenhum cabeçalho, para endpoints públicos sem autorização
    • Adicionar token OAuth: geralmente usado para APIs do Google hospedadas em *.googleapis.com
    • Adicionar token OIDC: usado para chamadas de endpoint de Google Cloud e de terceiros, exceto para APIs do Google hospedadas em *.googleapis.com.

  10. Se aplicável, em Conta de serviço, informe o e-mail da conta de serviço que será usado para gerar o 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.

  11. Se quiser, e se aplicável, especifique o Público-alvo para limitar os tipos de ações ou destinatários do token de autorização.

  12. Clique em Criar.

Sua tarefa vai aparecer na página Detalhes da fila.

gcloud

Para criar uma tarefa de destino HTTP e adicioná-la a uma fila existente, use o comando gcloud tasks create-http-task.

gcloud tasks create-http-task \
    --queue=QUEUE_ID \
    --url=URL \
    --location=REGION \
    --project=PROJECT_ID \
    --oidc-service-account-email=SERVICE_ACCOUNT_EMAIL

Substitua:

  • QUEUE_ID: o nome da fila em que a tarefa será adicionada.

  • URL: o URL totalmente qualificado para onde a solicitação será enviada. O caminho precisa começar com http:// ou https://. Por exemplo: https://www.example.com.

  • REGION: opcional. A região em que a fila é implantada, por exemplo, us-central1.

  • PROJECT_ID: opcional. O ID do projeto do Google Cloud em que a tarefa será criada.

  • 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 a flag --oidc-service-account-email por --oauth-service-account-email para especificar o e-mail da conta de serviço.

Depois de criar a tarefa, você vai receber uma mensagem de confirmação com o nome completo do recurso criado.

REST

Para criar uma tarefa de destino HTTP e adicioná-la a uma fila atual, use o método projects.locations.queues.tasks.create.

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.

  • 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"
      }
    },
    "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"
    }
  },
  "scheduleTime": "SCHEDULE_TIME",
  "createTime": "2026-04-30T19:11:50Z",
  "dispatchDeadline": "600s",
  "view": "BASIC"
}

Criar uma tarefa do App Engine

Ao criar uma tarefa, é possível especificar um nome para ela. Se o nome for idêntico ao de uma tarefa atual ou de uma tarefa excluída ou concluída recentemente, a chamada vai falhar. Se você não especificar um nome de tarefa, um ID aleatório e exclusivo será gerado.

Como há um custo de pesquisa extra para identificar nomes de tarefas duplicados, as tarefas criadas com IDs especificados pelo usuário têm uma latência significativamente maior. Recomendamos usar strings hash para o ID da tarefa ou para o prefixo dele. Para mais informações, consulte Deduplicação de tarefas.

gcloud

Para criar uma tarefa do App Engine e adicioná-la a uma fila existente, use o comando gcloud tasks create-app-engine-task.

gcloud tasks create-app-engine-task \
    --queue=QUEUE_ID \
    --relative-uri=RELATIVE_URI \
    --location=REGION \
    --project=PROJECT_ID \
    --routing=KEY:VALUE

Substitua:

  • QUEUE_ID: o nome da fila em que a tarefa será adicionada.
  • RELATIVE_URI: o URI relativo da solicitação. O caminho precisa começar com uma barra (/). Se não for especificado, o caminho raiz será usado (/).
  • REGION: opcional. A região em que a fila é implantada. Se não for especificado, o local do app do App Engine do projeto atual será usado.
  • PROJECT_ID: opcional. O ID do projeto do Google Cloud em que a tarefa será criada.
  • KEY:VALUE: opcional. A rota a ser usada para essa tarefa em que KEY é pelo menos um dos seguintes: service, version ou instance. As chaves ausentes vão usar o roteamento padrão.

Depois de criar a tarefa, você vai receber uma mensagem de confirmação com o nome completo do recurso criado.

REST

Para criar uma tarefa do App Engine e adicioná-la a uma fila, use o método projects.locations.queues.tasks.create.

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.
  • QUEUE_ID: obrigatório. O ID da fila a que a tarefa será adicionada.
  • RELATIVE_URI: obrigatório. O URI relativo da solicitação. O caminho precisa começar com uma barra (/). Se não for especificado, o caminho raiz será usado (/).
  • SERVICE: opcional. O serviço do App Engine que vai processar a tarefa. Por padrão, a tarefa é enviada para o serviço que é o padrão quando a tarefa é tentada.
  • VERSION: opcional. A versão do App Engine que vai processar a tarefa. Por padrão, a tarefa é enviada para a versão que é a padrão quando a tarefa é tentada.
  • 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": {
    "appEngineHttpRequest": {
      "httpMethod": "POST",
      "relativeUri": "RELATIVE_URI",
      "appEngineRouting": {
        "service": "SERVICE",
        "version": "VERSION"
      }
    },
    "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",
  "appEngineHttpRequest": {
    "httpMethod": "POST",
    "relativeUri": "RELATIVE_URI",
    "appEngineRouting": {
      "service": "SERVICE",
      "version": "VERSION",
      "host": "VERSION.SERVICE.PROJECT_ID.appspot.com"
    }
  },
  "scheduleTime": "SCHEDULE_TIME",
  "createTime": "2026-04-30T19:11:50Z",
  "dispatchDeadline": "600s",
  "view": "BASIC"
}

Criar um lote de tarefas

Você pode criar um lote de tarefas de destino e adicioná-lo a uma fila usando o método projects.locations.queues.tasks.batchCreate para criar uma lista de solicitações.

Observe o seguinte:

  • Todas as tarefas precisam ser adicionadas à mesma fila.

  • Há um limite de quantas tarefas podem ser criadas 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 concluídas.

  • Também é possível excluir um lote de tarefas. Para mais informações, consulte Excluir um lote de tarefas de uma fila.

Tarefas HTTP

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 as tarefas serão criadas.
  • 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 as tarefas serão adicionadas.
  • 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.

O corpo da solicitação contém uma lista de solicitações.

Corpo JSON da solicitação:

{
  "requests": [
    {
      "task": {
        "httpRequest": {
          "url": "URL",
          "httpMethod": "POST",
          "oidcToken": {
            "serviceAccountEmail": "SERVICE_ACCOUNT_EMAIL"
          }
        },
        "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 uma instância do recurso Operation. 

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

Tarefas do App Engine

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.
  • QUEUE_ID: obrigatório. O ID da fila a que as tarefas serão adicionadas.
  • RELATIVE_URI: obrigatório. O URI relativo da solicitação. O caminho precisa começar com uma barra (/). Se não for especificado, o caminho raiz será usado (/).
  • SERVICE: opcional. O serviço do App Engine que vai processar a tarefa. Por padrão, a tarefa é enviada para o serviço que é o padrão quando a tarefa é tentada.
  • VERSION: opcional. A versão do App Engine que vai processar a tarefa. Por padrão, a tarefa é enviada para a versão que é a padrão quando a tarefa é tentada.
  • 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.

O corpo da solicitação contém uma lista de solicitações.

Corpo JSON da solicitação:

{
  "requests": [
    {
      "task": {
        "appEngineHttpRequest": {
          "httpMethod": "POST",
          "relativeUri": "RELATIVE_URI",
          "appEngineRouting": {
            "service": "SERVICE",
            "version": "VERSION"
          }
        },
        "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 uma instância do recurso Operation. 

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

A seguir