使用 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 账号登录 。
  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”并启用它。

设置 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 要求您将自己的 OAuth 凭据与 Playground 搭配使用。

  1. 点击右上角的 OAuth 2.0 配置 齿轮图标。
  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 以供日后使用。

5. 向 API 发送请求

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

  1. 将 HTTP 方法 设置为 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"

再次点击 Send the request 以查看过滤后的结果。

6. 恭喜

恭喜！

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

希望您喜欢构建与 Google Health API 生态系统集成的应用。如需了解详情，请参阅参考文档中的其他 Google Health API 端点，并详细了解针对 Web 服务器应用的 Google OAuth 2.0。