Migrating from v1 to v2

This page provides instructions for migrating from the App Engine Task Queue REST API to the new v2 version. Note that the REST API has been renamed to Cloud Tasks API in v2. Cloud Tasks will be the new name for Task Queue.

Existing queues accessed through the Task Queue REST API v1 are still accessible via the new v2 version.

Before you begin

  1. Sign up for the Cloud Tasks alpha.
  2. Enable the Cloud Tasks API for your projects.

Creating and managing queues

No migration is required for creating and managing queues. You can continue using the same queue.yaml/queue.xml configuration file to manage your queues. Deploying such files still requires the same IAM roles as were previously required.

Mapping v1 API ACL roles to new v2 Cloud Task IAM roles

In v1, you restrict access to queues by listing user email addresses in the queue.yaml/queue.xml configuration file and assigning them user or writer roles.

The table below outlines a migration strategy from the API v1 permissions to the new IAM permissions used by v2:

v1 role v1 API permissions v2 (Cloud Tasks) IAM role v2 (Cloud Tasks) IAM permissions
user_email
  • list tasks
  • get tasks
  • lease tasks
  • delete tasks
  • update tasks
Cloud Tasks Admin (cloudtasks.admin)
  • cloudtasks.locations.list
  • cloudtasks.locations.get
  • cloudtasks.queues.list
  • cloudtasks.queues.get
  • cloudtasks.queues.create
  • cloudtasks.queues.update
  • cloudtasks.queues.delete
  • cloudtasks.queues.purge
  • cloudtasks.queues.pause
  • cloudtasks.queues.resume
  • cloudtasks.queues.getIamPolicy
  • cloudtasks.queues.setIamPolicy
  • cloudtasks.tasks.list
  • cloudtasks.tasks.get
  • cloudtasks.tasks.create
  • cloudtasks.tasks.delete
  • cloudtasks.tasks.runNow
  • cloudtasks.tasks.pull
  • cloudtasks.tasks.renewLease
  • cloudtasks.tasks.acknowledge
  • cloudtasks.tasks.cancelLease
  • cloudtasks.tasks.fullView
writer_email insert tasks Cloud Tasks Enqueuer (cloudtasks.enqueuer)
  • cloudtasks.tasks.create
  • cloudtasks.tasks.fullView

Using getStats

The getStats feature of the Task Queue REST API v1 is not yet supported in v2 (Cloud Tasks API). As a workaround, you could 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.

Migrating resources: API endpoint URLs and bodies

You must migrate from the v1 resources to the equivalent v2 resources:

  • Replace the v1 endpoint URLs with the new v2 URLs.
  • Adapt to the request and response bodies used by v2.

Note that the queue location is now part of the path in v2. The location to use is the same as your App Engine location. 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 changed endpoints for queues. You should replace the v1 endpoint URLs in your codebase with the new v2 endpoints URLS.

v1 queue endpoints
URIs are relative to https://www.googleapis.com/taskqueue/v1beta2/projects
v2 queue endpoints
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

Note: For v1 queue resource details, see the resource representation page. For v2 queues resource details, see the API docs.

Migrating task resources

The following table shows the changed endpoints for tasks.

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 acknowledge instead of delete. DELETE /PROJECT_ID/locations/LOCATION_ID/queues/QUEUE_ID/tasks/TASK_ID

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/pull POST /PROJECT_ID/taskqueues/QUEUE_ID/tasks/lease POST /PROJECT_ID/locations/LOCATION_ID/queues/QUEUE_ID/tasks:pull
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

Note: For v1 resource details, see the resource representation page. For v2 resource details, see the Cloud Tasks API documentation.

Sample Migration

For a GitHub repo sample commit that shows the changes that must be made to migrate from v1 of the REST API to v2, see the cloud-tasks-api-migration sample. This sample creates, pulls, and acknowledges tasks.

The sample migrates from the v1 version to the v2 API version in the following ways:

  • updating scopes,
  • updating endpoint URLs,
  • adapting 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 v2 by participating in the conversations with other v2 (Cloud Tasks API) alpha testers and the team working on the product on the following private Google Group:

https://groups.google.com/forum/#!forum/gct-testers

Send feedback about...

App Engine standard environment for Python