google-api-nodejs-client 的 realtimebidding 子包:版本演进、破坏性变更与 RTB 集成实战
google-api-nodejs-client 的 realtimebidding 子包:版本演进、破坏性变更与 RTB 集成实战
导读
本文以 google-api-nodejs-client 仓库中 realtimebidding 子包 CHANGELOG 为线索,梳理 Real-time Bidding API 客户端从 2021 年首个正式版本到 13.2.0 的完整演进史,解读 Node.js 运行时基线(Node 12 → 18 → 22)与 googleapis-common 依赖升级带来的破坏性影响,并结合 v1 源码 与 Discovery 文档 讲解 bidder、buyer、pretargeting 配置、creative 与 publisher connection 等核心资源的使用方式,帮助读者理解版本升级要点并掌握基于官方客户端接入 Google 实时竞价(RTB)的完整路径。
一、realtimebidding 子包与 RTB 能力概览
在 google-api-nodejs-client 仓库中,src/apis/realtimebidding/ 目录是一个独立发布、独立版本号的子包。其 README 对该 API 的定位是:允许外部 bidder(广告竞价方)管理其与 Google 的 RTB(Real-Time Bidding)集成,包括:
- 管理 bidder 竞价端点(endpoints)与 QPS 配额;
- 通过 pretargeting(预定向)配置决定接收哪些广告库存;
- 提交 creative(广告素材)供验证;
- 获取 creative 元数据,如审批状态。
从 Discovery 文档 可以看到该 API 的权威信息:canonicalName 为 "Real-time Bidding",baseUrl 为 https://realtimebidding.googleapis.com/,认证方式为 OAuth 2.0,唯一 scope 是 https://www.googleapis.com/auth/realtime-bidding("See, create, edit, and delete your Authorized Buyers and Open Bidding account entities")。
该子包同时在 index.ts 中暴露两个 API 版本:
v1:稳定版本,资源最完整;v1alpha:Alpha 版本,目前仅包含bidders.biddingFunctions等早期能力。
使用时可通过 google.realtimebidding('v1') 或 google.realtimebidding('v1alpha') 选择版本。CHANGELOG 中记录的版本号即对应 npm 上独立发布的 @googleapis/realtimebidding 包。
二、版本演进时间线:从 0.1.0 到 13.2.0
CHANGELOG 完整记录了 2021 年 3 月(0.2.0)至今的每次发布。按重大节点可划分为几个阶段:
| 阶段 | 版本范围 | 时间 | 关键变化 |
|---|---|---|---|
| 早期 | 0.1.0 – 1.0.0 | 2021-03 至 2021-06 | 初版发布,生成器改造,googleapis-common 升级到 v5 |
| 稳定期 | 1.1.0 – 4.x | 2021-06 至 2024-10 | 周期性 "update the API"(跟随上游 Discovery 文档重新生成) |
| Node 18 基线 | 5.0.0 – 6.0.0 | 2025-05 至 2025-06 | 明确 "upgrade to node 18",googleapis-common 升级到 8.x |
| Node 22 基线 | 7.0.0 – 13.2.0 | 2025-09 至 2026-10 | 最低 Node 版本提升到 22,googleapis-common 升至 9.0.0 |
从提交记录看,每次 "update the API" 都由自动化生成器(generator)基于 Google Discovery 文档重新生成 v1.ts 与 v1alpha.ts,因此版本号变化往往对应 API 表面(资源、方法、Schema 字段)的增删改,而非手写业务逻辑的变更。
三、破坏性变更(Breaking Changes)解读
CHANGELOG 中多次出现 ⚠ BREAKING CHANGES 标记,从源码与包配置可以验证其真实影响。
3.1 Node 版本基线:Node 12 → 18 → 22
- 4.0.0(2022-10):"submodules now require Node 12"——生成子模块最低要求从 Node 10 提升到 12;
- 5.0.0 / 6.0.0(2025-05/06):"upgrade to node 18";
- 10.0.0 – 13.0.0(2026-09/10):"Update apiary to minimum Node version of 22"。
这一变化直接反映在包配置中:realtimebidding 子包 package.json 当前声明 "engines": { "node": ">=22.0.0" },与仓库根 package.json 的 "node": ">=22.0.0" 一致。升级到最新版本前,务必确认运行环境 Node 版本 ≥ 22,否则安装或运行会因 engines 校验失败。
3.2 依赖升级:googleapis-common 8.x / 9.x
- 7.0.0 与 6.0.2 均记录 "upgrade googleapis-common to 8.0.0";
- 4.1.3 记录 "update dependency googleapis-common to v7";
- 当前 package.json 依赖
googleapis-common: ^9.0.0。
googleapis-common 是承载 createAPIRequest、GoogleAuth、OAuth2Client、GaxiosResponseWithHTTP2 等核心机制的公共层(见 v1.ts 的 import 段),其主版本升级往往伴随传输层、类型定义或认证行为的兼容性变化,因此被视为破坏性变更。
3.3 与生成器(Generator)相关的破坏性发布
2.0.0、4.0.0、7.0.0、8.0.0、9.0.0、10.0.0、12.0.0 等版本均标注 "run the generator" / "This release has breaking changes"。这类发布对应仓库根目录的生成流水线(如 owlbot.py 与 src/generator 中的模板),会一次性重排所有子包的类型定义与代码结构。对使用者而言,这意味着升级后可能需要重新编译 TypeScript 项目(生成的 .d.ts 可能变化),并检查是否存在废弃字段。
四、按资源深入:v1 API 的结构与典型调用
结合 v1.ts 的类定义,v1 版本将 API 组织为两层资源树:
Realtimebidding
├── bidders
│ ├── creatives
│ ├── endpoints
│ ├── pretargetingConfigs
│ └── publisherConnections
└── buyers
├── creatives
└── userLists
顶层 Realtimebidding 类(v1.ts L113)在构造函数中实例化 Resource$Bidders 与 Resource$Buyers,每个资源类再挂载各自的子资源与方法。下面分别介绍核心资源的用途与关键 Schema。
4.1 bidders:竞价方账号管理
Resource$Bidders(v1.ts L1252)提供:
get:按名称获取 bidder 账号;list:分页列出 bidder。
Schema$Bidder 包含以下输出字段(Output only):
| 字段 | 含义 |
|---|---|
name |
资源名,格式 bidders/{bidderAccountId} |
cookieMatchingNetworkId |
用于 cookie 匹配的 google_nid 参数 |
cookieMatchingUrl |
cookie 匹配请求的 base URL |
bypassNonguaranteedDealsPretargeting |
是否绕过非保证交易的 pretargeting |
dealsBillingId |
交易 pretargeting 配置的计费 ID |
示例调用(来自 v1.ts 的 JSDoc 示例):
const {google} = require('googleapis');
const realtimebidding = google.realtimebidding('v1');
const auth = new google.auth.GoogleAuth({
scopes: ['https://www.googleapis.com/auth/realtime-bidding'],
});
const authClient = await auth.getClient();
google.options({auth: authClient});
const res = await realtimebidding.bidders.get({
// Required. Format: `bidders/{bidderAccountId}`
name: 'bidders/my-bidder',
});
console.log(res.data);
4.2 bidders.endpoints:竞价端点与 QPS 配额
Resource$Bidders$Endpoints(v1.ts L1897)管理 bidder 的接收端点,提供 get、list、patch 方法。QPS 配额通过 pretargeting 配置中的 maximumQps 字段约束(见下文),端点本身用于接收来自 Google 的竞价请求。
4.3 bidders.pretargetingConfigs:预定向配置(核心)
Resource$Bidders$Pretargetingconfigs(v1.ts L2374)是 v1 中方法最丰富的资源,提供:
activate/suspend:激活 / 挂起配置;create/get/list/patch/delete:配置的增删改查;addTargetedApps/addTargetedPublishers/addTargetedSites:新增定向目标;removeTargetedApps/removeTargetedPublishers/removeTargetedSites:移除定向目标。
Schema$PretargetingConfig(v1.ts L962)的定向维度非常丰富,核心字段如下:
| 字段 | 作用 |
|---|---|
appTargeting |
定向 App 库存(最多 30,000 个 App ID),含类别与 App 两级子定向 |
webTargeting |
定向站点库存(最多 50,000 个 URL) |
publisherTargeting |
定向 publisher(最多 10,000 个 ads.txt / app-ads.txt 发布者 ID) |
geoTargeting |
地理定向(含/排除) |
includedEnvironments |
广告环境(如 APP / WEB) |
includedFormats / includedCreativeDimensions |
素材格式与尺寸 |
includedLanguages / includedMobileOperatingSystemIds |
语言与移动操作系统 |
includedPlatforms / includedUserIdTypes |
设备平台与用户标识类型 |
interstitialTargeting |
插屏广告定向 |
verticalTargeting / userListTargeting |
垂直行业与再营销名单定向 |
excludedContentLabelIds |
排除的敏感内容标签 |
minimumViewabilityDecile |
最低可见度十分位(0–10,5 表示至少 50% 可预测可见度) |
maximumQps |
该配置匹配的竞价请求 QPS 上限 |
displayName |
配置显示名(同一 bidder 下必须唯一) |
state |
配置状态(ACTIVE 等,Output only) |
billingId |
计费标识(Output only) |
值得注意的是 addTargetedApps 等请求要求:若目标列表已存在,传入的 targetingMode 必须与现有 PretargetingConfig.appTargeting.mobileAppTargeting.targetingMode 一致,否则返回 400 bad request(见 Schema$AddTargetedAppsRequest 注释)。这是实操中常见的错误来源。
4.4 bidders.publisherConnections:发布者连接审批
Open Bidding 场景下,publisher 会主动向 bidder 发起连接请求,由 bidder 审批。Resource$Bidders$Publisherconnections(v1.ts L4707)提供:
batchApprove/batchReject:批量批准 / 拒绝连接;get/list:查看连接详情。
Schema$PublisherConnection 的 name 遵循模式 bidders/{bidder}/publisherConnections/{publisher},biddingState 表示发布者是否已被批准,publisherPlatform 标识 Ad Manager 或 AdMob(见 v1.ts L1056-L1080)。
4.5 buyers:买家账号与素材管理
Resource$Buyers(v1.ts L5372)提供 get、list、getRemarketingTag。Schema$Buyer 的关键字段包括:
activeCreativeCount:近 30 天通过 API 提交或参与竞价的素材数(计入活跃素材上限);maximumActiveCreativeCount:买家可拥有的最大活跃素材数;billingIds:用于竞价请求与响应归属的计费 ID 列表;bidder:负责接收该账号竞价流量的 bidder 资源名。
其子资源:
buyers.creatives(v1.ts L5822):素材的提交与审核状态查询。典型方法包括addDeals(将交易与素材关联并提交 publisher 审核,单次最多 100 个 deal ID)、create、get、list、watch(监听素材审批状态变化)等;buyers.userLists(v1.ts L6737):再营销用户名单管理,包含close、create、get、list、open、patch等方法。
Schema$Creative(v1.ts L329)是一个内容丰富的素材实体,包含 adChoicesDestinationUrl(仅原生广告支持)、advertiserName、creativeFormat、declaredAttributes、declaredClickThroughUrls、html、native、video、renderUrl、creativeServingDecision(素材服务决策,含审批状态)等字段。这些字段可直接用于 creatives.list 的过滤(如按 advertiserName 过滤)。
示例调用(buyers.creatives.addDeals,来自 v1.ts JSDoc):
const res = await realtimebidding.buyers.creatives.addDeals({
// Required. See creative.name.
name: 'buyers/my-buyer/creatives/my-creative',
requestBody: {
dealIds: ['1234567890'],
},
});
console.log(res.data);
五、安装与版本选择
5.1 安装方式
该子包支持两种安装方式:
- 独立安装(推荐按需使用):
npm install @googleapis/realtimebidding(见 README); - 随主包安装:
npm install googleapis,通过google.realtimebidding('v1')使用。
5.2 运行时要求与版本对应
| 子包版本范围 | 最低 Node 版本 | googleapis-common |
|---|---|---|
| < 4.0.0 | Node 10/12 | v5/v7 |
| 5.0.0 – 6.0.0 | Node 18 | 8.x |
| ≥ 7.0.0 | Node 18(7.x)/ Node 22(10.0.0+) | 8.0.0 → 9.0.0 |
截至 13.2.0,package.json 声明 engines.node >= 22.0.0、依赖 googleapis-common ^9.0.0。建议在升级前先阅读本文第四节的方法清单,对照目标版本的 v1.ts 确认所用方法与字段未被移除。
5.3 TypeScript 类型与编译
子包通过 npm run compile(tsc -p .)将 TS 源码编译到 build/,package.json 的 main 指向 build/index.js、types 指向 build/index.d.ts,因此可直接获得完整的类型提示。若需浏览器端使用,可通过 webpack.config.js 中配置的 npm run webpack 生成 dist/realtimebidding.min.js(该配置对 crypto、fs 等 Node 内置模块做了 fallback 处理,并用 null-loader 屏蔽 google-auth-library、gcp-metadata 等 Node 专用依赖)。
六、升级迁移实践建议
综合 CHANGELOG 与源码,升级 @googleapis/realtimebidding 时建议按以下清单操作:
- 检查 Node 版本:
node -v,确保 ≥ 22(针对 10.0.0 及以上版本); - 锁定 googleapis-common 版本:若项目直接依赖
googleapis-common,需与子包要求的^9.0.0对齐; - 核对破坏性标记:在 CHANGELOG 中检索 "BREAKING CHANGES",重点检查生成器重排("run the generator")相关的发布,重新运行 TypeScript 编译以捕获类型变更;
- 验证方法签名:以 v1.ts 为准,确认
params与options的用法;所有方法均支持 Promise(async/await)与回调两种风格; - 关注字段变更:Discovery 驱动生成意味着字段可能被弃用(如
PretargetingConfig.allowedUserTargetingModes已标记 Deprecated,见 v1.ts L962-L966),升级后应清理对这些字段的依赖; - 关注 OAuth 行为:认证层随
googleapis-common主版本升级而变化,建议在升级后回归测试使用GoogleAuth、OAuth2Client、JWT、Compute、UserRefreshClient等认证客户端的场景(这些类型均从googleapis-common导入,见 v1.ts L20-L35)。
七、结语
@googleapis/realtimebidding 的 CHANGELOG 既是一部 Google RTB 客户端能力的演进史,也是一份完整的升级指南:从 Node 12 到 Node 22 的两次基线跃迁、googleapis-common 的两次主版本升级,以及持续跟随 Discovery 文档的 API 刷新,共同构成了使用该子包时需要把握的节奏。结合 v1.ts 中的资源树与 Schema 定义,开发者可以高效地完成 bidder/endpoint 管理、pretargeting 配置、creative 提交审批与 publisher connection 审批等 RTB 集成工作,并在每次主版本升级时做到有的放矢。