Google Search Console

核心用法

Google Search Console 技能通过 Maton 平台提供对 Google Search Console API 的托管式访问，无需开发者自行处理复杂的 Google OAuth 2.0 流程。用户只需获取 Maton API Key，即可通过 REST API 查询网站搜索表现数据、管理站点地图、执行 URL 检测等操作。

关键操作流程：
1. 注册 Maton 账户并获取 MATON_API_KEY
2. 创建 Google Search Console 连接，完成浏览器端 OAuth 授权
3. 使用 Authorization: Bearer $MATON_API_KEY 头调用 API
4. 多账户场景下通过 Maton-Connection 头指定特定连接

主要 API 能力：

• 站点管理：列出/获取已验证站点信息
• 搜索分析：查询点击量、展示量、CTR、平均排名，支持按 query、page、device、country、date 维度拆解
• 站点地图：提交、获取、删除 sitemap
• 数据特性：16 个月历史数据、2-3 天延迟、单次最多 25,000 行

显著优点

1. OAuth 托管简化：完全省去 Google Cloud Console 项目配置、OAuth 客户端设置、令牌刷新维护等工作
2. 标准化代理：Maton 统一处理认证注入，开发者只需关注业务逻辑
3. 多语言示例完善：提供 Python、JavaScript、Bash 等可直接运行的代码片段
4. 连接管理灵活：支持多 Google 账户切换，通过连接 ID 精确控制访问范围

潜在缺点与局限性

1. 第三方依赖风险：核心功能依赖 Maton 服务可用性，若 Maton 平台故障则完全不可用
2. 数据延迟固有：Google Search Console 本身存在 2-3 天数据延迟，非本技能可解决
3. 请求限制：Rate limit 为 10 req/sec 每账户，大规模数据抓取需分页处理
4. 环境变量陷阱：文档特别指出 curl 管道到 jq 时环境变量可能无法正确展开
5. 无实时数据：不适合需要即时搜索表现的场景

适合人群

• SEO 分析师：需要程序化获取搜索表现数据用于报告自动化
• 开发者/技术团队：希望快速集成 GSC 数据到内部 BI 或监控系统的团队
• 多站点运营者：管理多个网站且需切换不同 Google 账户查看数据
• 无服务器/边缘计算场景：不方便持久化存储 OAuth 令牌的环境

常规风险

| 风险类型 | 说明 | 缓解建议 |

|---------|------|---------|

| 密钥泄露 | `MATON_API_KEY` 泄露可导致账户数据被访问 | 使用密钥管理服务，避免硬编码 |

| 误操作写入 | 站点地图删除等操作不可逆 | 文档明确要求写操作前用户确认 |

| 权限过度 | OAuth 授权范围可能超出实际需求 | 定期审计 Maton 连接权限 |

| 供应商锁定 | 深度依赖 Maton 代理架构 | 保留直接调用 GSC API 的迁移能力 |

| 数据合规 | 搜索查询数据可能包含敏感信息 | 确保符合 GDPR 等数据保护法规 |

核心用法

本 Skill 是一个纯文档型 API 集成工具，通过 Maton 平台代理访问 Google Search Console API。用户需先在 maton.ai 获取 API Key 并配置 MATON_API_KEY 环境变量，然后通过标准 HTTP 请求调用 Maton 代理端点。核心功能包括三大模块：

搜索分析（Search Analytics）：支持按日期范围查询网站的关键词表现、页面流量、设备分布等维度数据，可获取点击量（clicks）、展示次数（impressions）、点击率（CTR）及平均排名等关键指标。请求需指定 siteUrl（需 URL 编码）、startDate、endDate 及维度参数，单次最多返回 25,000 行数据，支持 startRow 分页。

站点管理（Sites）：列出自有或授权的 Search Console 站点，支持获取单个站点的详细信息。站点 URL 必须严格编码，如 https://example.com 需转换为 https%3A%2F%2Fexample.com。

站点地图（Sitemaps）：支持查看、提交及删除站点地图。写操作（PUT/DELETE）需谨慎，建议在执行前与用户确认目标资源。

连接管理：通过 /connections 端点创建、列出、删除 OAuth 连接。首次使用需在浏览器完成 Google 授权流程，多连接场景需通过 Maton-Connection Header 指定目标连接。

显著优点

安全托管的 OAuth 架构：Skill 本身不处理 OAuth 令牌，所有敏感凭证由 Maton 服务端安全托管，用户仅需管理 Maton API Key，大幅降低令牌泄露风险。

零依赖轻量设计：纯 Markdown 文档型 Skill，无本地可执行代码、无依赖包管理，代码示例仅使用标准库（Python urllib/requests、JavaScript fetch），兼容性极强。

企业级数据覆盖：完整支持 Search Console 核心能力，包括 16 个月历史数据查询、多维度交叉分析（关键词 × 页面 × 国家 × 设备 × 日期）、站点地图生命周期管理。

透明可审计：MIT-0 许可证允许无限制商业使用，所有 API 端点均为知名可信域名（Google、Maton、ClawHub），无隐藏代理或数据中转。

潜在缺点与局限性

数据时效性滞后：Search Console 数据通常有 2-3 天延迟，无法获取实时搜索表现。

日期范围受限：单次查询最多覆盖 16 个月，历史趋势分析需多次聚合。

Maton 平台依赖：核心功能完全依赖 Maton API 服务的可用性，若 Maton 服务中断或调整定价策略，将直接影响 Skill 使用。

无原生可视化：返回数据为 JSON 格式，需用户自行处理为图表或报告，对非技术用户有一定门槛。

写操作风险：sitemap 的 PUT/DELETE 操作会直接影响 Google 索引状态，误操作可能导致收录问题，需严格遵循二次确认机制。

适合的目标群体

SEO 专员与网站运营人员：需要定期监控关键词排名、诊断流量波动、提交新页面至 Google 索引的专业人员。

数据分析师与增长团队：希望将 Search Console 数据接入自有 BI 系统（如 Tableau、Looker、Metabase），进行深度关联分析。

开发者与 DevOps：负责构建自动化 SEO 监控流水线，或集成搜索数据至内部运维大盘的技术团队。

多站点管理者：代理公司、大型媒体集团等需要批量管理数十甚至上百个 Search Console 账户的用户。

使用风险与注意事项

API 密钥泄露风险：MATON_API_KEY 是访问 Maton 服务的唯一凭证，若泄露他人可查询您的所有 Search Console 数据。建议配置 chmod 600 权限、定期轮换（90 天周期）、避免在日志中打印。

多连接混淆风险：当存在多个 Google 账号连接时，未指定 Maton-Connection Header 可能导致请求路由至错误账户，造成数据泄露或误操作。

Rate Limit 限制：Maton 平台限制 10 req/sec，高频批量查询需引入指数退避重试机制。

URL 编码易错点：siteUrl 中的斜杠、冒号等字符必须编码，否则返回 404。Skill 文档中虽提供示例，但手工拼接 URL 时仍易出错。

Shell 环境变量展开问题：文档特别指出，使用 curl 管道至 jq 时 $MATON_API_KEY 可能无法正确展开，建议使用 Python 示例代码规避。