google-search-console

用途

本技能用于读取 Google Search Console 中已验证站点的数据，涵盖搜索分析、站点地图和 URL 索引状态检查。官方文档：https://developers.google.com/webmaster-tools/v1/api_reference_index

主要能力

拉取关键词/页面表现：点击、展示、CTR、平均排名
查看已提交的站点地图及其处理状态
检查特定 URL 的索引覆盖与抓取状态

前置条件

在 vm0.ai → Settings → Connectors 中连接 Google Search Console（OAuth）。
所连接的 Google 账号必须已是 Search Console 中该资源的已验证所有者/用户。
访问令牌以 $GOOGLE_SEARCH_CONSOLE_TOKEN 注入。访问为只读（webmasters.readonly）。
基础地址：https://searchconsole.googleapis.com
siteUrl 格式——在路径中必须进行 URL 编码：
- URL 前缀资源：https://www.example.com/ → https%3A%2F%2Fwww.example.com%2F
- 域资源：sc-domain:example.com → sc-domain%3Aexample.com

使用方式

1. 列出已验证站点

查找你有权访问的确切 siteUrl 值（后续调用中使用其中之一）：

curl -s "https://searchconsole.googleapis.com/webmasters/v3/sites" --header "Authorization: Bearer $GOOGLE_SEARCH_CONSOLE_TOKEN" | jq '.siteEntry[] | {siteUrl, permissionLevel}'

2. 查询搜索分析

核心报表。返回按所请求维度分组的指标行。维度：query、page、country、device、searchAppearance、date。

将请求体写入 /tmp/gsc_query.json（某日期范围内按点击排序的前 25 个查询）：

{
  "startDate": "2026-05-01",
  "endDate": "2026-05-31",
  "dimensions": ["query"],
  "rowLimit": 25,
  "orderBy": [{ "field": "clicks", "descending": true }]
}

然后运行（将 <site-url-encoded> 替换为第 1 步中的值）：

curl -s -X POST "https://searchconsole.googleapis.com/webmasters/v3/sites/<site-url-encoded>/searchAnalytics/query" --header "Authorization: Bearer $GOOGLE_SEARCH_CONSOLE_TOKEN" --header "Content-Type: application/json" -d @/tmp/gsc_query.json | jq '.rows[] | {query: .keys[0], clicks, impressions, ctr, position}'

按页面而非查询：设置 "dimensions": ["page"] 并读取 page: .keys[0]。

过滤——添加 dimensionFilterGroups 块，例如仅返回页面包含 /blog/ 的行：

{
  "startDate": "2026-05-01",
  "endDate": "2026-05-31",
  "dimensions": ["query"],
  "dimensionFilterGroups": [
    { "filters": [{ "dimension": "page", "operator": "contains", "expression": "/blog/" }] }
  ],
  "rowLimit": 25
}

注意：Search Console 数据有约 2-3 天的延迟，最近几天的数据可能不完整。

3. 列出站点地图

查看已提交的站点地图以及 Google 是否已处理：

curl -s "https://searchconsole.googleapis.com/webmasters/v3/sites/<site-url-encoded>/sitemaps" --header "Authorization: Bearer $GOOGLE_SEARCH_CONSOLE_TOKEN" | jq '.sitemap[] | {path, lastSubmitted, lastDownloaded, isPending, errors, warnings, contents}'

获取单个站点地图

<feedpath> 是完整的站点地图 URL，需 URL 编码：

curl -s "https://searchconsole.googleapis.com/webmasters/v3/sites/<site-url-encoded>/sitemaps/<feedpath-encoded>" --header "Authorization: Bearer $GOOGLE_SEARCH_CONSOLE_TOKEN" | jq '{path, lastDownloaded, errors, warnings, contents}'

4. 检查 URL（索引状态）

检查特定 URL 是否已索引、其覆盖状态及最后抓取时间。

写入 /tmp/gsc_inspect.json（此处 siteUrl 为原始、未编码的资源；inspectionUrl 必须属于该资源）：

{
  "inspectionUrl": "https://www.example.com/blog/my-post",
  "siteUrl": "https://www.example.com/"
}

然后运行：

curl -s -X POST "https://searchconsole.googleapis.com/v1/urlInspection/index:inspect" --header "Authorization: Bearer $GOOGLE_SEARCH_CONSOLE_TOKEN" --header "Content-Type: application/json" -d @/tmp/gsc_inspect.json | jq '.inspectionResult.indexStatusResult | {verdict, coverageState, lastCrawlTime, googleCanonical, indexingState, robotsTxtState}'

适用场景

需要拉取关键词/页面表现（点击、展示、CTR、平均排名）时
需要查看已提交的站点地图及其处理状态时
需要检查特定 URL 的索引覆盖与抓取状态时

限制

访问为只读：提交/删除站点地图以及添加/移除站点需要完整的 webmasters 权限范围，本连接器不请求该权限。
searchAnalytics/query 每次请求的 rowLimit 上限为 25000；更大规模拉取需使用 startRow 分页。
使用第 1 步返回的确切 siteUrl 字符串——尾部斜杠或 http/https 不匹配会返回 403。