使用基于时间的访问权限

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

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

学习内容

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

提供有效的 OAuth 令牌，向 InitiatePortabilityArchive 端点发送经过身份验证的请求。响应应包含有效的 job_id。
向 GetPortabilityArchiveState 端点发送经过身份验证的请求。响应应包含有效的作业状态，并且在作业完成后，还应包含已签名的网址。
使用相同的凭据再次向 InitiatePortabilityArchive 端点发送包含有效 OAuth 令牌的已通过身份验证的请求。如果在初始请求后的 24 小时内发出请求，则会返回 FAILED_PRECONDITION 错误。

前提条件

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

确认 Data Portability API 是否面向您所在地区的用户提供。如需查看支持的国家/地区列表，请参阅“与第三方分享您的数据副本”页面上的常见问题。
完成 Data Portability API 的设置步骤。
请按照相应步骤为服务器端 Web 应用配置 OAuth。
- 创建授权凭据时，请记下您的 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 令牌。此流程使用服务器端 Web 应用的流程。此流程会生成一个刷新令牌，您可以将其用于后续导出。

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

构建如下所示的网址。
```
https://accounts.google.com/o/oauth2/v2/auth?
client_id=client_id&
redirect_uri=redirect_uri&
response_type=code&
access_type=offline&
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 天）。在本快速入门中，请选择 30 天。
在您授予同意并确定访问时长后，系统应会将您转到重定向 URI（https://google.com）。地址栏中生成的网址包含一个授权代码，您可以在下一步中将其换取 OAuth 令牌。

例如，如果用户账号向 dataportability.myactivity.search 范围授予 OAuth 访问权限，则生成的网址如下所示：
```
https://google.com/#state=developer-specified-value&code=your_auth_code&scope=https://www.googleapis.com/auth/dataportability.myactivity.search
```
如需将授权代码换成访问令牌，请使用以下参数调用 oauth 令牌端点：
```
curl https://oauth2.googleapis.com/token\
-H 'Content-Type: application/x-www-form-urlencoded' -X POST\
-d 'code=your_auth_code&\
redirect_uri=redirect_uri\
client_id=client_id&\
client_secret=client_secret&\
grant_type=authorization_code'
```
响应应如下所示：
```
{
  "access_token": your_OAuth_token,
  "expires_in": 3920,
  "token_type": "Bearer",
  "scope": "https://www.googleapis.com/auth/dataportability.myactivity.search",
  "refresh_token": your_refresh_token,
  "refresh_token_expires_in": 2591999
}
```
在网址中，your_OAuth_token 是表示令牌的字符串。

refresh_token_expires_in 字段以秒为单位，反映用户选择的访问权限时长是 30 天（2592000 秒）还是 180 天（15552000 秒）。如果您的应用的发布状态为测试，则无论用户选择哪种选项，您都将获得 7 天（604800 秒）的访问权限。

重要提示：您的 OAuth 访问令牌将在一小时后过期 - 请存储您的刷新令牌，以便稍后将其交换为新的访问令牌。
如需验证 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_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/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. You can initiate another export after #{timestamp_after_24hrs}.",
    "status": "RESOURCE_EXHAUSTED",
    "details": [
      {
        "@type": "type.googleapis.com/google.rpc.ErrorInfo",
        "reason": "RESOURCE_EXHAUSTED_TIME_BASED",
        "domain": "dataportability.googleapis.com"
  "metadata": {
    "previous_job_ids": "#{previous_job_ids}"
    "access_type": "ACCESS_TYPE_TIME_BASED"
    "timestamp_after_24hrs": "#{timestamp_after_24hrs}"
...

24 小时后，您可以请求重新导出，但首先必须将刷新令牌换成新的访问令牌。

curl https://oauth2.googleapis.com/token\
-H 'Content-Type: application/x-www-form-urlencoded' -X POST\
-d 'refresh_token=your_refresh_token&\
client_id=client_id&\
client_secret=client_secret&\
grant_type=refresh_token'

响应应如下所示：

{
  "access_token": your_OAuth_token,
  "expires_in": 3920,
  "token_type": "Bearer",
  "scope": "https://www.googleapis.com/auth/dataportability.myactivity.search",
  "refresh_token_expires_in": 2505599
}

如果用户续订访问权限，新的到期时间会反映在 refresh_token_expires_in 字段中。

您可以使用新的访问令牌重复 InitiatePortabilityArchive 和 GetPortabilityArchiveState 步骤。