给 Agent 开 GCP service account 访问 Search Console 和 GA4 数据

TLDR

想让 Claude Code 之类的 Agent 直接读 Google Search Console 和 GA4 的统计做 SEO 分析，不能靠 OAuth 浏览器授权（Agent 没有交互式登录），正确做法是 GCP service account：建一个服务账号 → 启用两个 API → 把这个服务账号邮箱加到 Search Console / GA4 里授权 → Agent 拿 JSON key 调 REST API。本文记录完整流程和踩的坑。

架构

Agent (Claude Code)
  → CLI 脚本 (gsc.py / ga.py)
  → service account JSON key 认证
  → Search Console API / Analytics Data API
  → 你的站点数据

关键点：service account 不是「你的 Google 账号」，而是 GCP 项目里的一个机器身份。权限不是靠账号密码，而是靠「把这个机器身份的邮箱加进目标资源」。

步骤 1：创建 service account

入口直达（PROJECT_ID 换成你的项目 ID）：

https://console.cloud.google.com/iam-admin/serviceaccounts?project=PROJECT_ID

菜单路径：☰ 导航 → IAM 与管理 → 服务账号

流程：+ 创建服务账号 → 填名称（如 seo-bot）→ 角色步骤可跳过（权限后面通过「加邮箱到 GSC/GA」给）→ 完成 → 回到列表点进账号 → 密钥 标签 → 添加密钥 → 创建新密钥 → JSON，浏览器下载一个 .json。

下载的 key 存到本地：

mkdir -p ~/.config/google
mv ~/Downloads/xxx.json ~/.config/google/key.json
chmod 600 ~/.config/google/key.json   # 私钥，收紧权限

坑 1：macOS 下 mv 下载文件夹里的文件可能报 Operation not permitted，这是 TCC 隐私保护（终端没「下载文件夹」访问权限）。要么在 系统设置 → 隐私与安全性 → 文件与文件夹 里给终端开权限，要么用 Finder 拖拽。

记下 service account 的邮箱（形如 seo-bot@PROJECT_ID.iam.gserviceaccount.com），后面授权要用。

步骤 2：启用两个 API

「建服务账号」和「启用 API」是两件独立的事，容易漏。不启用会报 accessNotConfigured / SERVICE_DISABLED。

两个直达 URL（注意 PROJECT_NUMBER 是数字项目编号，不是项目 ID——GCP 里这俩是不同的东西，API 启用页用的是数字编号）：

Search Console API：

https://console.developers.google.com/apis/api/searchconsole.googleapis.com/overview?project=PROJECT_NUMBER

Analytics Data API（GA4 用）：

https://console.developers.google.com/apis/api/analyticsdata.googleapis.com/overview?project=PROJECT_NUMBER

各点一下「启用」，变成「管理」就是启用了。启用后等 1-2 分钟让 Google 传播。

坑 2：PROJECT_ID（字母数字，如 my-project-123）和 PROJECT_NUMBER（纯数字，如 123456789012）是两个不同的标识。IAM 页用 ID，API 启用页用 NUMBER。搞混了 URL 会 404。

步骤 3：授权 service account 到 Search Console

直达 URL（SITE_URL 换成你的站点）：

https://search.google.com/search-console/users?resource_id=SITE_URL_ENCODED

resource_id 是 URL 编码后的站点地址，例如 https%3A%2F%2Fwww.example.com%2F。

→ 添加用户 → 粘贴 seo-bot@PROJECT_ID.iam.gserviceaccount.com → 权限选 「受限」（只读够用）。

步骤 4：授权到 GA4

直达 URL：

https://analytics.google.com/analytics/web/#/admin

→ 管理 → 媒体资源 列 → 媒体资源访问管理 → + 添加用户 → 粘同一邮箱 → 角色 「查看者」。

注意 GA4 里有两个 ID：

ga.py 的 --property 参数填数字媒体资源 ID，不是 G- 开头那个。数字 ID 在 管理 → 媒体资源设置 里看。

步骤 5：CLI 脚本

两个轻量 Python 脚本（service account key 走 ~/.config/google/key.json）：

# Search Console：近 30 天点击量 top 页面
python3 cli/gsc.py --site https://www.example.com/ --dimension page --days 30

# Search Console：top 查询词
python3 cli/gsc.py --dimension query --limit 20

# Search Console：单 URL 索引状态
python3 cli/gsc.py --inspect /path/to/page

# Search Console：sitemap 提交状态
python3 cli/gsc.py --sitemaps

# GA4：近 30 天活跃用户
python3 cli/ga.py --property 123456789 --metrics activeUsers,sessions --days 30

依赖与虚拟环境：

python3 -m venv .venv
.venv/bin/pip install google-api-python-client google-auth

坑 3：Homebrew 的 Python 是 externally-managed（PEP 668），直接 pip install 会被拒（除非 --break-system-packages，不推荐）。用项目级 .venv 最干净。

步骤 6：验证

两个脚本各跑一条，能出数据就通了：

.venv/bin/python cli/gsc.py --sitemaps
.venv/bin/python cli/ga.py --property 123456789 --metrics activeUsers --days 30

踩坑总结

参考资料

• Search Console API 文档
• Analytics Data API 文档
• GCP service account 文档