开始使用 Data Portability API

在本快速入门中，您将获取帐号的 OAuth 令牌，并向 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。在生产环境中，您通常会使用其他流程，例如适用于 Web 服务器应用的 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 令牌，请按以下步骤操作：

  1. 编写如下网址。

    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&
include_granted_scopes=true&
state=developer-specified-value

    在以下网址中：

    • client_id 是您的 OAuth 客户端 ID。
    • redirect_uri 是您授权的重定向 URI；例如，https://google.com。

    请注意，本快速入门网址中使用的范围是搜索 activity 范围。您也可以使用 YouTube 活动范围，或者同时使用两个范围。

  2. 将该网址粘贴到浏览器的地址栏中，然后按照 OAuth 流程中的步骤操作。此流程要求您登录您在此快速入门中使用的贵组织拥有或控制的帐号。

    这是同意 OAuth 范围的帐号。同意屏幕应如下所示（屏幕上的文字可能与下图中的文字有所不同）：

    用户同意允许访问搜索活动数据的同意屏幕

  3. 同意后，您应该会被重定向到重定向 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> 是表示令牌的字符串。

  4. 要验证 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"
}

  5. 收集您的 OAuth 令牌和 API 密钥。 您需要使用这些数据来调用 Data Portability API。

向端点发送请求

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

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

  1. 首先，向 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。此作业 ID 用于检索数据归档的状态。

    {
  "archiveJobId": "<your_job_id>"
}

    如果您未能提供有效的 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.

  2. 接下来，您需要向 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。如果作业未完成，响应将提供当前状态。您应该定期向此端点发送请求，直到作业完成。

    {
  "state": "IN_PROGRESS"
}

    如果作业已完成，响应会包含状态以及用于下载数据归档的一个或多个签名网址。

    {
  "state": "COMPLETE",
  "urls": [
    "<signed_url>"
  ]
}

    将签名网址粘贴到浏览器中，即可下载数据归档文件。您应检查归档文件的内容，确保其包含预期的搜索活动数据。

  3. （可选）重复上一条命令，向 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": "Resource has been exhausted (check quota).",
  "status": "RESOURCE_EXHAUSTED"
}

  4. 向 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 令牌。

    此命令会返回空响应。

  5. （可选）重置授权后，向 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"
  }