With this release of HTTP Targets, Cloud Tasks handlers can now be run on any HTTP endpoint with a public IP address, such as Cloud Functions, Cloud Run, GKE, Compute Engine, or even an on-prem web server. Your tasks can be executed on any of these services in a reliable, configurable fashion.
This page demonstrates how to programmatically create HTTP Target tasks and place them in Cloud Tasks queues. When you want to process a task, you must create a new task object and place it on a queue. You specify the service and handler that process the task, and optionally 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. 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.
In general, you create tasks in the form of an HTTP request. Using the Google Cloud Client Libraries and a service account, as the following samples do, can help you manage communication details with the Cloud Tasks server, and make creating tasks easier.
Creating HTTP Target tasks
The following examples create HTTP Target task requests that construct the task, including the URL of the task handler.
C#
Python
Note the requirements.txt
file:
Java
Note the pom.xml
file:
PHP
Note the composer.json
file:
Go
Node.js
Note the package.json
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 wish to use, you can. Just grant it the appropriate roles. These instructions cover creating a new service account specifically for this function.
Visit the Service accounts console page.
If necessary, select the appropriate project.
Click + Create service account.
Give the account a display 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, if you like.
Click Create. You move to the Service account permissions screen.
Click the Select a role dropdown.
Scroll to Cloud Tasks in the left column, and select Cloud Tasks Enqueuer in the right. This gives the service account permission to add tasks to the queue.
Click + Add another role.
Click the new Select a role dropdown.
Scroll to Service Accounts in the left column, and select Service Account User in the right. 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 requires the Cloud Run Invoker role, and so on. You can use the service account you just created or any other service account in your project.
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,
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 request, with the token, is sent, via HTTPS, from the queue to the handler.
You can use either an OIDC token
or an OAuth token. OIDC tokens are signed JSON Web Tokens (JWT) and are used primarily to assert identity and not to provide any implicit authorization
against a resource, unlike OAuth tokens,
which do provide access. OIDC tokens should generally be used for any handler
running on Google Cloud, for example, on Cloud Functions or Cloud Run.
The main exception is for Google APIs hosted on *.googleapis.com
: these APIs
expect an OAuth token. You specify either OIDC or OAuth in the request itself.
The following examples create task requests that also include the creation of a header token. OIDC tokens are used in the examples. To use an OAuth token, replace the OIDC parameter with the language appropriate OAuth parameter in constructing the request.
Python
Note the requirements.txt
file:
Java
Note the pom.xml
file:
Go
Node.js
Note the package.json
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 OIDC 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.
Using the 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
Add
. TheAdd members
screen opens. In the New members dialog box, add an email address of the format:
service-[project-number]@gcp-sa-cloudtasks.iam.gserviceaccount.com
Replacing [project-number] with your project number from above.
From the
Select a role
drop-down, chooseService Management
->Cloud Tasks Service Agent
Click
Save
.
Using gcloud
Find your project number:
gcloud projects describe [project-id] --format='table(projectNumber)'
Replacing [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
Replacing [project-id] with your project ID and [project-number] with the project number from above.
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.