google-api-nodejs-client 的 realtimebidding 子包:版本演进、破坏性变更与 RTB 集成实战

原创2026-10-15 09:52:131,996 阅读
文章标签:后端

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 安装方式

该子包支持两种安装方式:

  1. 独立安装(推荐按需使用):npm install @googleapis/realtimebidding(见 README);
  2. 随主包安装: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 时建议按以下清单操作:

  1. 检查 Node 版本:node -v,确保 ≥ 22(针对 10.0.0 及以上版本);
  2. 锁定 googleapis-common 版本:若项目直接依赖 googleapis-common,需与子包要求的 ^9.0.0 对齐;
  3. 核对破坏性标记:在 CHANGELOG 中检索 "BREAKING CHANGES",重点检查生成器重排("run the generator")相关的发布,重新运行 TypeScript 编译以捕获类型变更;
  4. 验证方法签名:以 v1.ts 为准,确认 params 与 options 的用法;所有方法均支持 Promise(async/await)与回调两种风格;
  5. 关注字段变更:Discovery 驱动生成意味着字段可能被弃用(如 PretargetingConfig.allowedUserTargetingModes 已标记 Deprecated,见 v1.ts L962-L966),升级后应清理对这些字段的依赖;
  6. 关注 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 集成工作,并在每次主版本升级时做到有的放矢。

登录后查看全文
google-api-nodejs-client