Cloud Tasks handlers can be run on any HTTP endpoint with an external IP address such as GKE, Compute Engine, or even an on-premises web server. Your tasks can be executed on any of these services in a reliable, configurable fashion.
This page demonstrates how to programmatically create basic HTTP target tasks and place them in Cloud Tasks queues.
For tasks that have HTTP targets (as opposed to explicit App Engine targets, which are less common), there are two ways to create tasks:
BufferTask
method: Use this method if your queue is set up to buffer tasks in front of a service. The queue must have queue-level routing. For most use cases, this is the best approach. This approach uses theBufferTask
method.CreateTask
method: This is more complex. You must explicitly create a task object. Use this method if the tasks in your queue have different routing configurations. In this case, you specify routing at the task level and cannot use queue-level routing. This approach uses theCreateTask
method.
Basic task creation (BufferTask
method)
This section discusses creating a task by sending an HTTP request. The method
you use is called BufferTask
.
Limitations
The BufferTask
method is subject to the following limitations:
Client libraries: The
BufferTask
method is not supported in client libraries.RPC API: The
BufferTask
method is not supported in the RPC API.Task-level routing: This method does not support task-level routing. Since there is nowhere to add routing information when creating a task this way, you must use queue-level routing (otherwise the task has no routing information). If your queue does not already use queue-level routing, see Configure queue-level routing for HTTP tasks.
Call the BufferTask
method
The following examples show how to create a task by sending an HTTP POST
request to the Cloud Tasks API
buffer
endpoint.
curl
The following code snippet shows an example of task creation using with the
BufferTask
method using curl
:
curl -X HTTP_METHOD\ "https://cloudtasks.googleapis.com/v2/projects/PROJECT_ID/locations/LOCATION/queues/QUEUE_ID/tasks:buffer" \
Replace the following:
HTTP_METHOD
: the HTTP method for your request; for exampleGET
orPOST
.PROJECT_ID
: the ID of your Google Cloud project. You can get this by running the following in your terminal:gcloud config get-value project
LOCATION
: the location of your queue.QUEUE_ID
: the ID of your queue.
Python
Advanced task creation (CreateTask
method)
This section discusses creating a task by constructing the task object. You use
the CreateTask
method.
When you create a task using the CreateTask
method, you explicitly create and
define the task object. You must specify the service and handler that process
the task.
Optionally, you can pass task-specific data along to the handler. You can also fine-tune the configuration for the task, like scheduling a time in the future when it should be executed or limiting the number of times you want the task to be retried if it fails (see Advanced configuration).
The following examples call the CreateTask
method to create a task using the
Cloud Tasks client libraries.
C#
Go
Java
Note the pom.xml
file:
Node.js
Note the package.json
file:
PHP
Note the composer.json
file:
Python
Note the requirements.txt
file:
Ruby
Setting up service accounts for HTTP target handler authentication
Cloud Tasks can call HTTP target handlers that require authentication if you have a service account with the appropriate credentials to access the handler.
If you have a current service account you want to use, you can. Just grant it the appropriate roles. These instructions cover creating a new service account specifically for this function. The existing or new service account used for Cloud Tasks authentication must be in the same project as your Cloud Tasks queues.
In the Google Cloud console, go to the Service accounts page.
If necessary, select the appropriate project.
Click Create service account.
In the Service account details section, give the account a name. The console creates a related email account name for the account. This is how you reference the account. You can also add a description of what the account is for. Click Create and continue.
In the Grant this service account access to project section, click Select a role. Search for and select Cloud Tasks Enqueuer. This role gives the service account permission to add tasks to the queue.
Click + Add another role.
Click Select a role. Search for and select Service Account User. This role allows the service account to authorize the queue to create tokens on its behalf using the service account's credentials.
If your handler is part of Google Cloud, grant the service account the role associated with accessing the service where your handler is running. Each service within Google Cloud requires a different role. For example, to access a handler on Cloud Run, grant the Cloud Run Invoker role. You can use the service account you just created or any other service account in your project.
Click Done to finish creating the service account.
Cloud Tasks itself must have a service account of its own that has the
Cloud Tasks Service Agent
role granted. This is so it can generate header
tokens based on the credentials associated with the Cloud Tasks
service account to authenticate with your handler target. The
Cloud Tasks service account with this role granted is automatically
created when you enable the Cloud Tasks API, unless you enabled it prior
to March 19, 2019, in which case you must add the role manually.
Using HTTP target tasks with authentication tokens
To authenticate between Cloud Tasks and an HTTP target
handler that requires such authentication, Cloud Tasks creates
a header token. This token is based on the credentials in the
Cloud Tasks Enqueuer
service account, identified by its email address. The
service account used for authentication must be part of the same
project where your Cloud Tasks queue resides. The request, with the
header token, is sent from the queue to the handler by HTTPS. You can use either
an ID token
or an access token.
ID tokens should generally be used for any handler running on Google Cloud,
for example, on Cloud Run functions or Cloud Run. The main exception is
for Google APIs hosted on *.googleapis.com
: these APIs expect an access token.
You can configure authentication at the queue level, or at the task level. To configure authentication at the queue level, see Create Cloud Tasks queues. If authentication is configured at the queue level, this configuration overrides configuration at the task level. To configure authentication at the task level, specify either an ID (OIDC) token or access (OAuth) token in the task itself.
BufferTask
method
The following examples use application default credentials to authenticate when
using the BufferTask
method for creating a task.
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"
Replace the following:
HTTP_METHOD
: the HTTP method for your request; for exampleGET
orPOST
.PROJECT_ID
: the ID of your Google Cloud project. You can get this by running the following in your terminal:gcloud config get-value project
LOCATION
: the location of your queue.QUEUE_ID
: the ID of your queue.ACCESS_TOKEN
: your access token. You can get this by running the following in your terminal:gcloud auth application-default login
gcloud auth application-default print-access-token
Python
In the following code sample, provide your authentication token value.
CreateTask
method
The following examples use the CreateTask
method with the
Cloud Tasks client libraries to create a task that also
includes the creation of a header token. ID tokens are used in the examples.
To use an access token, replace the OIDC parameter with the language appropriate
OAuth parameter in constructing the request.
Go
Java
Note the pom.xml
file:
Node.js
Note the package.json
file:
Python
Note the requirements.txt
file:
Providing your own HTTP target task handlers
HTTP Target task handlers are very similar to App Engine task handlers, with the following exceptions:
- Timeouts: for all HTTP target task handlers the default timeout is 10 minutes, with a maximum of 30 minutes.
- Authentication logic: if you are writing your own code in the targeted service to validate the token, you should use an ID token. For more information on what this entails, see OpenID Connect, particularly Validating an ID token.
Headers: an HTTP target request has headers set by the queue, which contain task-specific information your handler can use. These are similar to, but not identical with, the headers set on App Engine task requests. These headers provide information only. They should not be used as sources of identity.
If these headers were present in an external user request to your app, they are replaced by the internal ones. The sole exception is for requests from logged-in administrators of the application, who are allowed to set headers for testing purposes.
HTTP target requests always contain the following headers:
Header Description X-CloudTasks-QueueName
The name of the queue. X-CloudTasks-TaskName
The "short" name of the task, or, if no name was specified at creation, a unique system-generated id. This is the my-task-id
value in the complete task name, ie, task_name =projects/my-project-id/locations/my-location/queues/my-queue-id/tasks/my-task-id
.X-CloudTasks-TaskRetryCount
The number of times this task has been retried. For the first attempt, this value is 0
. This number includes attempts where the task failed due to 5XX error codes and never reached the execution phase.X-CloudTasks-TaskExecutionCount
The total number of times that the task has received a response from the handler. Since Cloud Tasks deletes the task once a successful response has been received, all previous handler responses were failures. This number does not include failures due to 5XX error codes. X-CloudTasks-TaskETA
The schedule time of the task, specified in seconds since January 1st 1970. In addition, requests from Cloud Tasks might contain the following headers:
Header Description X-CloudTasks-TaskPreviousResponse
The HTTP response code from the previous retry. X-CloudTasks-TaskRetryReason
The reason for retrying the task.
Adding the Cloud Tasks Service Agent role to your Cloud Tasks service account manually
This is necessary only if you enabled Cloud Tasks API prior to March 19, 2019.
Console
- Find the project number for your project on the Google Cloud Project Settings Page.
- Copy down the number.
- Open the IAM Admin Console Page.
- Click Grant access. The Grant access screen opens.
In the Add principals section, add an email address of the format:
service-PROJECT_NUMBER@gcp-sa-cloudtasks.iam.gserviceaccount.com
Replace PROJECT_NUMBER with your Google Cloud project number.
In the Assign roles section, search for and select Cloud Tasks Service Agent.
Click Save.
gcloud
Find your project number:
gcloud projects describe PROJECT_ID --format='table(projectNumber)'
Replace PROJECT_ID with your project ID.
Copy down the number.
Grant the Cloud Tasks service account the
Cloud Tasks Service Agent
role, using the project number you copied down:gcloud projects add-iam-policy-binding PROJECT_ID --member serviceAccount:service-PROJECT_NUMBER@gcp-sa-cloudtasks.iam.gserviceaccount.com --role roles/cloudtasks.serviceAgent
Replace the following:
PROJECT_ID
: your Google Cloud project ID.PROJECT_NUMBER
: your Google Cloud project number.
Advanced configuration
There are a number of attributes you can configure in your task. For a full list, see the task resource definition.
Examples of attributes you can customize:
- Naming: If you chose to specify a name for the task, Cloud Tasks can use that name to ensure task deduplication, although the processing necessary for this can add increased latency.
- Scheduling: You can schedule a task at a future time. Only supported
for
CreateTask
(not supported forBufferTask
) - Retry configuration: Configure the retry behavior for a task if the task
fails. Only supported for
CreateTask
(not supported forBufferTask
)
What's next
- Learn more about HTTP target tasks in the RPC API reference.
- Learn more about HTTP target tasks in the REST API reference.