Call Data Portability API methods

The Data Portability API consists of these methods:

  • portabilityArchive.initiate
  • archiveJobs.getPortabilityArchiveState
  • resetAuthorization
  • archiveJobs.retryPortabilityArchive

portabilityArchive.initiate

You call the portabilityArchive.initiate method to start a new data export job.

When you start an export job to create a data archive, you must request the appropriate resource group and provide an OAuth token with the required scopes for that resource group. The OAuth token is used to authorize the request and to determine which user data is being exported.

For a list of all resource groups supported by a particular service, see the schema reference page for that service.

For example, if you're exporting search activity data, you call InitiatePortabilityArchive(resources = ["myactivity.search"]). The request must have an OAuth token attached with the search OAuth scope: https://www.googleapis.com/auth/dataportability.myactivity.search.

Though it is possible to include multiple resource groups in a single InitiatePortabilityArchive call, this is not recommended. You can achieve faster processing by making separate InitiatePortabilityArchive requests for each resource group. Note that when you request multiple resource groups, the attached OAuth token must have all the appropriate scopes attached.

For example, instead of calling InitiatePortabilityArchive(resources = ["myactivity.search","myactivity.youtube"]) to create a data archive for both search and YouTube activity, make these separate calls: InitiatePortabilityArchive(resources = ["myactivity.search"]) and InitiatePortabilityArchive(resources = ["myactivity.youtube"]).

The InitiatePortabilityArchive request returns a job_id. This job ID is used to retrieve the state of the data archive.

archiveJobs.getPortabilityArchiveState

The archiveJobs.getPortabilityArchiveState method is called to retrieve the current state of the data archive export job. When you call getPortabilityArchiveState, you supply the job_id: GetPortabilityArchiveState(job_id). You must also supply an OAuth token with scopes that match the resource groups used in the initiate request.

If the state is COMPLETE, signed Cloud Storage URLs are returned that you can use to download the data. The signed URLs expire after six hours, and the data is available for 14 days.

An archive request can take several minutes, several hours, or even several days to complete depending on the volume of data. You can check the state of the archive every five to 60 minutes.

resetAuthorization

The resetAuthorization method does the following:

  • Revokes all user-granted OAuth scopes
  • Allows your application to call InitiatePortabilityArchive for a resource group that you used previously
  • Removes access to previous data archives

When you call resetAuthorization, you must supply an attached OAuth token for the user whose authorization you're resetting.

archiveJobs.retryPortabilityArchive

The archiveJobs.retryPortabilityArchive method is called to retry failed jobs where the archiveJobs.getPortabilityArchiveState method already returned a state of FAILED. This may occur due to a transient failure on the backend. In that case you can retry the export without obtaining a new OAuth token from the user. When you call retryPortabilityArchive you supply the job_id along with a valid OAuth token. The endpoint then tries to create an export for the same resource groups requested in the initial initiatePortabilityArchive request. If successful, this endpoint returns a new job_id that you can use in calls to getPortabilityArchiveState. A failed job can be retried up to three times.

For example:

  1. You call InitiatePortabilityArchive(resources = ["myactivity.search"]), and you receive job_id: 0.

  2. After calling GetPortabilityArchiveState(0), you receive JobSate: FAILED.

  3. You can then call RetryPortabilityArchive(0) to receive job_id: 1 for resources = ["myactivity.search"].

  4. Then, you can continue to make calls to GetPortabilityArchiveState(1).