开始使用 Data Portability API

在本快速入门中，您将为自己的账号获取 OAuth 令牌，并向 Data Portability API 端点发送一次性请求。

本快速入门介绍了如何使用 Data Portability API 一次性访问用户数据。如需持续访问用户数据，请参阅使用基于时间的访问权限。如需了解如何对请求应用时间过滤条件，请参阅应用时间过滤条件。

学习内容

在本快速入门中，您将学习如何：

提供有效的 OAuth 令牌，向 InitiatePortabilityArchive 端点发送经过身份验证的请求。响应应包含有效的 job_id。
向 GetPortabilityArchiveState 端点发送经过身份验证的请求。响应应包含有效的作业状态，并且在作业完成后，还应包含已签名的网址。
（可选）使用相同的凭据再次向 InitiatePortabilityArchive 端点发送包含有效 OAuth 令牌的已通过身份验证的请求。这会返回 RESOURCE_EXHAUSTED 错误，旨在突出显示 ResetAuthorization 端点的重要性。
向 ResetAuthorization 端点发送经过身份验证的请求。此请求会撤消所有用户授予的 OAuth 授权范围。
（可选）使用之前使用的 OAuth 令牌向 InitiatePortabilityArchive 端点发送请求。授权重置后，请求应会失败。

前提条件

如需运行本快速入门，您需要满足以下条件：

确认 Data Portability API 是否面向您所在地区的用户提供。如需查看支持的国家/地区列表，请参阅“与第三方分享您的数据副本”页面上的常见问题。
完成 Data Portability API 的设置步骤。
请按照相应步骤为 JavaScript Web 应用配置 OAuth。在生产环境中，您通常会使用其他流程，例如适用于网络服务器应用的 OAuth 流程。为简单起见，本快速入门使用 JavaScript Web 应用流程。
- 创建授权凭据时，请记下您的 OAuth 2.0 客户端 ID 和已获授权的重定向 URI（例如 https://google.com）。您将在本快速入门的后面部分用到这些值。
- 为 Data Portability API 配置范围时，请注意，本快速入门使用的是 myactivity.search 资源组：https://www.googleapis.com/auth/dataportability.myactivity.search。
- 当您选择要允许访问的时长时，本快速入门将使用一次性访问。
获取 OAuth 令牌。
获取对贵组织拥有或控制的账号的访问权限。本快速入门将导出此账号的搜索活动数据。

获取 OAuth 令牌

在本快速入门中，您将发送授权请求，以使用网址获取 OAuth 令牌。此流程使用 JavaScript Web 应用的流程。此流程不会返回刷新令牌。

对于正式版应用，您通常会使用 OAuth 流程获取刷新令牌，以便按需生成访问令牌。例如，服务器端 Web 应用的流程。

如需获取 OAuth 令牌，请执行以下操作：

构建如下所示的网址。
```
https://accounts.google.com/o/oauth2/v2/auth?
client_id=client_id&
redirect_uri=redirect_uri&
response_type=token&
scope=https://www.googleapis.com/auth/dataportability.myactivity.search&
state=developer-specified-value
```
在网址中：
- client_id 是您的 OAuth 客户端 ID。
- redirect_uri 是您的已获授权的重定向 URI；例如 https://google.com。
请注意，本快速入门的网址中使用的范围是搜索 activity 范围。您还可以使用 YouTube 活动范围，或同时使用这两个范围。

警告：请勿将 Data Portability API 权限范围与其他类型的权限范围混用，一次使用过多权限范围，或添加之前授予的权限范围，否则会导致错误。如需了解详情，请参阅范围限制。
将该网址粘贴到浏览器的地址栏，然后按照 OAuth 流程中的步骤操作。在此流程中，您需要登录您在本快速入门中使用的、由贵组织拥有或控制的账号。

这是同意 OAuth 权限范围的账号。意见征求界面应如下所示（您屏幕中的文字可能与此图片中的文字不同）：
选择要授予访问权限的范围，以及授予对账号数据的访问权限的时长（一次、30 天或 180 天）。对于本快速入门，请选择仅一次。
在您授予意见征求同意并选择访问时长后，系统应会将您转到重定向 URI（https://google.com）。地址栏中生成的网址包含 OAuth 访问令牌。

例如，如果用户账号向 dataportability.myactivity.search 范围授予 OAuth 访问权限，则生成的网址如下所示：
```
https://google.com/#state=developer-specified-value&access_token=your_OAuth_token&token_type=Bearer&expires_in=3599&scope=https://www.googleapis.com/auth/dataportability.myactivity.search
```
在网址中，your_OAuth_token 是表示令牌的字符串。

重要提示：您的 OAuth 访问令牌将在 1 小时后过期。如果您需要生成新令牌，请按照上一步中的步骤操作。
如需验证 OAuth 令牌，请将以下网址粘贴到浏览器中：
```
https://www.googleapis.com/oauth2/v3/tokeninfo?access_token=your_OAuth_token
```
响应应如下所示：
```
{
  "azp": <your_azp_value>,
  "aud": <your_aud_value>,
  "scope": "https://www.googleapis.com/auth/dataportability.myactivity.search",
  "exp": "1694210968",
  "expires_in": "3334",
  "access_type": "online"
}
```
您无需 azp 或 aud 字段即可发出请求。azp 字段表示授权呈现方的 client_id，aud 字段用于标识此令牌的目标受众群体，该受众群体将等于应用的某个客户端 ID。

