使用 OAuth2 Playground 完成首次 Google Health API 调用

1. 简介

OAuth 2.0 Playground 是一款基于 Web 的工具，可帮助您在不编写任何代码的情况下测试 Google OAuth 2.0 流程。此 Codelab 将向您展示如何设置 Google Cloud 项目、获取凭据、使用 OAuth 2.0 Playground 启动授权流程，以及首次调用某个 Google Health API 端点。

学习内容

  • 如何在 Google Cloud 控制台中设置客户端 ID。
  • 如何使用 OAuth 2.0 Playground 完成 Google OAuth 2.0 授权流程，以获取访问令牌和刷新令牌。
  • 如何使用 OAuth 2.0 Playground 调用 Google Health API 端点。

所需条件

如要设置 Fitbit 移动应用，请执行以下操作：

  1. 在 Apple App Store 或 Google Play 商店中搜索 Fitbit 移动应用，然后下载该应用。
  2. 选择应用图标。
  3. 点击使用 Google 账号登录 (Sign in with Google)。
  4. 选择您的 Google 账号，然后按继续按钮。

2. 设置 Google Cloud 项目

您将使用 Google Cloud 控制台创建客户端 ID 并启用 Google Health API 的使用。

  1. 登录 Google Cloud 控制台。
  2. 如需创建新项目，请执行以下操作：
    1. 在项目选择器中点击选择项目。
    2. 在右上角，选择新项目。
    3. 输入您的项目名称。
    4. 输入您的位置（例如“无组织”）。
    5. 点击创建按钮。
    6. 选择您的项目。

启用 Google Health API

  1. 点击左上角的菜单图标：菜单
  2. 选择 API 和服务 > 库。
  3. 搜索“Google Health API”，然后启用该 API。

设置 OAuth 凭据

如果您不在 Google Cloud 控制台中，请前往 Google Cloud 控制台。

  1. 点击左上角的菜单图标：菜单
  2. 依次选择 API 和服务 > 凭据。
  3. 在顶部中心位置，依次选择 + 创建凭据 > OAuth 客户端 ID。
  4. 点击配置同意屏幕按钮。如果系统显示“尚未配置 Google Auth Platform”消息，请点击开始使用按钮。
  5. 在第 1 部分中：
    1. 输入应用名称。
    2. 输入用户支持电子邮件地址。
    3. 点击下一步按钮。
  6. 在第 2 部分中：
    1. 选择外部。
    2. 点击下一步按钮。
  7. 在第 3 部分中：
    1. 在联系信息字段中输入您的电子邮件地址。
    2. 点击下一步按钮。
  8. 在第 4 部分中：
    1. 点击复选框，表示同意《Google 的 API 服务用户数据政策》。
    2. 点击创建按钮。
  9. 前往 API 和服务 > 凭据，然后依次选择 + 创建凭据 > OAuth 客户端 ID。
  10. 选择应用类型 Web 应用。
  11. 输入客户端 ID 名称。
  12. 将已获授权的 JavaScript 来源留空。
  13. 在已获授权的重定向 URI 下，点击 + 添加 URI，然后添加以下 URI：
    • https://www.google.com
    • https://developers.google.com/oauthplayground
  14. 点击创建按钮。
  15. Google 控制台会显示一条消息，告知您已创建客户端 ID。点击下载 JSON 链接下载客户端 ID 和客户端密钥，或记下这些值。之后您将无法恢复客户的密钥。
  16. 点击确定。您将返回到“OAuth 2.0 客户端 ID”页面。
  17. 您的客户端 ID 将添加到您的项目中。点击客户端 ID 网址即可查看详细信息。

添加测试用户

  1. 在左侧窗格中，选择受众群体。您应该会看到“发布状态”设置为测试，“用户类型”设置为外部。
  2. 在“测试用户”部分下，点击 + 添加用户按钮。输入您要检索其数据的任何用户的电子邮件地址。
  3. 点击保存按钮。

向客户端 ID 添加范围

  1. 在左侧窗格中，选择数据访问。
  2. 点击添加或移除范围按钮。
  3. 在“API”列中，搜索“Google Health API”。在此 Codelab 中，我们使用的是 .../auth/googlehealth.activity_and_fitness.readonly 范围
  4. 选择范围后，按更新按钮返回到“数据访问权限”页面。
  5. 点击保存按钮。

您已完成客户端 ID 的设置。

3. 向 Fitbit 移动应用添加数据

