Migrating from v1 to v2

Access to v1 of the Task Queue REST API (alpha) is no longer available as of February 20, 2018. See the Feature Deprecations page for more information.

A new version of the API is available, and as a part of the release, the name has been changed to the Cloud Tasks API (alpha). To use Cloud Tasks, you must apply to be whitelisted. After you are whitelisted, you can also use the Cloud Tasks API documentation.

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.

Important: If you manage Task Queues using the built-in App Engine SDK Task Queue API instead of the Task Queue REST API (v1) (Python, Java, Go, or PHP), you don't need to migrate and you can stop reading this document.

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
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.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
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

Important: when you make a lease request in Cloud Tasks API (v2), you must set the responseView field to Task.View.FULL in order to receive the task payload. Note also that some parameters in the v2 API, such as the number of tasks to lease, or the lease duration, should now be sent in the request body instead of path parameters.

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:

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