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.

Important: If you do not manage Task Queues using the Task Queue REST API but use the built-in App Engine SDK's Task Queue API (Python, Java, Go, or PHP), then 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

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 Cloud Platform 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

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

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