调用 Data Portability API 方法

Data Portability API 包含以下方法：

  • portabilityArchive.initiate
  • archiveJobs.getPortabilityArchiveState
  • resetAuthorization
  • archiveJobs.retryPortabilityArchive
  • archiveJobs.cancelPortabilityArchive
  • accessType.check

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 方法来检索数据归档导出作业的当前状态。调用 getPortabilityArchiveState 时，您需要提供 job_id：GetPortabilityArchiveState(job_id)。您还必须提供 OAuth 令牌，且令牌的范围与 initiate 请求中使用的资源组相匹配。

如果状态为 COMPLETE，系统会返回经过签名的 Cloud Storage 网址，您可以使用这些网址下载数据。签名网址会在 6 小时后过期，数据的有效期为 14 天。

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

resetAuthorization

resetAuthorization 方法会执行以下操作：

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

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

archiveJobs.retryPortabilityArchive

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

例如：

  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) 发起调用。

archiveJobs.cancelPortabilityArchive

当您持续访问用户数据时，系统会调用 archiveJobs.cancelPortabilityArchive 方法来取消单个作业，而不会撤消现有令牌。如果您不再需要某个作业或资源，并且想要重置作业配额，此操作非常有用。作业必须为 IN_PROGRESS，并且是在使用基于时间的访问权限的情况下创建的，才能取消。

例如，您可以取消针对 myactivity.youtube 和 youtube.public_videos 的正在进行的基于时间的作业，然后仅针对 myactivity.youtube 启动新作业。

accessType.check

借助 accessType.check 方法，您可以在启动作业之前检查 OAuth 令牌是否授予基于时间的访问权限或一次性访问权限。例如，如果用户授予一次性访问权限，您可能希望导出用户的完整历史记录；如果用户授予基于时间的访问权限，您可能只希望导出过去一天的数据。

响应包含两个字段：由请求中使用的 OAuth 令牌授权的一次性和基于时间的数据可移植性资源组 ID 的列表。用户无法在令牌授予中混合使用访问权限类型，但您不一定需要在未来假定这种行为。