google-api-nodejs-client 的 bigquerydatapolicy 包：从版本演进看 BigQuery 数据策略 API 的完整开发指南

• 后端

导读

本文以 Google 官方 Node.js 客户端库google-api-nodejs-client中bigquerydatapolicy子包（对应 CHANGELOG.md）为核心线索，系统梳理该包自 2023 年 11 月首次发布以来 22 个版本的演进脉络、破坏性变更与 API 更新节奏，并结合 v1.ts、v2.ts 与 package.json 的源码级证据，深入讲解 BigQuery Data Policy API 的资源层级、核心数据模型、IAM 集成与细粒度访问控制（grantees）。读完本文，你将掌握@googleapis/bigquerydatapolicy的安装、版本选择、v1/v2 全部方法调用方式，以及从变更日志中预判升级风险的能力。

一、bigquerydatapolicy 包是什么

bigquerydatapolicy是google-api-nodejs-client仓库中为BigQuery Data Policy API（官方描述：Allows users to manage BigQuery data policies）自动生成的子包。该 API 的核心能力是让用户对 BigQuery 中的数据列施加数据策略（Data Policy），典型场景包括：

• 数据脱敏（Data Masking）：通过DataMaskingPolicy为敏感列绑定预定义或自定义脱敏规则，控制不同角色读取到的数据形态；
• 细粒度访问控制（Fine-Grained Access）：在 v2 中通过grantees字段精确授权某个 IAM 主体对受策略保护数据的读取权限；
• IAM 策略管理：基于getIamPolicy/setIamPolicy/testIamPermissions方法对数据策略资源本身进行权限治理。

从仓库结构看，该子包位于 src/apis/bigquerydatapolicy，由index.ts统一导出 v1、v2 两个 API 版本（见 index.ts 中的VERSIONS映射），每个版本对应一个自动生成的 TypeScript 源码文件。

1.1 维护状态与替代库（重要提醒）

README.md 明确说明：Google 为该服务提供了多个库，@googleapis/bigquerydatapolicy处于维护模式（maintenance mode）——官方会继续为已有应用提供该库，但新应用建议改用@google-cloud/bigquery-datapolicies。官方给出的理由是后者更快、更易用且维护更积极。

这一点对读者非常重要：如果你正在新项目选型，请优先考虑@google-cloud/bigquery-datapolicies；如果你需要维护既有代码或研究自动生成库的机制，则继续阅读本文。

1.2 安装

$ npm install @googleapis/bigquerydatapolicy

安装后即可在代码中通过googleapis统一入口或独立包方式使用：

const {google} = require('googleapis'); const bigquerydatapolicy = google.bigquerydatapolicy('v1'); // 或 'v2'

二、版本演进全览：22 个版本的核心脉络

CHANGELOG.md 完整记录了该包从 0.1.0（2023-11-27）到 9.0.1（2026-09-23）的全部发布历史。下表按文件记录顺序整理（注：变更日志中存在个别版本号在文件顺序上非严格递增的现象，这是 release-please 批量补录早期版本所致，属正常的生成库维护行为）：

2.1 三条并行的演进主线

从上表可以提炼出该包的三种变更来源：

1. **bigquerydatapolicy:** update the API：这是最频繁的条目，代表 Google 端 discovery 文档更新后，自动生成器同步刷新了方法签名、Schema 与文档注释。这类变更通常不破坏兼容性，属于日常演进；
2. run the generator/regenerate index files：生成器本身升级（例如新增 API 版本、调整生成模板）后全量重新生成；
3. BREAKING CHANGES：影响升级安全性的节点版本要求调整与依赖升级，详见下一节。

三、破坏性变更：Node 版本要求的历史波动

该包生命周期内共出现 5 次明确标记的 BREAKING CHANGES，其中 4 次与Node.js 最低版本要求直接相关，这是升级时最先需要检查的兼容性门槛：

