调用 Data Portability API 方法

Data Portability API 包含以下方法：

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

portabilityArchive.initiate

调用 portabilityArchive.initiate 方法来启动新的数据导出作业。

在启动导出作业创建数据归档时，您必须请求相应的资源组，并提供该资源组所需范围的 OAuth 令牌。OAuth 令牌用于向请求授权，并确定要导出哪些用户数据。

如需查看特定服务支持的所有资源组的列表，请参阅该服务的架构参考页面。

例如，如果您要导出搜索活动数据，则可以调用 InitiatePortabilityArchive(resources = ["myactivity.search"])。该请求必须具有搜索 OAuth 范围附加的 OAuth 令牌：https://www.googleapis.com/auth/dataportability.myactivity.search。

虽然在一次 InitiatePortabilityArchive 调用中可以包含多个资源组，但不建议这样做。您可以为每个资源组发出单独的 InitiatePortabilityArchive 请求，从而提高处理速度。请注意，当您请求多个资源组时，附加的 OAuth 令牌必须附加所有适当的范围。

例如，不要调用 InitiatePortabilityArchive(resources = ["myactivity.search","myactivity.youtube"]) 同时为搜索和 YouTube 活动创建数据归档，而是进行以下单独的调用：InitiatePortabilityArchive(resources = ["myactivity.search"]) 和 InitiatePortabilityArchive(resources = ["myactivity.youtube"])。

InitiatePortabilityArchive 请求会返回 job_id。此作业 ID 用于检索数据归档的状态。

archiveJobs.getPortabilityArchiveState

可调用 archiveJobs.getPortabilityArchiveState 方法来检索数据归档导出作业的当前state。当您调用 getPortabilityArchiveState 时，您需要提供 job_id：GetPortabilityArchiveState(job_id)。您还必须提供一个范围与 initiate 请求中使用的资源组相匹配的 OAuth 令牌。

如果状态为 COMPLETE，则返回已签名的 Cloud Storage 网址，您可以使用该网址下载数据。签名网址会在 6 小时后过期，并且数据有效期为 14 天。

归档请求可能需要几分钟、几小时甚至几天才能完成，具体取决于数据量。您可以每 5 到 60 分钟检查一次归档文件的状态。

resetAuthorization

resetAuthorization 方法会执行以下操作：

  • 撤消用户授予的所有 OAuth 范围
  • 允许应用为之前使用的资源组调用 InitiatePortabilityArchive
  • 撤消对之前的数据归档的访问权限

调用 resetAuthorization 时，您必须为要重置其授权的用户提供附加的 OAuth 令牌。

archiveJobs.retryPortabilityArchive

如果作业的 archiveJobs.getPortabilityArchiveState 方法已返回 FAILED 状态，则调用 archiveJobs.retryPortabilityArchive 方法来重试失败的作业。state这可能是由于后端暂时性故障造成的。在这种情况下，您可以重试导出，而无需从用户那里获取新的 OAuth 令牌。当您调用 retryPortabilityArchive 时，您需要提供 job_id 以及有效的 OAuth 令牌。然后，该端点会尝试为初始 initiatePortabilityArchive 请求中请求的同一资源组创建导出内容。如果成功，此端点会返回一个新的 job_id，您可以在调用 getPortabilityArchiveState 时使用它。失败的作业最多可以重试三次。

例如：

  1. 您调用 InitiatePortabilityArchive(resources = ["myactivity.search"])，会收到 job_id: 0。

  2. 调用 GetPortabilityArchiveState(0) 后，您会收到 JobSate: FAILED。

  3. 然后，您可以调用 RetryPortabilityArchive(0) 来接收 resources = ["myactivity.search"] 的 job_id: 1。

  4. 然后，您可以继续调用 GetPortabilityArchiveState(1)。