★ FEATURED ARTICLE 后端【免费下载链接】google-api-nodejs-clientGoogles officially supported Node.js client library for accessing Google APIs. Support for authorization and authentication with OAuth 2.0, API Keys and JWT (Service Tokens) is included.项目地址https://gitcode.com/gh_mirrors/go/google-api-nodejs-client点击查看免费下载导读本文以 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.02023-11-27到 9.0.12026-09-23的全部发布历史。下表按文件记录顺序整理注变更日志中存在个别版本号在文件顺序上非严格递增的现象这是 release-please 批量补录早期版本所致属正常的生成库维护行为版本发布日期类型关键内容9.0.12026-09-23Bug Fixes更新 APIcommit b9f190b9.0.02026-09-14BREAKING Feature所有包最低 Node 版本恢复为 22#40208.0.02026-09-10BREAKING Features Fixes最低 Node 22#4011重新运行 generator更新 API7.0.02026-09-10BREAKING最低 Node 22#4011同时补回 Node 18 支持6.0.02026-09-09BREAKING最低 Node 22更新 API5.1.12026-09-09Bug Fixes补回 Node 18 支持5.1.02026-09-02Feature Fix运行 generator#3992依赖升级到 Node 225.0.02026-08-03BREAKING运行 generator#3955、#39594.2.02026-05-19Features更新 API重新生成 index 文件4.1.12025-12-05Bug Fixes更新 APIcommit c0993614.1.02025-10-20Feature运行 generator#38204.0.02025-10-15BREAKING运行 generator#38143.0.02025-09-16BREAKING Fixes发布流程调整#3769googleapis-common升级到 8.0.01.0.22025-08-21Bug Fixes更新 APIgoogleapis-common8.0.01.0.12025-08-13Bug Fixes更新 APIgoogleapis-common8.0.01.0.02025-08-07Bug Fixes更新 APIgoogleapis-common8.0.02.0.12025-07-08Bug Fixes更新 APIcommit adc491f2.0.02025-06-30BREAKING最低 Node 版本升级到 18更新 API1.0.12025-06-04Bug Fixesgoogleapis-common升级到 8.0.2-rc1.0.02025-05-29BREAKING最低 Node 版本升级到 180.2.12025-05-05Bug Fixes更新 API0.2.02024-08-16Features更新 APIcommit 9ccae460.1.22024-05-02Bug Fixes更新 API0.1.12024-02-02Bug Fixes更新 API0.1.02023-11-27首发初始版本2.1 三条并行的演进主线从上表可以提炼出该包的三种变更来源**bigquerydatapolicy:** update the API这是最频繁的条目代表 Google 端 discovery 文档更新后自动生成器同步刷新了方法签名、Schema 与文档注释。这类变更通常不破坏兼容性属于日常演进run the generator/regenerate index files生成器本身升级例如新增 API 版本、调整生成模板后全量重新生成BREAKING CHANGES影响升级安全性的节点版本要求调整与依赖升级详见下一节。三、破坏性变更Node 版本要求的历史波动该包生命周期内共出现 5 次明确标记的 BREAKING CHANGES其中 4 次与Node.js 最低版本要求直接相关这是升级时最先需要检查的兼容性门槛版本变更说明1.0.0 / 2.0.02025-05-29 / 2025-06-30upgrade to node 18最低 Node 版本提升到 18低于 18 的运行时不再受支持6.0.0 / 7.0.0 / 8.0.0 / 9.0.02026-09minimum Node version of 22最低 Node 版本提升到 22涉及全部生成包#4011、#4020值得注意的细节是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.02026-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$Datapoliciesv2.ts 结构相同。4.1 方法对照表方法v1v2对应 HTTP 端点create✅✅POST /v1/{parent}/dataPolicies/POST /v2/{parent}/dataPolicieslist✅✅GET /v1/{parent}/dataPolicies/GET /v2/{parent}/dataPoliciesget✅✅GET /v1/{name}/GET /v2/{name}patch更新元数据✅✅PATCH /v1/{name}/PATCH /v2/{name}delete✅✅DELETE /v1/{name}/DELETE /v2/{name}rename✅❌POST /v1/{name}:renamegetIamPolicy✅✅POST /v1/{resource}:getIamPolicy/POST /v2/{resource}:getIamPolicysetIamPolicy✅✅POST /v1/{resource}:setIamPolicy/POST /v2/{resource}:setIamPolicytestIamPermissions✅✅POST /v1/{resource}:testIamPermissions/POST /v2/{resource}:testIamPermissionsaddGrantees❌✅POST /v2/{dataPolicy}:addGranteesremoveGrantees❌✅POST /v2/{dataPolicy}:removeGrantees方法与端点的对应关系可在 v1.ts 与 v2.ts 中逐方法核对例如 v1 的create指向rootUrl /v1/{parent}/dataPoliciesv2 的addGrantees指向rootUrl /v2/{dataPolicy}:addGrantees。4.2 核心数据模型两个版本共享DataPolicy与DataMaskingPolicy两个核心 Schema但 v2 在字段上做了显著扩展Schema$DataPolicyv1 版见 v1.ts字段类型说明dataPolicyIdstring用户可读 ID项目内唯一用作资源名中的{data_policy_id}dataPolicyTypestring必填。策略类型如DATA_MASKING_POLICYnamestring输出字段。资源名格式projects/{project_number}/locations/{location_id}/dataPolicies/{data_policy_id}policyTagstring策略标签资源名格式projects/{project_number}/locations/{location_id}/taxonomies/{taxonomy_id}/policyTags/{policyTag_id}dataMaskingPolicyDataMaskingPolicy数据脱敏规则v2 版在 v1 基础上新增见 v2.tsdataGovernanceTag绑定到数据策略的数据治理标签Data Governance Taggrantees仅 v2 支持。拥有细粒度访问权限的 IAM 主体列表使用 IAM V2 主体语法支持user、group、serviceaccount、cloudidentity等主体类型v1 策略version 1且设置了policy_tag不填充该字段etag用于UpdateDataPolicy调用的乐观并发控制更新时必须匹配服务端 etagversion输出字段数据策略资源的版本号。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 创建数据策略createcreate用于在指定项目位置下创建新的数据策略v1 中要求同时给出dataPolicyId、策略标签与策略类型见 v1.tsconst {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 列出数据策略listlist支持filter、pageSize与pageToken三个分页/过滤参数见 v1.tsconst 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.tsnextPageToken为空即表示已到末页。5.3 更新元数据patchpatch更新已有数据策略的元数据支持allowMissing与updateMask见 v1.tsconst 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 重命名renamev1 独有的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.tstestIamPermissions校验调用者对指定资源是否拥有某些权限permissions字段不支持通配符。重要 IAM 细节来自Schema$Policy与Schema$Binding的字段注释见 v1.tsPolicy.etag用于乐观并发控制强烈建议采用读取 etag → 修改 → 携带 etag 写回的 read-modify-write 循环避免并发覆盖如果使用 IAM Conditions调用setIamPolicy时必须携带etag否则可能用 version 1 的策略覆盖 version 3 的策略导致条件绑定全部丢失Policy.version合法值为 0、1、3任何影响条件角色绑定的操作必须指定 version 3Binding.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 批量添加授权主体addGranteesconst {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:aliceexample.com, group:analystsexample.com], }, }); console.log(res.data); }该方法的语义在 v2.ts 的注释中有明确说明新授权主体会追加到已有 grantees 集合若请求包含重复主体或已存在的主体对应主体将被忽略。请求体 Schema 见 v2.ts。6.2 批量移除授权主体removeGranteesremoveGrantees与addGrantees对称从已有 grantees 集合中移除指定主体若请求包含不存在的 grantee该主体同样会被忽略见 v2.ts。6.3 v2 的并发控制etagv2 的DataPolicy带有etag字段见 v2.ts调用更新类操作时若策略已存在该字段必填且必须与服务端 etag 匹配getDataPolicy、createDataPolicy、updateDataPolicy的响应中都会返回最新 etag。这要求应用在读-改-写流程中缓存并回传 etag与前述 IAM 的 etag 机制一脉相承。七、请求参数与认证基础所有方法都继承一组标准查询参数两个版本一致见 v1.ts参数说明auth认证客户端或 API Key支持 OAuth2Client、JWT、Compute、UserRefreshClient、BaseExternalAccountClient、GoogleAuth$.xgafvV1 错误格式access_tokenOAuth 访问令牌alt响应数据格式callbackJSONP 回调fields部分响应时选择返回哪些字段keyAPI Key标识项目并提供配额与报告未提供 OAuth 2.0 令牌时必填oauth_token当前用户的 OAuth 2.0 令牌prettyPrint是否带缩进与换行返回响应quotaUser用于服务端应用配额目的的任意字符串不超过 40 字符uploadType/upload_protocol媒体上传相关参数认证推荐方式与 v1 示例一致通过GoogleAuth获取客户端并绑定到全局google.options({auth: authClient})。运行前需在 Google Cloud Console 启用bigquerydatapolicy.googleapis.comAPI并可用gcloud auth application-default login配置本地凭据。八、升级建议与维护总结综合 CHANGELOG.md 的破坏性变更记录给出以下升级检查清单Node 运行时9.x 要求 Node ≥ 22.0.0package.json 中的engines字段从旧版本升级前先确认运行环境依赖版本3.0.0 起googleapis-common升级到 8.0.0当前 9.0.1 使用^9.0.0升级时注意与仓库根 package.json 的版本对齐API 语义变化频繁的update the API条目意味着方法签名与 Schema 会随上游 discovery 文档演进建议升级后回归验证create/patch的请求体字段v1 → v2 差异若从 v1 迁移到 v2需注意rename方法在 v2 中不存在v2 使用patchname更新且 v2 新增grantees、dataGovernanceTag、etag、version字段与addGrantees/removeGrantees方法长期选型按 README.md 的建议新项目直接使用google-cloud/bigquery-datapolicies既有应用可继续使用本包。从变更日志的节奏看该包自 2023 年底首发以来保持每月至数月一次的发布频率其中 API 更新与生成器重建是最稳定的变更来源Node 版本要求则是影响升级决策的关键变量——掌握这些规律即可在升级googleapis/bigquerydatapolicy时从容应对。相关仓库资源子包变更日志本文核心依据子包说明文档安装、维护状态说明子包 package.json版本、Node 引擎与依赖声明入口文件 index.tsv1/v2 版本导出与工厂函数v1 自动生成源码v1 全部方法、Schema 与内嵌示例v2 自动生成源码v2 细粒度访问控制方法、Schema赞分享后端【免费下载链接】google-api-nodejs-clientGoogles officially supported Node.js client library for accessing Google APIs. Support for authorization and authentication with OAuth 2.0, API Keys and JWT (Service Tokens) is included.项目地址https://gitcode.com/gh_mirrors/go/google-api-nodejs-client点击查看免费下载相关推荐google-api-nodejs-client 中的 bigquerydatapolicy 模块用 Node.js 管理 BigQuery 数据策略的完整实战指南google api nodejs client 中的 bigquerydatapolicy 模块用 Node.js 管理 BigQuery 数据策略的完整实后端深入解析 google-api-nodejs-client 的 manufacturers 模块从 CHANGELOG 看 API 演进、版本策略与实战接入深入解析 google api nodejs client 的 manufacturers 模块从 CHANGELOG 看 API 演进、版本策略与实战接入后端google-api-nodejs-client analytics 子包版本演进全解析从 CHANGELOG 看 Google Analytics API Node.js 客户端的变化史google api nodejs client analytics 子包版本演进全解析从 CHANGELOG 看 Google Analytics API后端创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
阅读完成 · 觉得有帮助？