值得注意的细节是，2026-09 期间出现了一组快速迭代：6.0.0/7.0.0/8.0.0 在同一天（09-09 与 09-10）集中发布，其中 8.0.0 同时包含"升级到 Node 22"的破坏性变更与"add back support for node 18"的修复条目——这表明团队在收紧 Node 22 要求后曾短暂补回 Node 18 支持，最终在 9.0.0（2026-09-14）落地为所有包统一要求 Node 22，并在 9.0.1 继续以 API 更新收尾。

当前状态可以从 package.json 直接验证：

{ "name": "@googleapis/bigquerydatapolicy", "version": "9.0.1", "engines": { "node": ">=22.0.0" }, "dependencies": { "googleapis-common": "^9.0.0" } }

即：当前 9.0.1 版本要求 Node.js ≥ 22.0.0，依赖googleapis-common^9.0.0。如果你的 CI/部署环境仍停留在 Node 18 或 20，升级到 8.x/9.x 前必须先行调整运行时。

四、源码视角：v1 与 v2 的资源层级与方法清单

bigquerydatapolicy包同时暴露v1与v2两个 API 版本（见 index.ts 的VERSIONS导出）。两者共享相同的资源层级：

projects └── locations └── dataPolicies

这一结构在 v1.ts 中体现为三个嵌套的资源类：Resource$Projects→Resource$Projects$Locations→Resource$Projects$Locations$Datapolicies（v2.ts 结构相同）。

4.1 方法对照表

（方法与端点的对应关系可在 v1.ts 与 v2.ts 中逐方法核对，例如 v1 的create指向rootUrl + '/v1/{+parent}/dataPolicies'，v2 的addGrantees指向rootUrl + '/v2/{+dataPolicy}:addGrantees'。）

4.2 核心数据模型

两个版本共享DataPolicy与DataMaskingPolicy两个核心 Schema，但 v2 在字段上做了显著扩展：

Schema$DataPolicy（v1 版，见 v1.ts）：

v2 版在 v1 基础上新增（见 v2.ts）：

• dataGovernanceTag：绑定到数据策略的数据治理标签（Data Governance Tag）；
• grantees：仅 v2 支持。拥有细粒度访问权限的 IAM 主体列表，使用 IAM V2 主体语法，支持user、group、serviceaccount、cloudidentity等主体类型；v1 策略（version = 1且设置了policy_tag）不填充该字段；
• etag：用于UpdateDataPolicy调用的乐观并发控制，更新时必须匹配服务端 etag；
• version：输出字段，数据策略资源的版本号。

Schema$DataMaskingPolicy（两个版本一致）：通过二选一的字段指定脱敏规则——

• predefinedExpression：预定义脱敏表达式（如 SHA256 哈希、邮件脱敏等）；
• routine：自定义脱敏例程，格式为projects/{project_number}/datasets/{dataset_id}/routines/{routine_id}。

4.3 版本差异的业务含义

从源码结构可以推断 v1 → v2 的设计演进方向：v1 以"策略标签 + 脱敏策略"的经典组合实现列级保护；v2 引入细粒度访问控制（Fine-Grained Access），通过grantees字段和addGrantees/removeGrantees两个专属方法，允许在数据策略层面直接管理"谁能读"的主体清单，配合dataGovernanceTag实现更现代化的治理模型。这与 Google 官方在 README.md 中"新应用改用@google-cloud/bigquery-datapolicies"的建议方向一致——新库正是围绕 v2 能力设计的。

五、实战：v1 数据策略的增删改查与 IAM

以下代码均直接取自 v1.ts 中生成的内嵌示例，确保与仓库实际 API 签名一致。

5.1 创建数据策略（create）

create用于在指定项目位置下创建新的数据策略（v1 中要求同时给出dataPolicyId、策略标签与策略类型，见 v1.ts）：

