Migrating from v1 to v2

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

  1. Sign up for the Cloud Tasks alpha.
  2. 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 or writer 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
  • 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.lease
  • 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 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

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


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:


Was this page helpful? Let us know how we did:

Send feedback about...

App Engine standard environment for Python