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. Seu podem ser executadas em qualquer um desses serviços de maneira confiável de maneira
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 têm configurações de roteamento diferentes. Neste caso, você especifica o roteamento no nível da tarefa e não podem usar o roteamento no nível da fila. Essa abordagem usa o métodoCreateTask
.
Criação de tarefa básica (método BufferTask
)
Esta seção discute como criar 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á onde adicionar informações de roteamento ao criar uma tarefa dessa forma, precisa usar o roteamento no nível da fila (caso contrário, a tarefa não terá informações de roteamento). Se sua fila ainda não usar o roteamento no nível de fila, consulte Configure 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 a seguir mostra um exemplo de criação de tarefa usando com o
Método BufferTask
usando 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. para exemplo,GET
ouPOST
.PROJECT_ID
: o ID do seu projeto do Google Cloud. Você pode conseguir isso executando o seguinte no seu 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 por meio da construção do objeto task. 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 opção, você pode passar 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 o
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 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 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 seu nome 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. Para exemplo, para acessar um gerenciador no Cloud Run, conceda o Invocador do Cloud Run. 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 destino HTTP
gerenciador que exija 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. O
conta de serviço usada para autenticação precisa fazer parte do mesmo
projeto em que a fila do Cloud Tasks reside. A solicitação, com o valor-chave
token de cabeçalho, é enviado 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, no Cloud Run ou nas funções do 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 o Application Default Credentials para autenticação ao
usando 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. para exemplo,GET
ouPOST
.PROJECT_ID
: o ID do seu projeto do Google Cloud. Você pode conseguir isso executando 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 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 seus próprios gerenciadores de tarefas 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 sobre o que isso implica, consulte OpenID Connect, particularmente 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 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 participantes, adicione um endereço de e-mail no seguinte formato:
service-PROJECT_NUMBER@gcp-sa-cloudtasks.iam.gserviceaccount.com
Substitua PROJECT_NUMBER pelo seu projeto do Google Cloud. número
Na seção Atribuir funções, 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 projeto do Google Cloud.PROJECT_NUMBER
: o número do projeto do Google Cloud.
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:
- Nomenclatura: se você optar por especificar um nome para o tarefa, o Cloud Tasks pode usar esse nome para garantir a eliminação de duplicação de tarefas, embora o processamento necessário para isso possa aumentar a latência.
- Programação:você pode programar uma tarefa para outro momento. Compatível apenas
para
CreateTask
(incompatível comBufferTask
) - Configuração de nova tentativa:configure o comportamento de repetição para uma tarefa se ela
falhar. 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.