google-api-nodejs-client 的 apikeys 子包:从 CHANGELOG 读懂版本演进、破坏性变更与 v2 API 全貌
google-api-nodejs-client 的 apikeys 子包:从 CHANGELOG 读懂版本演进、破坏性变更与 v2 API 全貌
导读
src/apis/apikeys/ 是 google-api-nodejs-client 仓库中负责 Google Cloud API Keys 服务的独立子包,其 CHANGELOG.md 记录了该包从 1.0.0 到 13.0.1 的完整发布历史。本文以这份变更日志为骨架,逐条拆解其中的破坏性变更(BREAKING CHANGES)、Node.js 版本门槛的演进脉络与 API 更新节奏,并结合仓库中的 v2.ts、index.ts、package.json 与 discovery/apikeys-v2.json 等源码与元数据,还原 @googleapis/apikeys 包背后的 API Keys v2 REST 接口全貌。读完本文,你将掌握如何解读这份变更日志、判断某个版本升级是否会影响你的应用,以及该子包实际暴露的完整方法面与数据模型。
一、关联文档定位:一份「发布史即 API 演进史」的变更日志
在 google-api-nodejs-client 这个单体仓库中,每个 API 子包都拥有独立的 CHANGELOG.md、README.md、package.json 与生成源码。apikeys 子包对应 Google Cloud 的 API Keys API,官方描述为"Manages the API keys associated with developer projects"(管理开发者项目关联的 API 密钥),以 npm 包名 @googleapis/apikeys 独立发布,当前仓库版本为 13.0.1(见 package.json)。
与普通手写文档不同,这份 CHANGELOG 由 release-please 与代码生成流水线自动产出,因此它精确记录了每次发版的时间、类型(feature / bug fix / breaking change)与触发原因,是可以反推出 API 演进路线的一手资料。其时间跨度从 2023-08-17 的 1.0.0 一路延伸到 2026-09-23 的 13.0.1,恰好覆盖了 API Keys v2 接口从初版发布到 2026 年的全部迭代。
注:该包在 README.md 中被标注为 maintenance mode(维护模式)。README 明确建议新应用改用 Google 官方提供的
@google-cloud/apikeys库,本包则继续服务于已有存量应用。这也是解读这份变更日志时必须先了解的背景。
二、CHANGELOG 内容总览:全量版本清单
为完整继承原文档信息,先将 CHANGELOG.md 中全部版本按时间倒序整理如下(提交哈希均出自原文档,在此仅作记录,不附外部链接):
| 版本 | 日期 | 类型 | 核心变更 |
|---|---|---|---|
| 13.0.1 | 2026-09-23 | Bug Fixes | apikeys 更新 API(630a4fd) |
| 13.0.0 | 2026-09-14 | ⚠ BREAKING / Features | 再次将 apiary 最低 Node 版本提升至 22,波及全部包(#4020,4e5bae0) |
| 12.0.0 | 2026-09-10 | ⚠ BREAKING / Features / Bug Fixes | 最低 Node 版本提升至 22(#4011);apikeys 三次更新 API(0316790 / 602fdeb / e212177);运行生成器;升级依赖至 Node 22 |
| 11.0.0 | 2026-09-10 | ⚠ BREAKING / Features / Bug Fixes | 最低 Node 版本提升至 22(#4011);加回 Node 18 支持 |
| 10.0.0 | 2026-09-09 | ⚠ BREAKING / Features / Bug Fixes | 最低 Node 版本提升至 22;更新 API;运行生成器;升级依赖至 Node 22;加回 Node 18 支持 |
| 9.1.1 | 2026-09-09 | Bug Fixes | 加回 Node 18 支持(eccac1d) |
| 9.1.0 | 2026-09-02 | Features / Bug Fixes | 运行生成器(#3992,5f7d438);升级依赖至 Node 22(de9d20d) |
| 9.0.0 | 2026-08-31 | ⚠ BREAKING / Features | apikeys 更新 API(0316790 / 602fdeb / e212177);运行生成器(#3955) |
| 8.2.0 | 2026-08-28 | Features | apikeys 更新 API(0316790) |
| 8.1.0 | 2026-08-14 | Features | apikeys 更新 API(602fdeb) |
| 8.0.0 | 2026-08-03 | ⚠ BREAKING / Features | 运行生成器(#3955,c429a9b) |
| 7.0.0 | 2026-05-19 | ⚠ BREAKING / Features | apikeys 更新 API(e212177) |
| 6.0.0 | 2026-01-28 | ⚠ BREAKING / Features | apikeys 更新 API(43eff2a) |
| 5.0.1 | 2025-12-05 | Bug Fixes | apikeys 更新 API(998bb0e) |
| 5.0.0 | 2025-10-15 | ⚠ BREAKING / Features | 运行生成器(#3814,4ba19d0) |
| 4.0.0 | 2025-09-16 | ⚠ BREAKING / Bug Fixes | 为库统一发版(#3769);升级 googleapis-common 至 8.0.0(#3731) |
| 3.0.1 | 2025-07-08 | Bug Fixes | apikeys 更新 API(ec54b77) |
| 3.0.0 | 2025-06-30 | ⚠ BREAKING / Features / Bug Fixes | 升级至 Node 18(682fbb8);更新 API(a25ed5a);依赖 googleapis-common 8.0.2-rc |
| 2.0.1 | 2025-06-04 | Bug Fixes | 依赖升级 googleapis-common 8.0.2-rc(f4b0990) |
| 2.0.0 | 2025-05-29 | ⚠ BREAKING / Features | 升级至 Node 18(682fbb8) |
| 1.1.0 | 2025-02-04 | Features | apikeys 更新 API(49e5f04) |
| 1.0.7 | 2024-08-16 | Bug Fixes | apikeys 更新 API(6fd74d0) |
| 1.0.6 | 2024-08-16 | Bug Fixes | apikeys 更新 API(6fd74d0) |
| 1.0.5 | 2024-05-02 | Bug Fixes | apikeys 更新 API(f2ab501) |
| 1.0.4 | 2024-05-02 | Bug Fixes | apikeys 更新 API(f2ab501) |
| 1.0.3 | 2023-10-11 | Bug Fixes | 依赖 googleapis-common 升级至 v7(9491ec1) |
| 1.0.2 | 2023-08-25 | Bug Fixes | 依赖 googleapis-common 升级至 v7(9491ec1) |
| 1.0.1 | 2023-08-17 | Bug Fixes | apikeys 更新 API(18e475b) |
| 1.0.0 | 2023-08-17 | Bug Fixes | apikeys 更新 API(18e475b) |
另有一处记录上的特殊条目:1.0.0 (2025-08-07) 出现在 1.0.5 与 3.0.1 之间(见 CHANGELOG.md)。这是 release-please 在历史版本整理时产生的时间戳回填现象,其内容(apikeys 更新 API、googleapis-common 8.0.0)与 1.0.x 系列一致,读者按 1.0.x 系列理解即可,不影响变更语义。
三、破坏性变更的两条主线:Node 版本门槛与 API Schema 更新
纵观全表,"⚠ BREAKING CHANGES" 几乎贯穿每个大版本,其成因可归纳为两条清晰主线:
3.1 Node.js 最低版本门槛的两次跃升
这是影响面最大的破坏性来源,时间线为:
- 2025-05-29(2.0.0)与 2025-06-30(3.0.0):将最低 Node 版本从 16 升级至 18,对应提交 682fbb8;
- 2026-09-02(9.1.0)起:生成包依赖逐步升级至 Node 22(de9d20d),随后 9.1.1 / 10.0.0 / 11.0.0 出现"加回 Node 18 支持"(eccac1d)的过渡性修复;
- 2026-09-14(13.0.0):将 apiary(生成工具链)最低 Node 版本再次提升至 22(#4020,4e5bae0),并明确标注"all packages"——即全仓库所有子包统一执行。
这一演进在 package.json 中有最直接的落点:当前 engines.node 为 >=22.0.0。对使用者而言,升级到 13.x 之前必须先确认运行环境的 Node 主版本满足要求,否则将直接触发 npm 的 engines 校验失败。
3.2 由上游 Discovery 文档驱动的 API 更新
另一类破坏性变更来自服务端 API 本身的 Schema 变化,CHANGELOG 中以 "apikeys: update the API" 形式出现的提交(如 0316790、602fdeb、e212177、43eff2a、630a4fd 等)即为此类。它的产生机制是:上游 API 的 Discovery 文档更新后,仓库通过生成器重新生成 v2.ts,再以 feature 或 breaking change 形式发版。由于 API Keys 服务端的字段增减、参数标注(如 required / optional)变化都会导致客户端类型定义变化,TypeScript 用户升级后可能出现类型不兼容,这是需要特别留意的兼容性风险点。
四、由 CHANGELOG 反推的 API 全貌:apikeys v2 的资源与方法面
CHANGELOG 中的 "update the API" 条目本身不披露细节,但仓库源码完整保留了当前 API 面,可作为解读这些更新的基准。
4.1 包入口与版本注册
src/apis/apikeys/index.ts 是子包入口,它从 googleapis-common 引入 getAPI / AuthPlus 等基础设施,注册了唯一版本 v2:
export const VERSIONS = {
v2: apikeys_v2.Apikeys,
};
使用时可通过 google.apikeys('v2') 或直接 new apikeys({version: 'v2'}) 方式实例化(见 v2.ts 中 Options 接口与构造函数)。
4.2 三层资源结构与八个核心方法
从 v2.ts 的 Apikeys 类可以看到,客户端暴露了三个顶层资源:keys、operations、projects,其中 projects 下再嵌套 locations → keys(v2.ts)。与 discovery/apikeys-v2.json 中的 REST 定义逐一对应,完整方法清单如下:
| 资源路径 | 方法 | HTTP 端点(REST) | 返回类型 |
|---|---|---|---|
keys.lookupKey |
GET v2/keys:lookupKey |
V2LookupKeyResponse(v2.ts) |
|
operations.get |
GET v2/{+name} |
Operation(v2.ts) |
|
projects.locations.keys.create |
POST v2/{+parent}/keys |
Operation(v2.ts) |
|
projects.locations.keys.get |
GET v2/{+name} |
V2Key(v2.ts) |
|
projects.locations.keys.getKeyString |
GET v2/{+name}/keyString |
V2GetKeyStringResponse(v2.ts) |
|
projects.locations.keys.list |
GET v2/{+parent}/keys |
V2ListKeysResponse(v2.ts) |
|
projects.locations.keys.patch |
PATCH v2/{+name} |
Operation(v2.ts) |
|
projects.locations.keys.delete |
DELETE v2/{+name} |
Operation(v2.ts) |
|
projects.locations.keys.undelete |
POST v2/{+name}:undelete |
Operation(v2.ts) |
几点值得注意的细节:
- create / delete / patch / undelete 均返回
Schema$Operation长时任务对象,而非直接返回V2Key。这是 API Keys 服务采用异步资源操作模型的体现,客户端需要配合operations.get轮询任务完成状态(done字段为false表示仍在进行,见 v2.ts)。 - keyString(密钥明文)永远不会出现在常规读接口中:
get、list的响应均不含密钥值,只有专用的getKeyString才返回"加密并签名后的密钥值"(Schema$V2GetKeyStringResponse.keyString,v2.ts)。 - Key 是全局资源:所有接口都注明
location唯一支持值为global,资源名形如projects/{project}/locations/global/keys/{keyId}(v2.ts)。 - 删除有 30 天软删除窗口:
delete说明文档指出删除后 30 天内可恢复,之后将被彻底清除;list支持showDeleted参数把近 30 天内删除的 key 一并列出(v2.ts)。
4.3 核心数据模型:V2Key 与 V2Restrictions
Schema$V2Key(v2.ts)是管理对象的核心,字段包括:
displayName:可修改的人类可读名称,最大长度 63 字符;annotations:非查询性的任意键值元数据,修改对象时应保留;etag:服务端校验和,用于 update / delete 时的乐观并发控制(详见 AIP-154 语义,源码注释中给出);restrictions:密钥使用限制(见下);serviceAccountEmail:密钥绑定的服务账号邮箱(可选);- 只读字段:
createTime/deleteTime/updateTime、uid(UUID4)、keyString、name。
Schema$V2Restrictions(v2.ts)定义了四类限制,对应密钥的四种应用场景:
| 限制类型 | Schema | 允许字段 |
|---|---|---|
| Android | V2AndroidKeyRestrictions |
allowedApplications[],内含 packageName 与 sha1Fingerprint(两种格式均接受:DA:39:...:09 或 DA39A3...D80709,输出统一为后者) |
| iOS | V2IosKeyRestrictions |
allowedBundleIds[](Bundle ID 列表) |
| 浏览器 | V2BrowserKeyRestrictions |
allowedReferrers[](Referrer URL 正则表达式列表) |
| 服务器 | V2ServerKeyRestrictions |
allowedIps[](调用方 IP 地址列表) |
另有 apiTargets(V2ApiTarget<a href="https://link.gitcode.com/i/0cb58f0cba2f4af8133cecabd039894e" target="_blank">],[v2.ts)用于将密钥限定到特定服务与方法:service 使用规范服务名(如 translate.googleapis.com),methods 为空表示允许该服务的全部方法,支持 Get*、translate.googleapis.com.Get* 这类通配写法。语义上"请求命中任一限制即被放行;若未指定任何限制,则全部目标均被允许"(v2.ts)。
4.4 方法级参数细节(来自 Params 接口)
create.keyId:可选的自定义 ID,须匹配正则a-z?,不能是 UUID 形态,长度上限 63(v2.ts);patch.updateMask:字段掩码,可修改字段为display_name、restrictions、annotations;缺省时按 wire 上设置的允许字段隐式处理,特殊值"*"表示替换全部可修改字段(v2.ts);delete/patch均支持checkExistingUsage(定义检查既有使用行为)与etag(乐观并发);list.pageSize/pageToken/showDeleted用于分页与软删除过滤(v2.ts);lookupKey.keyString:传入密钥明文,反向查找其所属项目与资源名,若密钥已被彻底清除则name为空(v2.ts)。
五、认证与授权:OAuth 2.0 作用域全集
所有 apikeys 方法都需要 OAuth 2.0 或服务账号凭证,这在 discovery/apikeys-v2.json 与源码示例中保持一致。可用的作用域共四个:
| Scope | 权限描述 |
|---|---|
https://www.googleapis.com/auth/apikeys |
查看、编辑、配置和删除你的 Google Cloud API Keys 数据 |
https://www.googleapis.com/auth/apikeys.readonly |
只读查看你的 Google Cloud API Keys 数据 |
https://www.googleapis.com/auth/cloud-platform |
查看、编辑、配置和删除 Google Cloud 数据 |
https://www.googleapis.com/auth/cloud-platform.read-only |
只读查看 Google Cloud 服务数据 |
在 v2.ts 的每个方法示例中可以看到完整调用范式:先通过 google.auth.GoogleAuth 构造认证客户端并指定 scopes,再通过 google.options({auth: authClient}) 绑定全局,最后调用具体方法。例如 lookupKey 的典型用法:
const {google} = require('googleapis');
const apikeys = google.apikeys('v2');
async function main() {
const auth = new google.auth.GoogleAuth({
scopes: [
'https://www.googleapis.com/auth/apikeys',
'https://www.googleapis.com/auth/apikeys.readonly',
'https://www.googleapis.com/auth/cloud-platform',
'https://www.googleapis.com/auth/cloud-platform.read-only',
],
});
const authClient = await auth.getClient();
google.options({auth: authClient});
const res = await apikeys.keys.lookupKey({
keyString: 'your-api-key-string', // 必填:查找拥有该密钥值的项目
});
console.log(res.data);
// 期望响应: { name: "projects/.../keys/...", parent: "projects/..." }
}
写操作类方法(create / patch / delete / undelete)通常只需 apikeys 与 cloud-platform 两个作用域,只读方法(get / list / getKeyString / lookupKey / operations.get)还可选用两个只读 scope,源码中的示例注释已按此区分。
六、安装、环境要求与升级实践
6.1 安装与最低环境
独立安装该子包:
npm install @googleapis/apikeys
当前 package.json 表明:包主入口为 build/index.js(编译产物),类型声明为 build/index.d.ts,运行时依赖 googleapis-common@^9.0.0,engines 要求 Node.js >= 22.0.0。若希望随整个 google-api-nodejs-client 一起使用,也可以直接 npm install googleapis 后通过 google.apikeys('v2') 调用。仓库同时提供了 webpack.config.js 与 webpack 脚本,供浏览器端打包场景使用。
6.2 依据 CHANGELOG 制定升级策略
结合前文的两条破坏性变更主线,升级决策可以简化为两步判断:
- 先看运行时:目标版本的
engines.node是否与你的 Node 环境匹配。2.x / 3.x 要求 Node 18,13.x 要求 Node 22,中间 9.1.x~12.x 存在"加回 Node 18 支持"的过渡状态,若停留在 Node 18 可优先选择这些过渡版本或更早版本; - 再看类型面:大版本中的 "apikeys: update the API" 条目意味着 Schema 类型可能变化,TypeScript 项目升级后应重新执行类型检查,重点核对
V2Key/V2Restrictions相关字段是否仍在。
此外,README 已声明该库处于维护模式,官方推荐新项目评估迁移至 @google-cloud/apikeys(详见 README.md);存量项目则可继续锁定本包版本,并定期关注 CHANGELOG.md 中标注 ⚠ 的条目来判断是否触发升级。
七、结语:一份变更日志的完整解读闭环
src/apis/apikeys/CHANGELOG.md 的价值在于:它把版本号、Node 环境门槛、服务端 Schema 变更与生成器流水线四者绑定在一起,构成了 apikeys 子包最权威的演进档案。结合仓库内的 index.ts(入口注册)、v2.ts(完整方法面与数据模型)、package.json(版本与环境约束)以及 discovery/apikeys-v2.json(REST 元数据),任何开发者都能从"该不该升级、升级什么、升级后 API 长什么样"三个层面快速定位答案。这也是 Google API 客户端生成式仓库中,以 CHANGELOG 为抓手理解子包技术面的通用方法论。