对于 Fitbit 新用户，您的 Fitbit 账号中可能没有可查询的数据。我们将手动添加锻炼日志，然后通过某个端点查询该日志。如需手动记录锻炼，请按以下步骤操作：

  1. 在设备上打开 Fitbit 移动应用。根据需要登录 Fitbit 账号。
  2. 点按屏幕右下角的“+”按钮。
  3. 在“手动记录”部分，点按活动
  4. 搜索锻炼类型步行，然后选择该类型。
  5. 输入今天的开始时间。
  6. 将时长更改为 15 分钟。
  7. 将距离设为 1.0 英里。
  8. 点按添加。
  9. 长按屏幕并向下滑动，将移动应用与 Fitbit 服务器同步。松开手指后，您应该会看到移动应用同步。
  10. 在“活动”部分，您应该会看到手动记录的“步行”条目。显示步行活动的屏幕截图。

4. 在 OAuth 2.0 Playground 中进行授权

前往 OAuth 2.0 Playground。

Google Health API 要求您在 Playground 中使用自己的 OAuth 凭据。

  1. 点击右上角的 OAuth 2.0 Configuration 齿轮图标。
  2. 选择 Use your own OAuth credentials（使用您自己的 OAuth 凭据）。
  3. 输入您在 Google Cloud 项目设置期间获得的 OAuth 客户端 ID 和 OAuth 客户端密钥。

Playground 界面分为三个主要步骤，我们将按顺序执行这些步骤：

  1. 选择并授权 API
  2. 将授权代码兑换为令牌
  3. 向 API 发送请求

选择并授权 API

您可以在此处选择要请求的 API 范围。

  1. 在第 1 步中，找到 API 列表中的 Google Health API v4 并展开它。
  2. 选择 https://www.googleapis.com/auth/googlehealth.activity_and_fitness.readonly。如果列表中未显示您需要的范围，您可以在“输入您自己的范围”字段中手动输入。
  3. 点击授权 API。
  4. 系统会向 Google 的 OAuth 2.0 授权端点发送请求，所选范围会包含在请求中，然后您会被重定向到 Google 账号权限请求页面。
  5. 使用您在设置 Google Cloud 项目部分配置的测试用户账号登录（如果尚未登录）。
  6. 查看请求的权限，然后点击继续以授予访问权限。

您授予同意权限后，Google 会将您重定向回 Playground，并向该工具提供授权代码，该代码将在下一步中使用。

右侧的请求 / 响应面板会显示完整的 HTTP 重定向流程。

初始授权请求的响应是 302 Found 重定向：

HTTP/1.1 302 Found
Location: https://accounts.google.com/o/oauth2/v2/auth?redirect_uri=https%3A%2F%2Fdevelopers.google.com%2Foauthplayground&prompt=consent&response_type=code&client_id=your_client_id&scope=https%3A%2F%2Fwww.googleapis.com%2Fauth%2Fgooglehealth.activity_and_fitness.readonly&access_type=offline

重定向回 Playground 的结果请求包含授权代码：

GET /oauthplayground/?iss=https://accounts.google.com&code=authorization_code&scope=https://www.googleapis.com/auth/googlehealth.activity_and_fitness.readonly HTTP/1.1
Host: developers.google.com

授权代码是 GET 请求网址中 code= 和 &scope 之间的 authorization_code 所表示的字母数字值。在此示例中，该值类似于：4/0AbPOj...

将授权代码兑换为令牌

在此步骤中，代码会换取令牌，以便您发出 API 请求。

完成选择和授权 API 后，Playground 会自动填充授权代码字段。如需将其兑换为令牌，请执行以下操作：

  1. 点击第 2 步中的将授权代码转换为令牌按钮。
  2. access_token 和 refresh_token 会显示在右侧的请求/响应面板中。

您应该会看到如下所示的响应：

{
  "access_token": "ya29.a0AFH6S....",
  "refresh_token_expires_in": 604799,
  "expires_in": 3599,
  "token_type": "Bearer",
  "scope": "https://www.googleapis.com/auth/googlehealth.activity_and_fitness.readonly",
  "refresh_token": "1/og..."
}

刷新令牌简介

当您兑换授权代码时，除了 access_token 之外，响应还可能包含 refresh_token。access_token的生命周期较短（通常为 1 小时）。当 access_token 过期时，您必须使用 refresh_token 获取新的 access_token，而无需用户再次登录或同意。之所以能这么做，是因为我们在授权请求中加入了 access_type=offline。

如果您在响应中未收到 refresh_token，可能是因为您已为此应用和范围授予同意声明。刷新令牌通常仅在用户首次向您的应用授予同意权限时，或者在授权网址中添加 prompt=consent 以强制显示同意屏幕（即使在后续授权中也是如此）时才会颁发。

refresh_token 的有效期很长，但如果 6 个月未使用、用户撤消了对您应用的访问权限或出于其他原因，则可能会过期或失效。您应安全地存储 refresh_token 以备将来使用。

关于更新范围

