Com essa versão de destinos HTTP, os gerenciadores do Cloud Tasks agora podem ser executados em qualquer endpoint HTTP com um endereço IP público, como Cloud Functions, Cloud Run, GKE, Compute Engine ou até mesmo um servidor da Web local. Execute sua tarefas em qualquer um desses serviços de forma confiável e configurável.
Mostraremos nesta página como criar tarefas de HTTP Target de forma programática e colocá-las nas filas do Cloud Tasks.
Se você especificar um nome para a tarefa, o Cloud Tasks poderá usar esse nome para garantir a eliminação de tarefas duplicadas, embora o processamento necessário para isso possa aumentar a latência.
Em geral, as tarefas são criadas na forma de uma solicitação HTTP. Usar as bibliotecas de cliente e uma conta de serviço, como os exemplos a seguir, pode ajudar a gerenciar detalhes de comunicação com o servidor do Cloud Tasks e facilitar a criação de tarefas.
Como criar tarefas de destino HTTP
Para tarefas com destinos HTTP, há duas maneiras de criar tarefas.
Método
BufferTask
:use esse método se a fila estiver configurada para armazenar tarefas em buffer na frente de um serviço. A fila precisa ter roteamento no nível da fila.Método
CreateTask
:é mais complexo. É preciso criar explicitamente um objeto de tarefa. 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.
Método BufferTask
Limitações
Bibliotecas de cliente: o método
BufferTask
não é compatível com bibliotecas de cliente.API RPC: o método
BufferTask
não é compatível com a API RPC.Roteamento no nível da fila:para usar o método
BufferTask
, sua fila precisa 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.
Exemplo de REST
O snippet de código abaixo mostra um exemplo de criação de tarefa usando o
método BufferTask
e 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 para sua solicitação, por exemplo,GET
ouPOST
.PROJECT_ID
: o ID do projeto do Google Cloud. Para isso, execute o seguinte no seu terminal:gcloud config get-value project
LOCATION
: o local da fila.QUEUE_ID
: o ID da fila.
Método CreateTask
Para criar uma tarefa usando o método CreateTask
, crie e defina explicitamente o objeto da tarefa. Especifique o serviço e o gerenciador que processam
a tarefa.
Opcionalmente, você pode transmitir dados específicos da tarefa para o gerenciador. Também é possível ajustar a configuração da tarefa, como agendar um horário no futuro em que ela precisa ser executada ou limitar o número de vezes em que você quer que a tarefa seja repetida se falhar.
Os exemplos a seguir seguem o método CreateTask
para criar uma tarefa usando as bibliotecas de cliente do Cloud Tasks.
C#
Python
Observe o arquivo requirements.txt
:
Java
Observe o arquivo pom.xml
:
PHP
Observe o arquivo composer.json
:
Go
Node.js
Observe o arquivo package.json
:
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. Você também pode adicionar uma descrição da função da conta. Clique em Criar e continuar.
Na seção Conceda a essa conta de serviço acesso ao projeto, clique em Selecionar um papel. Pesquise e selecione Enfileirador do Cloud Tasks. 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 nome dela usando as credenciais da conta de serviço.
Se o gerenciador fizer parte do 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 requer um papel diferente. Por exemplo, para acessar um gerenciador no Cloud Run, é preciso ter o papel Cloud Run Invoker e assim por diante. 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 Task reside. A solicitação, com o token de cabeçalho,
é enviada, por HTTPS, da fila para o gerenciador. É possível usar um token de ID ou token de acesso.
Os tokens de ID geralmente são usados para qualquer gerenciador em execução no Google Cloud,
por exemplo, no Cloud Functions ou no Cloud Run. A principal exceção é para
APIs do Google hospedadas em *.googleapis.com
: essas APIs esperam um token de acesso.
Especifique um token de ID (OIDC)
ou um token de acesso (OAuth)
na própria tarefa.
Método BufferTask
Limitações
Bibliotecas de cliente: o método
BufferTask
não é compatível com bibliotecas de cliente.API RPC: o método
BufferTask
não é compatível com a API RPC.Roteamento no nível da fila:para usar o método
BufferTask
, sua fila precisa 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.
Exemplo de REST com autenticação
Quando você usa o método BufferTask
para criar tarefas, qualquer configuração do OIDC ou OAuth
definida no nível da fila substitui a configuração no nível da tarefa.
Para configurar a autenticação no nível da fila, consulte
Criar filas do Cloud Tasks. No entanto,
é possível autenticar ao criar a tarefa. O exemplo a seguir usa
credenciais padrão do aplicativo para autenticar ao criar uma tarefa:
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 para sua solicitação, por exemplo,GET
ouPOST
.PROJECT_ID
: o ID do projeto do Google Cloud. Para isso, execute o seguinte no seu 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 seu terminal:gcloud auth application-default login
gcloud auth application-default print-access-token
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.
Python
Observe o arquivo requirements.txt
:
Java
Observe o arquivo pom.xml
:
Go
Node.js
Observe o arquivo package.json
:
Como fornecer os próprios gerenciadores de tarefa de HTTP Target
Os gerenciadores de tarefas de HTTP Target são muito parecidos com os gerenciadores de tarefas do App Engine, com as seguintes exceções:
- Tempo limite: em todos os gerenciadores de tarefa de HTTP Target, o tempo limite padrão é de 10 minutos, e máximo de 30 minutos.
- Lógica de autenticação: se você estiver escrevendo seu próprio código no serviço de destino para validar o token, use um token de ID. Para mais informações, consulte OpenID Connect (em inglês), especialmente a seção Como validar um token de ID (em inglês).
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 podem 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.
Como usar o console
- Encontre o número do projeto na página de configurações do projeto do Google 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 principais, adicione um endereço de e-mail no formato:
service-PROJECT_NUMBER@gcp-sa-cloudtasks.iam.gserviceaccount.com
Substitua PROJECT_NUMBER pelo número do projeto acima.
Na seção Atribuir papéis, pesquise e selecione Agente de serviço do Cloud Tasks.
Clique em Salvar.
Como usar a 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 pelo ID do projeto e PROJECT_NUMBER pelo número do projeto acima.
A seguir
- Saiba mais sobre as tarefas de destino HTTP na referência da API RPC.
- Saiba mais sobre as tarefas de HTTP Target na referência da API REST.