google-api-nodejs-client 之 Analytics Hub API 客户端库完全指南:数据交换、Listing 与订阅实战
google-api-nodejs-client 之 Analytics Hub API 客户端库完全指南:数据交换、Listing 与订阅实战
导读
本文围绕 google-api-nodejs-client 仓库中 Analytics Hub API(analyticshub)的客户端库展开,该库用于"安全高效地交换数据与分析资产"(Exchange data and analytics assets securely and efficiently)。你将掌握如何在 Node.js 项目中安装并初始化该客户端、完成 OAuth 2.0 认证、调用 Data Exchange、Listing、Subscription 等核心资源的方法,并了解该库当前的维护状态与官方推荐的迁移方向,以及其底层自动生成代码的实现结构。
Analytics Hub 是什么,这个库的定位与支持状态
Analytics Hub(Google Cloud Analytics Hub API)是 Google 提供的用于跨组织共享数据与分析资产的托管平台:数据提供方可以将 BigQuery 数据集、Pub/Sub Topic、存储过程等发布为 Listing,订阅方通过订阅机制安全地访问这些资产。在 google-api-nodejs-client 中,它对应独立的 API 客户端模块 analyticshub。
仓库中的关联文档 src/apis/analyticshub/README.md 明确给出了支持状态,这是使用前必须了解的事实:
- Google 为该服务提供了多套库,本库(
googleapis全家桶内的@googleapis/analyticshub)目前处于维护模式(maintenance mode),仅面向已有存量应用的用户持续可用; - 如果你在构建新应用或改造旧应用,官方推荐改用
@google-cloud/bigquery-analyticshub(Google Cloud Node.js 客户端库),官方文档称其"更快、更易用、维护更好"; - 详细说明可参见 Google Cloud 官方文档中关于客户端库选择的说明(Client Libraries Explained 为外部页面,此处仅作背景)。
也就是说:存量项目可以放心继续使用本模块;新项目建议评估迁移到 BigQuery 专用客户端库。本文后续的所有安装、代码示例与源码解析,均基于当前仓库中维护的 analyticshub 模块展开。
安装:两种方式任选
依据 src/apis/analyticshub/README.md 与仓库根目录 README.md 的说明,有两种安装路径:
方式一:安装整个 googleapis 主包(包含全部 API)
$ npm install googleapis
这种方式将所有 Google API 客户端一并装入,初始化时按需加载,适合需要同时使用多个 API 的场景。
方式二:仅安装 analyticshub 子模块(按需依赖)
$ npm install @googleapis/analyticshub
从 src/apis/analyticshub/package.json 可以看到,该独立包的当前版本为 24.1.1,其唯一运行时依赖为 googleapis-common(^9.0.0),并要求 Node.js >=22.0.0。独立安装可以显著缩小依赖体积、减少启动时间,适合只使用 Analytics Hub 一个 API 的项目。
初始化与认证:Scope 与两种调用入口
该 API 需要的 OAuth 2.0 Scope
根据发现文档 discovery/analyticshub-v1.json 中 auth.oauth2.scopes 的定义,调用 Analytics Hub API 需要以下两个 scope 之一(或全部):
| Scope | 含义 |
|---|---|
https://www.googleapis.com/auth/bigquery |
查看并管理 Google BigQuery 中的数据,同时可看到 Google 账号邮箱 |
https://www.googleapis.com/auth/cloud-platform |
查看、编辑、配置并删除 Google Cloud 数据,可看到账号邮箱 |
在 src/apis/analyticshub/v1.ts 中每个方法的示例代码都默认携带这两个 scope,例如 organizations.locations.dataExchanges.list、dataExchanges.create、listings.create、subscriptions.delete 等方法的 JSDoc 示例均如此。
入口一:从 googleapis 主包加载
const {google} = require('googleapis');
const analyticshub = google.analyticshub('v1');
入口二:直接使用独立子模块
const {analyticshub} = require('@googleapis/analyticshub');
const client = analyticshub('v1');
从 src/apis/analyticshub/index.ts 的源码可以看到,analyticshub() 是一个工厂函数,支持以版本字符串('v1' / 'v1beta1')或 Options 对象作为入参,内部通过 getAPI('analyticshub', versionOrOptions, VERSIONS, this) 完成客户端装配;同时导出了 AuthPlus、GlobalOptions、GoogleConfigurable 等 googleapis-common 的类型与工具。
认证示例:GoogleAuth + Application Default Credentials
以 src/apis/analyticshub/v1.ts 中每个方法 JSDoc 内嵌的官方示例为骨架,标准认证流程如下:
const {google} = require('googleapis');
const analyticshub = google.analyticshub('v1');
async function main() {
const auth = new google.auth.GoogleAuth({
// 可以数组形式指定,也可以单个空格分隔的字符串
scopes: [
'https://www.googleapis.com/auth/bigquery',
'https://www.googleapis.com/auth/cloud-platform',
],
});
// 获取 auth client,并绑定到后续所有调用
const authClient = await auth.getClient();
google.options({auth: authClient});
// Do the magic
const res = await analyticshub.organizations.locations.dataExchanges.list({
organization: 'organizations/my-organization/locations/my-location',
pageSize: 'placeholder-value',
pageToken: 'placeholder-value',
});
console.log(res.data);
}
main().catch(e => {
console.error(e);
throw e;
});
前提条件(源码 JSDoc 中同样注明):
- 在 Google Cloud Console 启用
analyticshub.googleapis.comAPI; - 执行
gcloud auth application-default login完成本地凭据登录; - 安装依赖模块。
资源层级与方法全景:从 v1.ts 看客户端结构
src/apis/analyticshub/v1.ts(共 7351 行)是自动生成的完整类型定义与实现,顶层 Analyticshub 类挂载了 organizations 与 projects 两个一级资源,方法与 REST 路径一一对应。核心资源树如下:
Analyticshub
├── organizations
│ └── locations
│ └── dataExchanges.list
└── projects
└── locations
├── dataExchanges
│ ├── create / delete / get / patch / list
│ ├── getIamPolicy / setIamPolicy / testIamPermissions
│ ├── subscribe / listSubscriptions
│ └── listings
│ ├── create / delete / get / patch / list
│ ├── getIamPolicy / setIamPolicy / testIamPermissions
│ ├── subscribe / listSubscriptions
│ └── (Listing 下的关联操作)
│ └── queryTemplates
│ ├── approve / submit / create / delete / get / list / patch
└── subscriptions
├── delete / get / list / patch
├── getIamPolicy / setIamPolicy
└── refresh / revoke
按资源整理的方法与请求参数
organizations.locations.dataExchanges(按组织维度列出数据交换):
| 方法 | HTTP | 路径模板 | 必填参数 |
|---|---|---|---|
list |
GET | /v1/{+organization}/dataExchanges |
organization |
| 可选参数 | — | — | pageSize、pageToken |
organization 形如 organizations/myorg/locations/us(见 v1.ts#L1597 的路径拼接与 v1.ts#L1614-L1627 的参数接口)。
projects.locations.dataExchanges(项目维度数据交换 CRUD 与订阅):
| 方法 | HTTP | 必填参数 | 说明 |
|---|---|---|---|
create |
POST | parent、dataExchangeId |
创建数据交换,dataExchangeId 仅允许 Unicode 字母、数字、下划线,最长 100 字节(v1.ts#L1701-L1723) |
get / delete / patch |
GET/DELETE/PATCH | name |
数据交换资源名,如 projects/myproject/locations/us/dataExchanges/123 |
list |
GET | parent |
支持 pageSize / pageToken 分页 |
getIamPolicy / setIamPolicy / testIamPermissions |
POST | resource |
IAM 策略管理 |
subscribe |
POST | name |
订阅整个数据交换,返回 Schema$Operation(异步操作) |
listSubscriptions |
GET | resource |
列出某个数据交换的全部订阅 |
projects.locations.dataExchanges.listings(Listing 级操作):
| 方法 | HTTP | 必填参数 | 说明 |
|---|---|---|---|
create |
POST | parent、listingId |
parent 形如 projects/myproject/locations/us/dataExchanges/123;listingId 同样最长 100 字节(v1.ts#L3362-L3396) |
get / delete / patch |
— | name |
如 projects/123/locations/us/dataExchanges/456/listings/789 |
list |
GET | parent |
分页返回 Schema$ListListingsResponse |
subscribe |
POST | name |
订阅单个 Listing |
getIamPolicy / setIamPolicy / testIamPermissions |
— | resource |
IAM 策略管理 |
listSubscriptions |
GET | resource |
查看该 Listing 的订阅情况 |
projects.locations.dataExchanges.queryTemplates(查询模板管理):
| 方法 | 说明 |
|---|---|
approve |
批准查询模板 |
submit |
提交查询模板 |
create / delete / get / list / patch |
查询模板的标准 CRUD |
projects.locations.subscriptions(订阅生命周期管理):
| 方法 | 说明 |
|---|---|
delete |
删除订阅,返回 Schema$Operation(v1.ts#L6236-L6303) |
get / list |
查询单个 / 分页列出订阅 |
refresh |
刷新订阅(更新链接资源) |
revoke |
撤销订阅 |
getIamPolicy / setIamPolicy |
订阅的 IAM 策略 |
核心数据模型:DataExchange / Listing / Subscription
自动生成的 Schema 类型同样定义在 src/apis/analyticshub/v1.ts 中,写请求体时可直接对照。
DataExchange(数据交换,v1.ts#L359-L400)
| 字段 | 类型 | 说明 |
|---|---|---|
displayName |
string(必填) | 人类可读名称,仅允许 Unicode 字母、数字、下划线、连字符、空格、&,不能以空格开头/结尾,最长 63 字节 |
description |
string | 描述,不能包含 Unicode 非字符及 C0/C1 控制码(Tab/LF/CR/FF 除外),最长 2000 字节 |
documentation |
string | 数据交换的文档说明 |
icon |
string(base64) | 图标图片,Base64 编码,最大 3.0 MiB,预期尺寸 512×512 像素 |
primaryContact |
string | 主要联系人邮箱或 URL,最长 1000 字节 |
discoveryType |
string | 发现页类型;更新该字段会同步覆盖该交换下所有 Listing 的 discovery_type |
sharingEnvironmentConfig |
SharingEnvironmentConfig |
数据共享环境配置,可区分默认交换与 Data Clean Room(DCR)交换 |
listingCount |
number(输出) | 该交换包含的 Listing 数量 |
logLinkedDatasetQueryUserEmail |
boolean | 是否启用邮箱共享强制(email sharing mandate) |
name |
string(输出) | 资源名,如 projects/myproject/locations/us/dataExchanges/123 |
Listing(数据资产列表项,v1.ts#L729-L814)
关键字段包括:displayName、description、documentation、icon、primaryContact、categories(分类)、state(状态)、discoveryType、resourceType(共享资产类型,如 BigQuery Dataset / Pub/Sub Topic)、requestAccess、allowOnlyMetadataSharing(仅共享元数据)、restrictedExportConfig,以及承载具体资产内容的配置对象:
bigqueryDataset:BigQuery 数据集引用(含dataset、table、restrictedExportConfig等);pubsubTopic:Pub/Sub Topic;storedProcedureConfig:存储过程配置;dataProvider/publisher:数据提供方与发布方信息(name、primaryContact);commercialInfo:商业信息(商业订阅相关)。
Subscription(订阅,v1.ts#L1341-L1402)
| 字段 | 类型 | 说明 |
|---|---|---|
name |
string(输出) | 订阅资源名,如 projects/myproject/locations/us/subscriptions/123 |
dataExchange / listing |
string(输出) | 源数据交换 / 源 Listing 的资源名 |
destinationDataset |
DestinationDataset |
为订阅者创建的 BigQuery 目标数据集(含 datasetReference、friendlyName、description、labels、location) |
linkedDatasetMap |
map(输出) | Listing 资源名到关联数据集名的映射,如 projects/123/.../listings/789 -> projects/123/datasets/my_dataset;仅 state == STATE_ACTIVE 时有值 |
linkedResources |
LinkedResource[](输出) |
订阅中创建的链接资源列表 |
state |
string(输出) | 订阅状态 |
resourceType |
string(输出) | 被共享资产的类型 |
creationTime / lastModifyTime |
string(输出) | 创建 / 最后修改时间戳 |
organizationId / organizationDisplayName |
string(输出) | 订阅所属组织的 ID 与显示名 |
subscriberContact |
string(输出) | 订阅者邮箱 |
logLinkedDatasetQueryUserEmail |
boolean(输出) | 订阅者是否同意邮箱共享强制 |
其中 DestinationDataset(v1.ts#L460-L478)在调用 subscribe 时由订阅方指定,是"订阅后资产落在哪个数据集"的关键配置。
实战:一个完整的数据交换 + Listing + 订阅流程
将上述 API 串起来,一个典型流程是:数据提供方创建 Data Exchange → 在其中发布 Listing → 订阅方订阅 Listing → 通过订阅管理查看与撤销。以下代码基于 v1.ts 中各方法的真实参数编写:
const {google} = require('googleapis');
const analyticshub = google.analyticshub('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 parent = 'projects/my-project/locations/us';
// 1) 创建 Data Exchange
const dx = await analyticshub.projects.locations.dataExchanges.create({
parent,
dataExchangeId: 'my_exchange',
requestBody: {
displayName: 'My Analytics Exchange',
description: 'Securely shared analytics assets',
primaryContact: 'owner@example.com',
},
});
const dxName = dx.data.name;
console.log('DataExchange:', dxName);
// 2) 在 Exchange 下发布 Listing(共享一个 BigQuery Dataset)
const listing = await analyticshub.projects.locations.dataExchanges.listings.create({
parent: dxName,
listingId: 'my_listing',
requestBody: {
displayName: 'Revenue Dashboard Dataset',
description: 'Daily aggregated revenue tables',
resourceType: 'BIGQUERY_DATASET',
bigqueryDataset: {
dataset: 'projects/my-project/datasets/revenue_daily',
},
},
});
const listingName = listing.data.name;
console.log('Listing:', listingName);
// 3) 订阅该 Listing(订阅方指定目标数据集)
const sub = await analyticshub.projects.locations.dataExchanges.listings.subscribe({
name: listingName,
requestBody: {
destinationDataset: {
datasetReference: {
datasetId: 'subscriber_copy',
projectId: 'subscriber-project',
},
location: 'us',
},
},
});
console.log('Subscribe operation:', sub.data);
// 4) 列出订阅并撤销
const subs = await analyticshub.projects.locations.dataExchanges.listSubscriptions({
resource: dxName,
});
console.log(subs.data.subscriptions);
const revoke = await analyticshub.projects.locations.subscriptions.revoke({
name: subs.data.subscriptions[0].name,
});
console.log('Revoked:', revoke.data);
}
main().catch(e => {
console.error(e);
throw e;
});
几点实战注意:
subscribe返回的是Schema$Operation(异步长任务),需要轮询操作状态确认完成;- 订阅状态仅
STATE_ACTIVE时linkedDatasetMap/linkedResources才有值(见 v1.ts#L1363-L1369); - Data Clean Room(DCR)场景下,
SharingEnvironmentConfig会限定"每个 Cleanroom 只创建一个链接数据集"或"每个 Listing 一个数据集"等行为(见 v1.ts#L417-L426 的DcrExchangeConfig)。
版本支持:v1 与 v1beta1
src/apis/analyticshub/index.ts 中的 VERSIONS 常量同时导出了两个版本:
export const VERSIONS = {
v1: analyticshub_v1.Analyticshub,
v1beta1: analyticshub_v1beta1.Analyticshub,
};
v1:稳定版本,上述所有资源与方法均在此版本实现(src/apis/analyticshub/v1.ts);v1beta1:Beta 版本(src/apis/analyticshub/v1beta1.ts),资源层级与 v1 基本一致(同样含organizations.locations.dataExchanges与projects.locations.dataExchanges.listings),适合提前试用新能力,但接口可能有破坏性变更。
调用时通过 google.analyticshub('v1') 或 google.analyticshub('v1beta1') 显式选择版本。
从源码看实现原理:自动生成的客户端如何工作
analyticshub 模块的代码(index.ts、v1.ts、v1beta1.ts)均为自动生成产物(v1.ts 头部标注 THIS FILE IS AUTO-GENERATED),其生成源是 discovery/analyticshub-v1.json 与 discovery/analyticshub-v1beta1.json 两份 Discovery Document。理解这一点有助于你把握客户端的几个底层事实:
-
REST 端点由 Discovery Document 决定:
baseUrl为https://analyticshub.googleapis.com/(并支持analyticshub.mtls.googleapis.com的 mTLS 端点);每个方法实现中通过options.rootUrl || 'https://analyticshub.googleapis.com/'拼出最终 URL(如 v1.ts#L1583-L1600),且requiredParams/pathParams决定了哪些参数必须提供、哪些参数会写入路径模板。 -
请求统一由
createAPIRequest转发:所有方法最终都调用googleapis-common的createAPIRequest(见 v1.ts#L1601-L1610),并支持回调风格与 Promise 风格两种调用方式(每个方法都重载了callback与Promise两种签名),也支持StreamMethodOptions以流式获取响应。 -
参数接口全部强类型化:每个方法都有对应的
Params$Resource$...接口(继承StandardParameters),StandardParameters(v1.ts#L43-L100)统一支持auth、key、access_token、fields、prettyPrint、quotaUser等全局参数,其中auth可接受OAuth2Client、JWT、Compute、UserRefreshClient、GoogleAuth等多种凭据形态。 -
类型与实现同文件:
Schema$*接口(DataExchange、Listing、Subscription、QueryTemplate、Operation等)与资源类、参数接口全部内联在同一文件,方便直接导入使用,例如:
import {analyticshub_v1} from '@googleapis/analyticshub';
type DataExchange = analyticshub_v1.Schema$DataExchange;
- 认证能力随模块导出:
index.ts末尾导出了AuthPlus以及GlobalOptions、APIRequestContext、BodyResponseCallback等googleapis-common类型,使得独立安装的子模块同样具备完整的认证工具链。
License 与获取帮助
- 该库基于 Apache 2.0 许可发布,完整许可文本见仓库根目录 LICENSE;
- 模块的
package.json中声明author为 Google LLC、license为Apache-2.0(见 src/apis/analyticshub/package.json); - 版本变更记录可查阅 src/apis/analyticshub/CHANGELOG.md;
- 如需参与贡献,仓库根目录的 CONTRIBUTING.md 与 CODE_OF_CONDUCT.md 提供了完整指引。
小结
google-api-nodejs-client 中的 analyticshub 模块为 Node.js 开发者提供了完整的 Analytics Hub API 调用能力:覆盖 v1 / v1beta1 两个版本,资源树包含组织维度与项目维度的 Data Exchange、Listing、Query Template、Subscription 全生命周期操作,并内置 IAM 策略管理与订阅刷新/撤销等高级能力。使用前请务必留意其维护模式状态——存量应用可继续基于 src/apis/analyticshub/v1.ts 中沉淀的强类型接口稳定运行,而新建项目则应按官方建议评估迁移到 @google-cloud/bigquery-analyticshub。无论选择哪条路径,本文给出的认证流程、资源方法映射表与实战示例,都能帮助你快速在 Node.js 中打通"发布数据资产 → 订阅 → 管理订阅"的完整链路。