This page provides instructions for migrating from the App Engine Task Queue REST API (v1) to the new Cloud Tasks API (v2) version. Note that Task Queue itself is now named Cloud Tasks, and the new v2 version of the API is now named Cloud Tasks API (v2).
Queues that have been accessed through the Task Queue REST API (v1) are still accessible via the new v2 version.
Before you begin
- Sign up for the Cloud Tasks alpha.
- Enable the Cloud Tasks API for your projects.
Creating and managing queues
With Cloud Tasks API (v2) you can continue to create and manage your queues using the same
queue.yaml
/queue.xml
configuration file you used with the Task Queue REST API (v1). Deploying such files requires the same IAM roles that were previously required.
Managing access to queues
In the v1 API, you restricted access to queues by:
- listing user email addresses in the
queue.yaml
/queue.xml
configuration file - assigning those email addresses
user
orwriter
roles
In the v2 API, you manage queue access through IAM permissions.
The table below maps the Task Queue REST API (v1) permissions to the equivalent new IAM permissions used by Cloud Tasks API (v2):
v1 role | v1 API permissions | v2 (Cloud Tasks) IAM role | v2 (Cloud Tasks) IAM permissions |
---|---|---|---|
user_email |
|
Cloud Tasks Admin (cloudtasks.admin) |
|
writer_email | insert tasks | Cloud Tasks Enqueuer (cloudtasks.enqueuer) |
|
Using getStats
The getStats
feature of the Task Queue REST API (v1) is not yet supported in Cloud Tasks API (v2). As a workaround, you can use the existing
QueueStatistics
class available in the App Engine SDK. However, Google does not recommend using
the results of either getStats
or QueueStatistics
as the basis of
programmatic decision-making in your code, because these methods return only
approximations and even these approximations are subject to delay.
Resources: new API endpoint URLs and bodies
You must migrate your code from using the v1 API resources to using the equivalent v2 API resources:
- Replace the v1 endpoint URLs with the new v2 URLs.
- Adapt to the request and response bodies used by v2.
Note that your queue location-id
is now part of the path in Cloud Tasks API (v2). This is the location where your App Engine App is executing. You can see it at the top right of your App Engine dashboard in the GCP Console.
Migrating queue resources
The following table shows the new endpoints for queues. You should replace the v1 API endpoint URLs in your codebase with the new v2 API endpoint URLS.
v1 queue endpoint URIs are relative to https://www.googleapis.com/taskqueue/v1beta2/projects |
v2 queue endpoint URIs are relative to https://cloudtasks.googleapis.com/v2beta2/projects |
---|---|
GET /PROJECT_ID/taskqueues/QUEUE_ID |
GET /PROJECT_ID/locations/LOCATION_ID/queues/QUEUE_ID
|
Migrating task resources
The following table shows the changed endpoints for tasks types.
Method | v1 task endpoints URIs are relative to https://www.googleapis.com/taskqueue/v1beta2/projects |
v2 task endpoints URIs are relative to https://cloudtasks.googleapis.com/v2beta2/projects |
---|---|---|
delete | DELETE /PROJECT_ID/taskqueues/QUEUE_ID/tasks/TASK_ID |
After a lease, you should now use POST to acknowledge instead of DELETE.
POST /PROJECT_ID/locations/LOCATION_ID/queues/QUEUE_ID/tasks/TASK_ID:acknowledge |
get | GET /PROJECT_ID/taskqueues/QUEUE_ID/tasks/TASK_ID | GET /PROJECT_ID/locations/LOCATION_ID/queues/QUEUE_ID/tasks/TASK_ID |
insert/create | POST /PROJECT_ID/taskqueues/QUEUE_ID/tasks | POST /PROJECT_ID/locations/LOCATION_ID/queues/QUEUE_ID/tasks |
lease | POST /PROJECT_ID/taskqueues/QUEUE_ID/tasks/lease | POST /PROJECT_ID/locations/LOCATION_ID/queues/QUEUE_ID/tasks:lease |
list | GET /PROJECT_ID/taskqueues/QUEUE_ID/tasks | GET /PROJECT_ID/locations/LOCATION_ID/queues/QUEUE_ID/tasks |
patch or update / renewLease or cancelLease |
PATCH /PROJECT_ID/taskqueues/QUEUE_ID/tasks/TASK_ID POST /PROJECT_ID/taskqueues/QUEUE_ID/tasks/TASK_ID |
POST /PROJECT_ID/locations/LOCATION_ID/queues/QUEUE_ID/tasks/TASK_ID:renewLease POST /PROJECT_ID/locations/LOCATION_ID/queues/QUEUE_ID/tasks/TASK_ID:cancelLease |
Sample Migration
For a GitHub repo sample commit that shows the changes that must be made to migrate from Task Queue REST API (v1) to Cloud Tasks API (v2), see the cloud-tasks-api-migration sample. This sample creates, leases, and acknowledges tasks.
The sample migrates from the v1 API version to the v2 API version in the following ways:
- It updates scopes.
- It updates endpoint URLs.
- It adapts to the new request and response body formats.
Getting migration help
If you run into any trouble migrating your application, and you have a support package, you can get help through your normal support channel.
If you don't have a support package, you can obtain help migrating to the v2 API by participating in the conversations with other Cloud Tasks API v2 alpha testers and the team working on the product on the following private Google Group: