@gscdump/engine-gsc-api

中文文档
7.15.0发布于 2026/11/16MITTypeScriptES Module构建来源已验证近 30 天下载 9266

GSC活API引擎适配器——将"搜索分析"(Search Analytics REST API)包装为"分析查询源"(Analysis Query source),用于打入分析器调度.

中文使用文档
文档目录7 节
  1. 安装
  2. 查询活行
  3. 推迟认证
  4. 出口
  5. 计划存储同步工作
  6. 限制和后退
  7. 许可证

@gscdump/ engine- gsc- api

npm version npm downloads license

使用 Google 搜索主控台作为 AnalysisQuerySource。 。 。 . 这个适配器在无本地 Store 的行图下运行分析器.

安装

npm install @gscdump/engine-gsc-api @gscdump/analysis gscdump

查询活行

import { createGscApiQuerySource } from '@gscdump/engine-gsc-api'
import { googleSearchConsole } from 'gscdump'
import { between, date, gsc, page } from 'gscdump/query'

const client = googleSearchConsole({ accessToken: process.env.GSC_ACCESS_TOKEN! })
const source = createGscApiQuerySource({ client, siteUrl: 'sc-domain:example.com' })
const state = gsc.select(page)
  .where(between(date, '2026-08-01', '2026-08-28'))
  .limit(100)
  .getState()

const rows = await source.queryRows(state)
console.log(rows)

见 @gscdump/analysis 用于分析器调度.

推迟认证

createLiveGscSource({ siteUrl, getAccessToken }) 在第一个查询中调用您的符号函数. 它为源头的一生重用产生的客户端. 如果您的主机在请求之间管理着令牌刷新, 则每个请求创建源 .

出口

导出目的
createGscApiQuerySource将 Google 客户端包成源
createLiveGscSource以延迟的符号查找创建源
canProxyToGsc检查查询输入是否支持实时路由
fetchGscTopN读取一个尺寸和日期范围的上行
fetchGscDaily每天阅读衡量标准
runGscSyncSlice读取边框搜索分析同步切片
runGscSearchAppearanceContextSlice读取搜索外观上下文切片
planGscSyncWork查找分类账缺口和大小 同步窗口
gscSyncFanout构建标准搜索分析表扇出
tablesCoveredByGscSync列出表格,同步切片必须写入
ledgerTablesForGscSync列出一个扇形图所需的分类表
planGscBackfillDates选择内部修复或后向填充日期

计划存储同步工作

传过去你想要覆盖的日期,计划 (table, searchType) 扇出,和 日期已经输入你的分类账。 计划只返回缺失 窗口。 在分类账中记录零行切片,所以不会重复.

import { gscSyncFanout, planGscSyncWork } from '@gscdump/engine-gsc-api'

const plan = planGscSyncWork({
  dates: ['2026-09-01', '2026-09-02'],
  fanout: gscSyncFanout(['web'], { omitWebDates: true }),
  ledger: [{ table: 'pages', searchType: 'web', date: '2026-09-01' }],
  pagesPerDayEstimate: 100,
})

for (const window of plan.windows) {
  // Run runGscSyncSlice for this table and date range, then commit its ledger rows.
  console.log(window)
}

默认匹配主机Worker测试的窗口预算. 设定 rowBudget, (中文(简体) ), maxSpanDays,以及 maxWindowsPerRun 为你自己的运行时间。 窗口数 限制可以扩大范围 maxSpanDays 在长时间的追赶中.

限制和后退

源支持行查询和regex过滤. 它没有 SQL 执行、 比较连接或引擎衍生的维度, 例如 queryCanonical。 。 。 . canProxyToGsc 在选择或过滤中拒绝错误的输入、预过滤和引擎衍生的维度. 收集行后仍然支持度量过滤器 .

createCompositeSource 从 @gscdump/analysis/source 接受 { engine, live, site }。 。 。 . 当存储覆盖或维度无法回答时,它会向谷歌发送支持的查询. 这个 site 输入供给同步约束和可选覆盖日期跨度. SQL执行使用"引擎".

谷歌的音乐 搜索分析限制 仍然适用.

许可证

麻省理工学院

版本与发布记录

@gscdump/engine-gsc-api 共发布 262 个版本,首次发布于 2026/04/28;过去 12 个月发布了 262 个版本。最新版本附带 npm provenance 构建来源证明,可追溯到公开的 CI 构建记录。

版本发布日期距今
7.15.0latest2026/11/16今天
7.14.02026/11/16今天
7.13.22026/11/151 天前
7.13.12026/11/152 天前
7.13.02026/11/124 天前
7.12.12026/11/116 天前

关于 @gscdump/engine-gsc-api 的常见问题

@gscdump/engine-gsc-api 是什么?

GSC活API引擎适配器——将"搜索分析"(Search Analytics REST API)包装为"分析查询源"(Analysis Query source),用于打入分析器调度.

如何安装 @gscdump/engine-gsc-api?

在项目目录运行 npm install @gscdump/engine-gsc-api,或使用 pnpm add / yarn add / bun add。

@gscdump/engine-gsc-api 支持 TypeScript 吗?

支持。包内自带 TypeScript 类型声明(package.json 声明了 types 入口),安装后即可获得类型提示,无需再安装 @types 包。

@gscdump/engine-gsc-api 支持 ESM 还是 CommonJS?

以 ES Module 形式发布,推荐使用 import 引入。在 CommonJS 项目中,Node.js 20.19+ / 22.12+ 可以直接 require() 不含顶层 await 的 ES Module,更早的版本需要改用动态 import()。

@gscdump/engine-gsc-api 需要什么版本的 Node.js?

package.json 的 engines 字段要求 Node.js >=22.13.0。版本不符时 npm 默认只给出警告,开启 engine-strict 后会拒绝安装。

@gscdump/engine-gsc-api 可以商用吗?

@gscdump/engine-gsc-api 使用 MIT 许可。宽松许可:允许商业使用、修改和再分发,通常只需在分发时保留原版权与许可声明。以上为概括,不构成法律意见,请以许可原文为准。

@gscdump/engine-gsc-api 的下载量有多少?

根据 npm 官方下载统计,@gscdump/engine-gsc-api 在 2026/10/17 – 2026/11/15 这 30 天内被下载 9,266 次,日均约 309 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入,适合横向比较热度,不能直接等同于使用人数。

@gscdump/engine-gsc-api 还在维护吗?

最新版本 7.15.0 发布于 2026/11/16(今天);至今共发布 262 个版本,其中过去 12 个月发布了 262 个;首次发布于 2026/04/28。发布频率只是参考信号:功能稳定的工具可能很少需要更新,建议结合源码仓库的 issue 和提交记录判断。