const {google} = require('googleapis'); const bigquerydatapolicy = google.bigquerydatapolicy('v1'); async function main() { const auth = new google.auth.GoogleAuth({ scopes: [ 'https://www.googleapis.com/auth/bigquery', 'https://www.googleapis.com/auth/cloud-platform', ], }); const authClient = await auth.getClient(); google.options({auth: authClient}); const res = await bigquerydatapolicy.projects.locations.dataPolicies.create({ // Required. 父资源名，格式为 projects/{project_number}/locations/{location_id} parent: 'projects/my-project/locations/my-location', requestBody: { dataPolicyId: 'my_dataPolicyId', dataPolicyType: 'my_dataPolicyType', policyTag: 'my_policyTag', dataMaskingPolicy: {}, // 具体脱敏规则 }, }); console.log(res.data); } main().catch(e => { console.error(e); throw e; });

5.2 列出数据策略（list）

list支持filter、pageSize与pageToken三个分页/过滤参数（见 v1.ts）：

const res = await bigquerydatapolicy.projects.locations.dataPolicies.list({ // 目前仅支持基于 policy_tag 的过滤与 OR 谓词，如 // "policy_tag: projects/1/locations/us/taxonomies/2/policyTags/3" // 也支持通配符 "policy_tag: projects/1/locations/us/taxonomies/2*" filter: 'placeholder-value', // 每页条数，1~1000，默认 50 pageSize: '50', // 上一页返回的 nextPageToken pageToken: 'placeholder-value', parent: 'projects/my-project/locations/my-location', });

响应体Schema$ListDataPoliciesResponse由dataPolicies数组与nextPageToken组成（见 v1.ts），nextPageToken为空即表示已到末页。

5.3 更新元数据（patch）

patch更新已有数据策略的元数据，支持allowMissing与updateMask（见 v1.ts）：

const res = await bigquerydatapolicy.projects.locations.dataPolicies.patch({ // 若为 true 且策略不存在，则新建策略（此时忽略 update_mask） allowMissing: 'placeholder-value', name: 'projects/my-project/locations/my-location/dataPolicies/my-dataPolicie', // FieldMask，未设置时默认更新所有允许更新的字段； // 注意 name 与 dataPolicyId 字段不允许通过本方法修改 updateMask: 'placeholder-value', requestBody: { dataMaskingPolicy: {}, }, });

5.4 重命名（rename）

v1 独有的rename方法通过Schema$RenameDataPolicyRequest的newDataPolicyId字段修改策略 ID（见 v1.ts 与 v1.ts）。

5.5 IAM 三件套

三个 IAM 方法均以资源名（{+resource}）为路径参数，对应端点如 v1.ts 所示：

• getIamPolicy：读取数据策略资源的 IAM 策略。可传入GetPolicyOptions.requestedPolicyVersion（合法值 0、1、3）请求特定策略版本；
• setIamPolicy：写入完整策略。请求体Schema$SetIamPolicyRequest包含policy（完整 Policy 对象）与可选的updateMask（未设置时默认paths: "bindings, etag"，见 v1.ts）；
• testIamPermissions：校验调用者对指定资源是否拥有某些权限（permissions字段不支持通配符）。

重要 IAM 细节（来自Schema$Policy与Schema$Binding的字段注释，见 v1.ts）：

• Policy.etag用于乐观并发控制，强烈建议采用"读取 etag → 修改 → 携带 etag 写回"的 read-modify-write 循环，避免并发覆盖；
• 如果使用 IAM Conditions，调用setIamPolicy时必须携带etag，否则可能用 version 1 的策略覆盖 version 3 的策略，导致条件绑定全部丢失；
• Policy.version合法值为 0、1、3，任何影响条件角色绑定的操作必须指定 version 3；
• Binding.members支持allUsers、user:{emailid}、serviceAccount:{emailid}、group:{emailid}、domain:{domain}以及工作负载/工作力身份池（workforce/workload identity pools）等一整套主体标识语法。

六、实战：v2 细粒度访问控制

v2 的独特价值在于Fine-Grained Access。在创建/更新数据策略时（dataPolicyType需配合相应类型），可通过DataPolicy.grantees字段声明具备细粒度访问权限的 IAM 主体（使用 IAM V2 主体语法，仅支持 user、group、serviceaccount、cloudidentity 四类主体）。

6.1 批量添加授权主体（addGrantees）

const {google} = require('googleapis'); const bigquerydatapolicy = google.bigquerydatapolicy('v2'); async function main() { const auth = new google.auth.GoogleAuth({ scopes: ['https://www.googleapis.com/auth/cloud-platform'], }); const authClient = await auth.getClient(); google.options({auth: authClient}); const res = await bigquerydatapolicy.projects.locations.dataPolicies.addGrantees({ // 目标数据策略资源名 dataPolicy: 'projects/my-project/locations/my-location/dataPolicies/my-dataPolicie', requestBody: { // 新授权主体；重复的 grantee 会被忽略 grantees: ['user:alice@example.com', 'group:analysts@example.com'], }, }); console.log(res.data); }

该方法的语义在 v2.ts 的注释中有明确说明：新授权主体会追加到已有 grantees 集合；若请求包含重复主体或已存在的主体，对应主体将被忽略。请求体 Schema 见 v2.ts。

6.2 批量移除授权主体（removeGrantees）

removeGrantees与addGrantees对称：从已有 grantees 集合中移除指定主体；若请求包含不存在的 grantee，该主体同样会被忽略（见 v2.ts）。

6.3 v2 的并发控制：etag

v2 的DataPolicy带有etag字段（见 v2.ts）：调用更新类操作时若策略已存在，该字段必填且必须与服务端 etag 匹配；getDataPolicy、createDataPolicy、updateDataPolicy的响应中都会返回最新 etag。这要求应用在"读-改-写"流程中缓存并回传 etag，与前述 IAM 的 etag 机制一脉相承。

七、请求参数与认证基础

所有方法都继承一组标准查询参数（两个版本一致，见 v1.ts）：

认证推荐方式与 v1 示例一致：通过GoogleAuth获取客户端并绑定到全局google.options({auth: authClient})。运行前需在 Google Cloud Console 启用bigquerydatapolicy.googleapis.comAPI，并可用gcloud auth application-default login配置本地凭据。

八、升级建议与维护总结

综合 CHANGELOG.md 的破坏性变更记录，给出以下升级检查清单：

1. Node 运行时：9.x 要求 Node ≥ 22.0.0（package.json 中的engines字段）；从旧版本升级前先确认运行环境；
2. 依赖版本：3.0.0 起googleapis-common升级到 8.0.0，当前 9.0.1 使用^9.0.0，升级时注意与仓库根 package.json 的版本对齐；
3. API 语义变化：频繁的update the API条目意味着方法签名与 Schema 会随上游 discovery 文档演进，建议升级后回归验证create/patch的请求体字段；
4. v1 → v2 差异：若从 v1 迁移到 v2，需注意rename方法在 v2 中不存在（v2 使用patch+name更新），且 v2 新增grantees、dataGovernanceTag、etag、version字段与addGrantees/removeGrantees方法；
5. 长期选型：按 README.md 的建议，新项目直接使用@google-cloud/bigquery-datapolicies，既有应用可继续使用本包。

从变更日志的节奏看，该包自 2023 年底首发以来保持每月至数月一次的发布频率，其中 API 更新与生成器重建是最稳定的变更来源，Node 版本要求则是影响升级决策的关键变量——掌握这些规律，即可在升级@googleapis/bigquerydatapolicy时从容应对。

相关仓库资源

• 子包变更日志（本文核心依据）
• 子包说明文档（安装、维护状态说明）
• 子包 package.json（版本、Node 引擎与依赖声明）
• 入口文件 index.ts（v1/v2 版本导出与工厂函数）
• v1 自动生成源码（v1 全部方法、Schema 与内嵌示例）
• v2 自动生成源码（v2 细粒度访问控制方法、Schema）

• 后端