google-api-nodejs-client 之 Analytics Hub API 客户端库完全指南:数据交换、Listing 与订阅实战

原创2026-10-14 18:28:481,391 阅读
文章标签:后端

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 中同样注明):

  1. 在 Google Cloud Console 启用 analyticshub.googleapis.com API;
  2. 执行 gcloud auth application-default login 完成本地凭据登录;
  3. 安装依赖模块。

资源层级与方法全景:从 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。理解这一点有助于你把握客户端的几个底层事实:

  1. 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 决定了哪些参数必须提供、哪些参数会写入路径模板。

  2. 请求统一由 createAPIRequest 转发:所有方法最终都调用 googleapis-common 的 createAPIRequest(见 v1.ts#L1601-L1610),并支持回调风格与 Promise 风格两种调用方式(每个方法都重载了 callback 与 Promise 两种签名),也支持 StreamMethodOptions 以流式获取响应。

  3. 参数接口全部强类型化:每个方法都有对应的 Params$Resource$... 接口(继承 StandardParameters),StandardParameters(v1.ts#L43-L100)统一支持 auth、key、access_token、fields、prettyPrint、quotaUser 等全局参数,其中 auth 可接受 OAuth2Client、JWT、Compute、UserRefreshClient、GoogleAuth 等多种凭据形态。

  4. 类型与实现同文件:Schema$* 接口(DataExchange、Listing、Subscription、QueryTemplate、Operation 等)与资源类、参数接口全部内联在同一文件,方便直接导入使用,例如:

import {analyticshub_v1} from '@googleapis/analyticshub';
type DataExchange = analyticshub_v1.Schema$DataExchange;
  1. 认证能力随模块导出:index.ts 末尾导出了 AuthPlus 以及 GlobalOptions、APIRequestContext、BodyResponseCallback 等 googleapis-common 类型,使得独立安装的子模块同样具备完整的认证工具链。

License 与获取帮助

小结

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 中打通"发布数据资产 → 订阅 → 管理订阅"的完整链路。

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