新的 Data Portability API 功能现已推出，并将于 2025 年 2 月 20 日面向所有用户推出！

此页面由 Cloud Translation API 翻译。

对请求应用时间过滤条件

在本快速入门中，您将为自己的账号获取 OAuth 令牌，并使用时间戳向 Data Portability API 端点发送请求，以过滤导出的数据。

本快速入门介绍了如何将 Data Portability API 与基于时间的访问权限搭配使用，以及如何为受支持的资源应用时间过滤条件。如需详细了解基于时间的用户数据访问权限，请参阅使用基于时间的访问权限。

学习内容

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

向 InitiatePortabilityArchive 端点发送定期的经过身份验证的请求，以便仅导出自上次导出之后的新数据。
向 InitiatePortabilityArchive 端点发送经过身份验证的请求，以便仅导出过去 6 个月内的数据。
向 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。
- 选择要允许访问的时长时，您应选择 30 天，以便测试基于时间的访问权限功能。（时间过滤器也适用于一次性访问权限）。
获取 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 范围。您可以使用支持时间过滤条件的任何镜重。

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

这是同意 OAuth 权限范围的账号。意见征求界面应如下所示（您屏幕中的文字可能与此图片中的文字不同）：
选择要授予访问权限的范围，以及授予对账号数据的访问权限的时长（一次、30 天或 180 天）。在本快速入门中，请选择 30 天。（时间过滤条件也适用于一次性访问权限）。
在您授予同意并确定访问时长后，系统应会将您转到重定向 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 密钥。

上次导出的数据

您可以将时间过滤条件与基于时间的访问权限搭配使用，以导出自上次导出以来的新数据。例如，请考虑作用域 https://www.googleapis.com/auth/dataportability.myactivity.search。

首先，您需要向 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 请求会返回 archiveJobId 和 accessType。作业 ID 用于检索数据归档的状态，而访问类型决定了您是否已获授对数据的一时性访问权限或基于时间的访问权限。对于基于时间的访问权限，您会看到：
```
{
  "archiveJobId": "<your_job_id_1>"
  "accessType": "ACCESS_TYPE_TIME_BASED"
}
```
如果您未能提供有效的 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_1/portabilityArchiveState
```
在此命令中：
- your_OAuth_token 是您的 OAuth 令牌。
- your_job_id_1 是 InitiatePortabilityArchive 请求返回的作业 ID。
响应基于作业的状态。如果作业未完成，响应会提供当前状态。您应定期向此端点发送请求，直到作业完成为止。
```
{
  "state": "IN_PROGRESS"
}
```
如果作业已完成，响应将包含状态以及一个或多个用于下载数据归档文件的已签名网址。此外，还有一个 export_time 字段，表示首次调用 InitiatePortabilityArchive 的时间戳。
```
{
  "state": "COMPLETE",
  "urls": [
    "<signed_url>"
  ]
  "export_time": "<timestamp_of_first_initiate_request>"
}
```
将已签名的网址粘贴到浏览器中，以下载数据归档文件。您应检查归档内容，确保其中包含预期的搜索活动数据。

注意：完成归档作业所需的时间取决于归档文件的大小。最长时长为 7 天。

如果您在响应中收到 FAILED 状态，则可以使用 RetryPortabilityArchive 方法重试导出。

等待至少 24 小时，然后使用第 1 步中的相同命令再次向 InitiatePortabilityArchive 发出请求，但这次使用 export_time 作为 start_time。

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

对于基于时间的访问权限，此操作将返回：

{
  "archiveJobId": "<your_job_id_2>"
  "accessType": "ACCESS_TYPE_TIME_BASED"
}

重复第 2 步，向 GetPortabilityArchiveState 端点发送经过身份验证的请求，以检索归档作业的状态（使用 <your_job_id_2>）。

作业完成后，响应将如下所示：

  {
    "state": "COMPLETE",
    "urls": [
      "signed_urls"
    ],
    "start_time": timestamp_of_first_initiate_request,
    "export_time": timestamp_of_second_initiate_request
  }

验证第二次导出的数据仅包含首次导出后生成的新数据。

过去 6 个月的数据

您还可以使用时间过滤条件，仅导出最新数据，而不是整个语料库。

假设今天的日期为 2024-10-01，并且您想导出过去 6 个月的数据。首先，您向 InitiatePortabilityArchive 端点发送经过身份验证的请求，其中 start_time 为“2024-04-01T00:00:00Z”。

运行以下 curl 命令：

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

对于基于时间的访问权限，此操作将返回：

{
  "archiveJobId": "job_id_1"
  "accessType": "ACCESS_TYPE_TIME_BASED"
}

向 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/job_id_1/portabilityArchiveState

作业完成后，响应将如下所示：

{
  "state": "COMPLETE",
  "urls": [
    "signed_urls"
  ],
  "start_time": "2024-04-01T00:00:00Z",
  "export_time": "2024-10-01T00:00:00Z"
}

请注意，start_time 是第 1 步中指定的 start_time，export_time 是第 1 步中对 InitiatePortabilityArchive 进行调用的时刻的时间戳。

验证导出的数据是否仅包含过去 6 个月内的数据。

特定时间段内的数据

您可以使用时间过滤条件导出特定日期范围内的数据，例如仅导出 2023 年的数据。

首先，您向 InitiatePortabilityArchive 端点发送经过身份验证的请求，其中 start_time 为“2023-01-01T00:00:00Z”，end_time 为“2023-12-31T23:59:59Z”。

运行以下 curl 命令：

curl -H 'Authorization: Bearer your_OAuth_token' -X POST \
-H "Content-Type: application/json; charset=utf-8" \
--data '{"resources":["myactivity.search"],
"start_time": "2023-01-01T00:00:00Z",
"end_time": "2023-12-31T23:59:59Z"}' \
https://dataportability.googleapis.com/v1/portabilityArchive:initiate

对于基于时间的访问权限，此操作将返回：

{
  "archiveJobId": "job_id_1"
  "accessType": "ACCESS_TYPE_TIME_BASED"
}

向 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/job_id_1/portabilityArchiveState

作业完成后，响应将如下所示：

{
  "state": "COMPLETE",
  "urls": [
    "signed_urls"
  ],
  "start_time": "2023-01-01T00:00:00Z",
  "export_time": "2023-12-31T23:59:59Z"
}

请注意，start_time 是第 1 步中指定的 start_time，export_time 等于第 1 步中提供的 end_time。

验证导出的数据是否仅包含 2023 年的数据。

支持的镜重

以下范围支持时间过滤条件：

https://www.googleapis.com/auth/dataportability.myactivity.youtube
https://www.googleapis.com/auth/dataportability.myactivity.maps
https://www.googleapis.com/auth/dataportability.myactivity.search
https://www.googleapis.com/auth/dataportability.myactivity.myadcenter
https://www.googleapis.com/auth/dataportability.myactivity.shopping
https://www.googleapis.com/auth/dataportability.myactivity.play
https://www.googleapis.com/auth/dataportability.chrome.history

注意：混合使用受支持和不受支持镜区的经过时间过滤的请求会导致 INVALID_ARGUMENT 错误，其中包含 The requested resources do not support time filters。