Os gerenciadores do Cloud Tasks podem ser executados em qualquer endpoint HTTP com um endereço IP externo, como GKE, Compute Engine ou até mesmo um servidor da Web local. Suas tarefas podem ser executadas em qualquer um desses serviços de forma confiável e configurável.
Esta página demonstra como criar tarefas de destino HTTP básicas de forma programática e colocá-las nas filas do Cloud Tasks.
Para tarefas com destinos HTTP (ao contrário de destinos explícitos do App Engine, que são menos comuns), há duas maneiras de criar tarefas:
Método
BufferTask
:use esse método se a fila estiver configurada para armazenar tarefas na frente de um serviço. A fila precisa ter roteamento no nível da fila. Essa é a melhor abordagem para a maioria dos casos de uso. Essa abordagem usa o métodoBufferTask
.Método
CreateTask
:é mais complexo. É necessário criar um objeto de tarefa de maneira explícita. Use esse método se as tarefas na fila tiverem configurações de roteamento diferentes. Nesse caso, você especifica o roteamento no nível da tarefa e não pode usar o roteamento no nível da fila. Essa abordagem usa o métodoCreateTask
.
Criação de tarefas básicas (método BufferTask
)
Esta seção discute a criação de uma tarefa enviando uma solicitação HTTP. O método
usado é chamado BufferTask
.
Limitações
O método BufferTask
está sujeito às seguintes limitações:
Bibliotecas de cliente:o método
BufferTask
não tem suporte em bibliotecas de cliente.API RPC:o método
BufferTask
não tem suporte na API RPC.Roteamento no nível da tarefa:esse método não oferece suporte ao roteamento no nível da tarefa. Como não há lugar para adicionar informações de roteamento ao criar uma tarefa dessa maneira, é necessário usar o roteamento no nível da fila. Caso contrário, a tarefa não terá informações de roteamento. Se a fila ainda não usa o roteamento no nível da fila, consulte Configurar o roteamento no nível da fila para tarefas HTTP.
Chame o método BufferTask
.
Os exemplos a seguir mostram como criar uma tarefa enviando uma solicitação HTTP POST
ao endpoint buffer
da API Cloud Tasks.
curl
O snippet de código abaixo mostra um exemplo de criação de tarefas usando o
método BufferTask
com curl
:
curl -X HTTP_METHOD\ "https://cloudtasks.googleapis.com/v2/projects/PROJECT_ID/locations/LOCATION/queues/QUEUE_ID/tasks:buffer" \
Substitua:
HTTP_METHOD
: o método HTTP da solicitação, por exemplo,GET
ouPOST
.PROJECT_ID
: o ID do projeto Google Cloud . Para isso, execute o seguinte no terminal:gcloud config get-value project
LOCATION
: o local da fila.QUEUE_ID
: o ID da fila.
Python
Criação de tarefas avançadas (método CreateTask
)
Esta seção discute a criação de uma tarefa construindo o objeto da tarefa. Você usa
o método CreateTask
.
Ao criar uma tarefa usando o método CreateTask
, você cria e
define explicitamente o objeto da tarefa. É necessário especificar o serviço e o gerenciador que processam
a tarefa.
Como alternativa, é possível transmitir dados específicos da tarefa para o gerenciador. Também é possível ajustar a configuração da tarefa, como agendar um horário para que ela seja executada ou limitar o número de vezes que a tarefa será repetida se falhar. Consulte Configuração avançada.
Os exemplos a seguir chamam o método CreateTask
para criar uma tarefa usando as
bibliotecas de cliente do Cloud Tasks.
C#
Go
Java
Observe o arquivo pom.xml
:
Node.js
Observe o arquivo package.json
:
PHP
Observe o arquivo composer.json
:
Python
Observe o arquivo requirements.txt
:
Ruby
Como configurar contas de serviço para autenticação do gerenciador de destino HTTP
O Cloud Tasks pode chamar gerenciadores de destino HTTP que exigem autenticação se você tiver uma conta de serviço com as credenciais apropriadas para acessar o gerenciador.
Se você tiver uma conta de serviço atual que queira usar, é possível. Apenas conceda a ela os papéis apropriados. Estas instruções abrangem a criação de uma nova conta de serviço especificamente para essa função. A conta de serviço nova ou atual usada para a autenticação do Cloud Tasks precisa estar no mesmo projeto que as filas do Cloud Tasks.
No Console do Google Cloud, acesse a página Contas de serviço.
Se necessário, selecione o projeto apropriado.
Clique em Criar conta de serviço.
Na seção Detalhes da conta de serviço, dê um nome à conta. O console cria um nome de conta de e-mail relacionado para a conta. É assim que você faz referência à conta. Também é possível adicionar uma descrição da finalidade da conta. Clique em Criar e continuar.
Na seção Conceder acesso a essa conta de serviço ao projeto, clique em Selecionar uma função. Pesquise e selecione Cloud Tasks Enqueuer. Esse papel concede à conta de serviço permissão para adicionar tarefas à fila.
Clique em Adicionar outro papel.
Clique em Selecionar papel. Pesquise e selecione Usuário da conta de serviço. Esse papel permite que a conta de serviço autorize a fila a criar tokens em seu nome usando as credenciais da conta de serviço.
Se o gerenciador fizer parte de Google Cloud, conceda à conta de serviço o papel associado ao acesso ao serviço em que o gerenciador está em execução. Cada serviço no Google Cloud exige um papel diferente. Por exemplo, para acessar um gerenciador no Cloud Run, conceda o papel Cloud Run Invoker. Você pode usar a conta de serviço que acabou de criar ou qualquer outra conta de serviço no projeto.
Clique em Concluído para terminar a criação da conta de serviço.
O próprio Cloud Tasks precisa ter uma conta de serviço que tenha o papel Cloud Tasks Service Agent
concedido. Dessa forma, ele pode gerar tokens de cabeçalho com base nas credenciais associadas à conta de serviço do Cloud Tasks para autenticação com seu destino de gerenciador. Com esse papel, a conta de serviço do Cloud Tasks é criada automaticamente quando você ativa a API Cloud Task, a menos que você a tenha habilitado antes de 19 de março de 2019. Se esse for o caso, você precisa adicionar o papel manualmente.
Como usar tarefas de destino HTTP com tokens de autenticação
Para autenticar entre o Cloud Tasks e um gerenciador de destino HTTP que exige essa autenticação, o Cloud Tasks cria um token de cabeçalho. Esse token é baseado nas credenciais na
conta de serviço Cloud Tasks Enqueuer
, identificada pelo endereço de e-mail. A
conta de serviço usada para autenticação precisa fazer parte do mesmo
projeto em que a fila do Cloud Tasks está. A solicitação, com o
token do cabeçalho, é enviada da fila para o gerenciador por HTTPS. É possível usar
um token de ID
ou um token de acesso.
Os tokens de ID geralmente precisam ser usados em qualquer gerenciador em execução no Google Cloud,
por exemplo, nas funções do Cloud Run ou no Cloud Run. A principal exceção é
para APIs do Google hospedadas em *.googleapis.com
: essas APIs esperam um token de acesso.
É possível configurar a autenticação no nível da fila ou da tarefa. Para configurar a autenticação no nível da fila, consulte Criar filas do Cloud Tasks. Se a autenticação for configurada no nível da fila, essa configuração vai substituir a configuração no nível da tarefa. Para configurar a autenticação no nível da tarefa, especifique um token de ID (OIDC) ou token de acesso (OAuth) na tarefa.
Método BufferTask
Os exemplos a seguir usam credenciais padrão do aplicativo para autenticação ao
usar o método BufferTask
para criar uma tarefa.
curl
curl -X HTTP_METHOD\ "https://cloudtasks.googleapis.com/v2/projects/PROJECT_ID/locations/LOCATION/queues/QUEUE_ID/tasks:buffer" \ -H "Authorization: Bearer ACCESS_TOKEN"
Substitua:
HTTP_METHOD
: o método HTTP da solicitação, por exemplo,GET
ouPOST
.PROJECT_ID
: o ID do projeto Google Cloud . Para isso, execute o seguinte no terminal:gcloud config get-value project
LOCATION
: o local da fila.QUEUE_ID
: o ID da fila.ACCESS_TOKEN
: seu token de acesso. Para isso, execute o seguinte no terminal:gcloud auth application-default login
gcloud auth application-default print-access-token
Python
No exemplo de código abaixo, forneça o valor do token de autenticação.
Método CreateTask
Os exemplos a seguir usam o método CreateTask
com as
bibliotecas de cliente do Cloud Tasks para criar uma tarefa que também
inclui a criação de um token de cabeçalho. Os tokens de ID são usados nos exemplos.
Para usar um token de acesso, substitua o parâmetro OIDC pelo parâmetro OAuth apropriado
da linguagem ao criar a solicitação.
Go
Java
Observe o arquivo pom.xml
:
Node.js
Observe o arquivo package.json
:
Python
Observe o arquivo requirements.txt
:
Como fornecer os próprios gerenciadores de tarefa de destino HTTP
Os gerenciadores de tarefas de HTTP Target são muito parecidos com os gerenciadores de tarefas do App Engine, com as seguintes exceções:
- Tempos limite: para todos os gerenciadores de tarefa de destino HTTP, o tempo limite padrão é de 10 minutos, com um máximo de 30 minutos.
- Lógica de autenticação: ao escrever o próprio código no serviço de destino para validar o token, você precisa usar um token de ID. Para mais informações, consulte OpenID Connect (link em inglês), especialmente a seção Como validar um token de ID.
Cabeçalhos: uma solicitação de destino HTTP tem cabeçalhos definidos pela fila, que contém informações específicas da tarefa que seu gerenciador pode usar. Eles são semelhantes, mas não idênticos, aos cabeçalhos definidos nas solicitações de tarefas do App Engine. Esses cabeçalhos fornecem apenas informações. Eles não devem ser usados como fontes de identidade.
Se esses cabeçalhos estiverem presentes em uma solicitação de usuário externo ao seu aplicativo, eles serão substituídos pelos internos. A única exceção é para solicitações de administradores conectados do aplicativo, que podem definir cabeçalhos para fins de teste.
As solicitações de destino HTTP sempre contêm os seguintes cabeçalhos:
Cabeçalho Descrição X-CloudTasks-QueueName
O nome da fila. X-CloudTasks-TaskName
O nome abreviado da tarefa ou, se nenhum nome foi especificado na criação, um código exclusivo gerado pelo sistema. Esse é o valor my-task-id
no nome completo da tarefa, ou seja, task_name =projects/my-project-id/locations/my-location/queues/my-queue-id/tasks/my-task-id
.X-CloudTasks-TaskRetryCount
O número de novas tentativas para a tarefa. Para a primeira tentativa, esse valor é 0
. Esse número inclui tentativas em que a tarefa falhou devido a códigos de erro 5XX e nunca chegou à fase de execução.X-CloudTasks-TaskExecutionCount
O número total de vezes em que a tarefa recebeu uma resposta do gerenciador. Como o Cloud Tasks exclui a tarefa depois que uma resposta bem-sucedida foi recebida, todas as respostas anteriores do gerenciador falharam. Esse número não inclui falhas devido a códigos de erro 5XX. X-CloudTasks-TaskETA
O horário de agendamento da tarefa, especificado em segundos desde 1º de janeiro de 1970. Além disso, as solicitações do Cloud Tasks podem conter os seguintes cabeçalhos:
Cabeçalho Descrição X-CloudTasks-TaskPreviousResponse
O código de resposta HTTP da tentativa anterior. X-CloudTasks-TaskRetryReason
O motivo para tentar novamente a tarefa.
Como adicionar o papel de Agente de serviço do Cloud Tasks à sua conta de serviço do Cloud Tasks manualmente
Isso é necessário somente se você ativou a API Cloud Tasks antes de 19 de março de 2019.
Console
- Encontre o número do projeto na página de configurações do projeto doGoogle Cloud.
- Copie o número.
- Abra a página do Admin Console do IAM.
- Clique em Conceder acesso. A tela Conceder acesso é aberta.
Na seção Adicionar participantes, adicione um endereço de e-mail no seguinte formato:
service-PROJECT_NUMBER@gcp-sa-cloudtasks.iam.gserviceaccount.com
Substitua PROJECT_NUMBER pelo número do projeto Google Cloud .
Na seção Atribuir papéis, pesquise e selecione Agente de serviço do Cloud Tasks.
Clique em Salvar.
gcloud
Encontre seu número do projeto:
gcloud projects describe PROJECT_ID --format='table(projectNumber)'
Substitua PROJECT_ID pela ID do seu projeto.
Copie o número.
Conceda à conta de serviço do Cloud Tasks o papel
Cloud Tasks Service Agent
, usando o número do projeto que você copiou:gcloud projects add-iam-policy-binding PROJECT_ID --member serviceAccount:service-PROJECT_NUMBER@gcp-sa-cloudtasks.iam.gserviceaccount.com --role roles/cloudtasks.serviceAgent
Substitua:
PROJECT_ID
: o ID do seu Google Cloud projeto.PROJECT_NUMBER
: o número do Google Cloud projeto.
Configuração avançada
É possível configurar vários atributos na tarefa. Para uma lista completa, consulte a definição de recursos da tarefa.
Exemplos de atributos que podem ser personalizados:
- Nomeação:se você especificou um nome para a tarefa, o Cloud Tasks pode usar esse nome para garantir a eliminação da duplicação de tarefas, embora o processamento necessário para isso possa aumentar a latência.
- Programação:é possível programar uma tarefa para um horário futuro. Somente compatível
com
CreateTask
(não compatível comBufferTask
) - Configuração de novas tentativas:configure o comportamento de novas tentativas de uma tarefa em caso de falha. Compatível apenas com
CreateTask
(não é compatível comBufferTask
)
A seguir
- Saiba mais sobre as tarefas de destino HTTP na referência da API RPC.
- Saiba mais sobre as tarefas de destino HTTP na referência da API REST.