如果您的应用日后需要访问其他 Google Health API 范围，您必须提示用户重新授权您的应用，并请求完整的范围集（包括现有范围和新范围）。

如需更新应用授权请求中的范围，请执行以下操作：

  1. 确定应用所需的范围的完整列表。
  2. 修改授权网址中的 scope 参数，以包含更新后的以空格分隔的范围值列表。
  3. 将 prompt=consent 附加到身份验证 URI 参数。如果包含 prompt=consent，则每次应用请求授权范围时，系统都会显示同意屏幕，提示用户批准更新后的列表。

用户完成同意流程后，您会收到一个新的授权代码，该代码可用于换取涵盖全套范围的令牌。

5. 向 API 发送请求

现在，您可以使用访问令牌向 Google Health API 发出请求。在 Playground 的第 3 步中，通过指定请求 URI、HTTP 方法、标头和请求正文来配置 HTTP 请求。

  1. 将 HTTP Method 设置为 GET。
  2. 将请求 URI 设置为 https://health.googleapis.com/v4/users/me/dataTypes/exercise/dataPoints。
  3. 点击 Send the request。

响应内容应如下所示：

{
  "dataPoints": [
    {
      "name": "users/2515055256096816351/dataTypes/exercise/dataPoints/8896720705097069096",
      "dataSource": {
        "recordingMethod": "MANUAL",
        "platform": "FITBIT"
      },
      "exercise": {
        "interval": {
          "startTime": "2026-02-23T13:10:00Z",
          "startUtcOffset": "-18000s",
          "endTime": "2026-02-23T13:25:00Z",
          "endUtcOffset": "-18000s"
        },
        "exerciseType": "WALKING",
        "metricsSummary": {
          "caloriesKcal": 16,
          "distanceMillimiters": 1609344,
          "steps": "2038",
          "averagePaceSecondsPerMeter": 0.55923407301360051,
          "activeZoneMinutes": "0"
        },
        "exerciseMetadata": {},
        "displayName": "Walk",
        "activeDuration": "900s",
        "exerciseEvents": [
          {
            "eventTime": "2026-02-23T13:10:00Z",
            "eventUtcOffset": "-18000s",
            "exerciseEventType": "START"
          },
          {
            "eventTime": "2026-02-23T13:25:00Z",
            "eventUtcOffset": "-18000s",
            "exerciseEventType": "STOP"
          }
        ],
        "updateTime": "2026-02-24T01:19:22.450466Z"
      }
    },
    {
      "name": "users/2515055256096816351/dataTypes/exercise/dataPoints/5870930690409355408",
      "dataSource": {
        "recordingMethod": "MANUAL",
        "platform": "FITBIT"
      },
      "exercise": {
        "interval": {
          "startTime": "2026-02-23T06:00:00Z",
          "startUtcOffset": "-18000s",
          "endTime": "2026-02-23T06:15:00Z",
          "endUtcOffset": "-18000s"
        },
        "exerciseType": "WALKING",
        "metricsSummary": {
          "caloriesKcal": 17,
          "distanceMillimiters": 1609344,
          "steps": "2038",
          "averagePaceSecondsPerMeter": 0.55923407301360051,
          "averageHeartRateBeatsPerMinute": "81",
          "activeZoneMinutes": "0",
          "heartRateZoneDurations": {
            "lightTime": "900s"
          }
        },
        "exerciseMetadata": {},
        "displayName": "Walk",
        "activeDuration": "900s",
        "exerciseEvents": [
          {
            "eventTime": "2026-02-23T06:00:00Z",
            "eventUtcOffset": "-18000s",
            "exerciseEventType": "START"
          },
          {
            "eventTime": "2026-02-23T06:15:00Z",
            "eventUtcOffset": "-18000s",
            "exerciseEventType": "STOP"
          }
        ],
        "updateTime": "2026-02-23T08:29:39.480437Z"
      }
    }
  ],
  "nextPageToken": ""
}

许多端点都支持用于过滤或分页的查询参数。例如，如需列出特定时间范围内的锻炼项目，请更改请求 URI 以添加过滤参数：

https://health.googleapis.com/v4/users/me/dataTypes/exercise/dataPoints?filter=exercise.interval.civil_start_time >= "2026-02-22T00:00:00"

再次点击发送请求，查看过滤后的结果。

6. 恭喜

恭喜！

您已完成基本 Codelab，并成功学习了如何使用 OAuth2 Playground 测试 OAuth 2.0 授权以及如何调用 Google Health API 端点。

希望您能愉快地构建与 Google Health API 生态系统集成的应用。如需了解详情，请参阅参考文档，探索其他 Google 健康数据 API 端点，并详细了解如何针对网络服务器应用使用 Google OAuth 2.0。