mcpField
G
ghealth-shared

ghealth-shared

github.com/google-health-api其他27460 次安装16 周前更新
代码仓库

关于 ghealth-shared

ghealth 是用于配置认证并通过命令行访问 Google Health API 的工具，适合需要读取健康数据或管理用户资料、Webhook 的 Agent 与开发者。它提供 OAuth 引导、凭据管理及多种数据输出格式。

主要功能

  1. 01交互式与无提示配置
  2. 02OAuth 登录与令牌刷新
  3. 03凭据导入和导出
  4. 04数据与用户资料命令
  5. 05JSON、表格和 CSV 输出

适用场景

  1. 01配置 Google Health API 访问
  2. 02在无浏览器主机完成认证
  3. 03导出健康数据为 CSV
  4. 04管理用户资料和 Webhook

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/google-health-api/google-health-cli --skill ghealth-shared

安装后在 Claude Code 中输入/ghealth-shared确认已加载。

详细介绍

ghealth — 通用前置条件

设置

ghealth setup                       # interactive wizard, run once

六个步骤：GCP 项目 ID、OAuth client_secret JSON（桌面应用）、启用 Health API、选择范围、基于浏览器的 OAuth、保存配置文件。

可编写脚本（跳过提示）：

ghealth setup \
  --project-id my-project \
  --client-secret ~/Downloads/client_secret_123.json \
  --scopes-preset readonly \
  --skip-enable-api \
  --no-prompt

添加 --non-interactive-auth 以跳过浏览器步骤，之后使用 ghealth auth login --complete <code> 完成。

写入的文件

所有文件均位于 ~/.config/ghealth/ 下（使用 GHEALTH_CONFIG_DIR 覆盖）：

文件内容权限模式
client_secret.json你的 GCP OAuth 客户端0600
credentials.json访问令牌 + 刷新令牌（明文 JSON）0600
pending_auth.json进行中的非交互式流程状态0600
config.toml当前配置文件（项目、范围、格式）0600

身份验证

方法用法
已存储的凭据ghealth auth login（设置后默认使用）
无头模式（无浏览器）ghealth auth login --non-interactive → 点击 URL → ghealth auth login --complete <code>
在计算机之间迁移令牌ghealth auth export > creds.json → 在目标计算机上：ghealth auth import --file creds.json
访问令牌（不刷新）export GHEALTH_ACCESS_TOKEN=ya29...
凭据文件export GHEALTH_CREDENTIALS_FILE=/path/to.json
ADC（GCP 环境）如可用则自动使用

优先级：环境变量令牌 > 凭据文件 > 已存储凭据 > ADC。刷新令牌会保存在 credentials.json 中，并自动刷新（访问令牌有效期为 1 小时）；如果 API 返回 401，则会强制刷新一次，然后报错。

检查：ghealth auth status。退出代码：

  • 0 — 已在本地配置；不会发起网络调用。已过期的已存储令牌仍会返回退出代码 0 — JSON 会报告 authenticated: false / expired: true
  • 2 — 存在 client_secret.json，但没有已存储令牌（缺少 credentials.json）；请运行 ghealth auth login
  • 5 — 完全没有 client_secret.json；错误中包含用于引导初始化的 next_steps[]（见下文）

添加 --validate，可通过 Google 的 tokeninfo 端点验证访问令牌。不添加此选项时，环境变量令牌 / 凭据文件模式会报告 configured: true，但绝不会声称 authenticated: true——令牌存在并不能证明其有效。添加 --validate 后，响应会包含来自 Google 的 authenticated、expires_in 和 scope。

Agent 的引导初始化方案

获取 OAuth 客户端 client_secret 检查清单（无需调用失败的命令）：

ghealth setup --instructions
# → exit 0, JSON on stdout with status: "instructions" and next_steps[].
# Same six steps an auth error would emit when no client_secret.json is configured:
#   1. Open https://console.cloud.google.com/apis/credentials
#   2. Create or select a Google Cloud project
#   3. Enable the Google Health API
#   4. Create OAuth client ID with Application type: Desktop app
#   5. Download the client_secret JSON
#   6. Run: ghealth setup --client-secret /path/to/client_secret.json

在缺少 client_secret.json 导致流程受阻的所有错误路径中，也会嵌入相同的 next_steps 数组：auth login（包括 --complete 在内的所有模式）、auth status、auth refresh、auth export、setup --no-prompt。Agent 应使用 jq -e '.error.next_steps' 并原样转达。

在工作站上全新安装（有浏览器）：

ghealth setup    # one interactive run; refresh handles itself afterwards

在无头主机上全新安装（无浏览器）：

ghealth setup --project-id $P --client-secret $CS \
              --scopes-preset readonly --skip-enable-api \
              --no-prompt --non-interactive-auth
# stdout prints status: "setup_pending_auth" + an auth_url on stderr
# human clicks the URL on any browser → URL bar shows ?code=... ; agent copies it
ghealth auth login --complete <code>

将令牌挂载到容器 / 第二个工作节点：

# on authenticated host:
ghealth auth export > /secrets/ghealth-creds.json
# in the container (with the same client_secret.json available):
ghealth auth import --file /secrets/ghealth-creds.json

命令结构

ghealth data <type> <operation> [flags]
ghealth user <subcommand>
ghealth schema <subcommand>
ghealth webhooks <subcommand>

user 子命令：identity、profile get|update、settings get|update、irn-profile、paired-devices list|get --id <id>。

webhooks 子命令：subscribers list|create|update|delete、subscriptions list|create|update|delete --subscriber <id>、verify --url <url>。需要 cloud-platform 范围（ghealth auth login --scopes cloud-platform）**以及已配置的项目 ID。**这些是项目级推送通知端点；经过身份验证的身份还需要在该项目上拥有 Health API 订阅者 IAM 权限。

全局标志

标志作用
--format json|table|csv输出格式（默认：json）
-o <file>将数据写入文件；stdout 仅显示列架构和 3 行预览（不含数据）
--raw跳过响应简化，返回原始 API JSON
--dry-run打印 HTTP 请求，但不执行
--profile <name>使用指定名称的配置档案

list 也接受：--limit N（结果总数上限，默认 500）、--from、--to、--filter、--page-token（从先前响应的 nextPageToken 处继续）、--detail（睡眠）。

发现

ghealth schema types              # All types + supported operations
ghealth schema type <name>        # Fields, parameters for one type
ghealth data <type> --help        # Available operations
ghealth data <type> list --help   # Flags for an operation

输出

  • 默认会简化响应：时间戳采用带 UTC 偏移量的扁平格式，来源信息精简，并移除空字段
  • 所有读取操作（list、get、rollup、daily-rollup、reconcile）的 JSON 输出形状始终一致：对象 {"dataPoints": [...]}，可选包含 _hints 和 nextPageToken。行始终位于 dataPoints 下，即使是汇总和空结果也是如此，因此 json.load(out)["dataPoints"] 始终可用
  • --raw 返回完整的 API 响应
  • --format csv 输出扁平 CSV；嵌套对象会自动展平为以点号分隔的列（例如，metricsSummary.caloriesKcal）
  • -o <file> 会将数据写入文件，并且 stdout 仅输出摘要（行数、列名、3 行预览）。请使用此方式代替管道（> file）——管道会将数据写入文件，但 stdout 上不会显示架构
  • 错误始终以 JSON 格式输出到 stderr，退出代码为 0-5
  • 时间戳包含用户的时区偏移量（例如，+01:00）

评论

支持 Markdown