注意：您还可以通过发出 HTTP GET 请求来验证令牌。
收集您的 OAuth 令牌和 API 密钥。您需要这些信息才能调用 Data Portability API。

向端点发送请求

在本快速入门中，您将使用 curl 命令调用 Data Portability API 端点。这些命令需要您之前收集的 OAuth 令牌和 API 密钥。

如需调用 Data Portability API，请执行以下操作：

首先，您需要向 InitiatePortabilityArchive 端点发送经过身份验证的请求。此请求会启动归档作业。

运行以下 curl 命令：
```
curl -H 'Authorization: Bearer your_OAuth_token' -X POST \
-H "Content-Type: application/json; charset=utf-8" \
--data '{"resources":["myactivity.search"]}' \
https://dataportability.googleapis.com/v1/portabilityArchive:initiate
```
在此命令中：
- your_OAuth_token 是您的 OAuth 令牌。
警告： resources 参数应仅包含已获授权访问的 OAuth 范围。在此示例中，系统仅授予了 myactivity.search。如果您添加其他资源组，系统会返回错误。如需了解详情，请参阅范围限制。

InitiatePortabilityArchive 请求会返回 job_id 和 accessType。作业 ID 用于检索数据归档的状态，而访问类型决定了您是否已获授对数据的一时性访问权限或基于时间的访问权限。在本快速入门中，您应该拥有一次性访问权限。
```
{
  'archiveJobId': '<your_job_id>'
  'accessType': 'ACCESS_TYPE_ONE_TIME'
}
```
如果您未能提供有效的 OAuth 令牌，系统会返回以下错误消息：
```
Request had invalid authentication credentials. Expected OAuth 2.0 access
token, login cookie or other valid authentication credential. See
https://developers.google.com/identity/sign-in/web/devconsole-project.
```
接下来，您向 GetPortabilityArchiveState 端点发送经过身份验证的请求，以检索归档作业的状态。

运行以下 curl 命令：
```
curl -H 'Authorization: Bearer your_OAuth_token' -X GET \
-H "Content-Type: application/json; charset=utf-8" \
https://dataportability.googleapis.com/v1/archiveJobs/your_job_id/portabilityArchiveState
```
在此命令中：
- your_OAuth_token 是您的 OAuth 令牌。
- your_job_id 是 InitiatePortabilityArchive 请求返回的作业 ID。
响应基于作业的状态。如果作业未完成，响应会提供当前状态。您应定期向此端点发送请求，直到作业完成为止。
```
{
  "state": "IN_PROGRESS"
}
```
如果作业已完成，响应将包含状态以及一个或多个用于下载数据归档文件的已签名网址。
```
{
  "state": "COMPLETE",
  "urls": [
    "<signed_url>"
  ]
}
```
将已签名的网址粘贴到浏览器中，以下载数据归档文件。您应检查归档内容，确保其中包含预期的搜索活动数据。

注意：完成归档作业所需的时间取决于归档文件的大小。最长时长为 7 天。
注意：如果您在响应中收到 FAILED 状态，可以使用 RetryPortabilityArchive 方法重试导出。

（可选）重复上一个命令，将经过身份验证的请求发送到 InitiatePortabilityArchive 端点。

curl -H 'Authorization: Bearer your_OAuth_token' -X POST \
-H "Content-Type: application/json; charset=utf-8" \
--data '{"resources":["myactivity.search"]}' \
https://dataportability.googleapis.com/v1/portabilityArchive:initiate

在此命令中：

your_OAuth_token 是您的 OAuth 令牌。

响应应指明此用户已耗尽对 myactivity.search 资源的一次性同意。

...
"error": {
    "code": 429,
    "message": "Requested resources have already been exported. Please call ResetAuthorization and re-obtain consent before trying again.",
    "status": "RESOURCE_EXHAUSTED",
    "details": [
      {
        "@type": "type.googleapis.com/google.rpc.ErrorInfo",
        "reason": "RESOURCE_EXHAUSTED_ONE_TIME",
        "domain": "dataportability.googleapis.com"
  "metadata": {
    "previous_job_ids": "{previous_job_ids}"
    "access_type": "ACCESS_TYPE_ONE_TIME"
...

向 ResetAuthorization 端点发送经过身份验证的请求。此请求会撤消所有用户授予的 OAuth 范围，并允许您针对已使用的资源组调用 InitiatePortabilityArchive。
```
curl -H 'Authorization: Bearer your_OAuth_token' -X POST \
-H "Content-Type: application/json; charset=utf-8" \
https://dataportability.googleapis.com/v1/authorization:reset
```
在此命令中：
- your_OAuth_token 是您的 OAuth 令牌。
此命令会返回空响应。

（可选）重置授权后，向 InitiatePortabilityArchive 端点发送另一个请求。使用您之前所用的 curl 命令。

curl -H 'Authorization: Bearer your_OAuth_token' -X POST \
-H "Content-Type: application/json; charset=utf-8" \
--data '{"resources":["myactivity.search"]}' \
https://dataportability.googleapis.com/v1/portabilityArchive:initiate

在此命令中：

your_OAuth_token 是您的 OAuth 令牌。

由于您提供的 OAuth 令牌已被撤消，因此响应应返回错误。

...
  "error": {     
    "code": 401,    
        "message": "Request had invalid authentication credentials. Expected
        OAuth 2 access token, login cookie or other valid authentication
        credential. See https://developers.google.com/identity/sign-in/web/devconsole-project.",
        "status": "UNAUTHENTICATED"
  }