google-api-nodejs-client 中的 App Hub 客户端库:安装、认证与 App Hub API 使用指南

原创2026-10-14 17:20:171,617 阅读
文章标签:后端

google-api-nodejs-client 中的 App Hub 客户端库:安装、认证与 App Hub API 使用指南

App Hub 是 Google Cloud 上用于"构建、运行和管理应用程序"的服务,而本仓库 google-api-nodejs-client 中提供的 @googleapis/apphub 模块,则是官方支持的 Node.js 客户端库,用于以代码方式调用 App Hub API。本文以仓库中的 App Hub 模块文档 为主体,结合该模块的 入口源码 与 v1 API 类型定义 等实现细节,讲解如何在 Node.js 项目中安装、初始化、认证并调用 App Hub 的 Application、Service、Workload 等资源接口,帮助你快速上手这一官方维护的客户端库。

一、App Hub 是什么

App Hub 面向 Google Cloud 用户,提供"应用程序中心化治理"的能力:它允许你将分布在多个 Google Cloud 项目中的服务(Service)和工作负载(Workload)归入逻辑上的"应用程序"(Application)边界,并进行统一管理。用模块源码中的原话来说:

"App Hub lets you build, operate, and manage applications on Google Cloud."

在 API 层面,App Hub 通过一个 Application 定义其治理边界(governance boundary),支持应用级 IAM 权限以对齐治理需求。这一描述直接体现在 v1.ts 中 Schema$Application 的注释:

"Application defines the governance boundary for App Hub entities that perform a logical end-to-end business function. App Hub supports application level IAM permission to align with governance requirements."

也就是说,App Hub 的核心价值在于:把"业务应用"(如一套电商系统)映射为云端资源集合,将底层的 GKE 部署、托管实例组(MIG)等"工作负载"和网络接口"服务"统一注册、关联并治理。

二、支持状态:维护模式与官方替代库

在开始使用之前,必须明确该库当前的支持状态。根据 src/apis/apphub/README.md 的 Support status 章节,Google 针对 App Hub 服务提供了多个库:

  • 本仓库生成的 @googleapis/apphub 库目前处于 维护模式(maintenance mode),仍会继续提供给已有存量应用使用;
  • 如果你正在构建新应用,或希望现代化改造旧应用,Google 官方建议改用 @google-cloud/apphub(注:这是文档原文中的外部 npm 链接,此处仅作说明,不构成仓库内的可引用路径);
  • 官方称替代库"更快、更易用、维护更好"。

因此,本文介绍的是"存量项目继续使用本仓库模块"的完整用法;新项目建议评估官方推荐库。这一点属于文档明确的官方说明,是使用本库前最重要的决策前提。

三、安装

该模块以独立 npm 包的形式发布,安装命令与 README 安装章节 完全一致:

$ npm install @googleapis/apphub

如果你希望使用本仓库的聚合入口 googleapis(包含全部 Google API 客户端),则按照 v1.ts 中代码示例的注释 所示安装:

$ npm install googleapis

从模块自身的 package.json 可以确认如下运行时约束:

配置项 值 说明
包名 @googleapis/apphub 独立发布的 npm 包名
当前版本 13.0.1 详见 CHANGELOG.md
主入口 build/index.js 编译产物入口
类型声明 build/index.d.ts 提供 TypeScript 类型支持
运行时要求 Node.js >=22.0.0 engines 字段明确的最低 Node 版本
核心依赖 googleapis-common ^9.0.0 认证与请求基础设施
许可证 Apache-2.0 见 LICENSE

需要提醒的是,Node.js 版本要求经历了变化:CHANGELOG.md 记录了 v12.0.0、v13.0.0 等版本中"最小 Node 版本提升到 22"的破坏性变更,因此在使用新版本前请先确认运行环境的 Node 版本。

四、初始化与版本选择

App Hub API 客户端支持两个 API 版本:v1 与 v1alpha。这一点在 模块入口文件 index.ts 中有直接体现:

export const VERSIONS = {
  v1: apphub_v1.Apphub,
  v1alpha: apphub_v1alpha.Apphub,
};

入口函数 apphub() 接受两个参数形式:直接传版本字符串,或传 Options 配置对象。两种写法等价:

const {google} = require('googleapis');
const apphub = google.apphub('v1');
const apphub = google.apphub({version: 'v1'});

Options 接口在 v1.ts 中定义,它继承 GlobalOptions 并固定 version: 'v1'。若使用 v1alpha 版本,写法同理:google.apphub('v1alpha')。

从源码结构看,v1 与 v1alpha 两个版本的资源层次基本一致(均包含 applications、discoveredServices、discoveredWorkloads、operations 等),但 v1alpha 作为预发布版本可能包含尚未 GA 的接口,生产环境应优先使用 v1。

五、认证与授权

App Hub API 要求 Google Cloud 认证。从 v1.ts 中 StandardParameters 的 auth 定义 可以看出,客户端支持多种认证方式:

  • OAuth2Client:OAuth 2.0 客户端
  • JWT:服务账号令牌(Service Token)
  • Compute:GCE 元数据服务器认证
  • UserRefreshClient:用户刷新令牌
  • BaseExternalAccountClient:外部账号(如 Workload Identity Federation)
  • GoogleAuth:统一认证入口(推荐)
  • 或直接传字符串形式的 API Key(key 参数)

官方代码示例中推荐的认证方式是通过 GoogleAuth 获取客户端并绑定到全局请求,需要的 OAuth scope 为 https://www.googleapis.com/auth/cloud-platform。完整流程(摘自 v1.ts 的 create 方法示例):

const {google} = require('googleapis');
const apphub = google.apphub('v1');

async function main() {
  const auth = new google.auth.GoogleAuth({
    // Scopes 可以传数组,也可以传单个以空格分隔的字符串
    scopes: ['https://www.googleapis.com/auth/cloud-platform'],
  });

  // 获取认证客户端并绑定到所有后续请求
  const authClient = await auth.getClient();
  google.options({auth: authClient});

  // 后续即可调用 App Hub API
}

main().catch(e => {
  console.error(e);
  throw e;
});

在本地开发环境下,可通过 gcloud 建立应用默认凭证:

$ gcloud auth application-default login

同时需要先在 Google Cloud Console 中启用 App Hub API(apphub.googleapis.com,该 API 名称出现在 v1.ts 示例注释中)。

六、API 资源结构:从入口到具体接口

这是本库的核心使用地图。结合 v1.ts 与 v1alpha.ts 的类定义,App Hub 客户端的资源层次如下(调用时以点号逐级访问):

apphub.projects
└── .locations
    ├── .applications            // 应用程序资源
    │   ├── .services           // 应用下的服务
    │   └── .workloads          // 应用下的工作负载
    ├── .discoveredServices      // 已发现的未注册服务
    ├── .discoveredWorkloads     // 已发现的未注册工作负载
    ├── .extendedMetadataSchemas // 扩展元数据 Schema
    ├── .operations              // 长时运行操作
    └── .serviceProjectAttachments // 服务项目挂载

6.1 locations 级操作

projects.locations 资源(类定义)除聚合上述子资源外,还提供如下方法:

方法 作用
get 获取某个 Location 的信息
list 列出 host project 下的所有 Location
getBoundary / updateBoundary 获取/更新应用管理边界(Boundary 资源)
lookupServiceProjectAttachment 查询服务项目与宿主项目的挂载关系
detachServiceProjectAttachment 将服务项目从宿主项目解绑,可从任意服务项目调用,无需宿主项目权限

6.2 applications 资源

projects.locations.applications(类定义)是核心资源,支持:

  • create:在宿主项目与指定位置创建 Application(异步返回 Operation)
  • get:获取 Application 详情
  • list:列出 Application
  • patch:更新 Application
  • delete:删除 Application
  • getIamPolicy / setIamPolicy / testIamPermissions:应用级 IAM 权限管理

其中 create 方法的参数非常典型,可直接用于实战(摘自 v1.ts 示例):

const res = await apphub.projects.locations.applications.create({
  // Required. Application 标识符,仅含小写字母、数字或连字符,
  // 首字符必须是字母,末字符必须是字母或数字,最长 63 字符
  applicationId: 'my-app-id',
  // Required. 创建 Application 的项目与位置,
  // 格式: `projects/{project}/locations/{location}`
  parent: 'projects/my-project/locations/my-location',
  // Optional. 请求 ID,用于幂等重试,必须是有效 UUID
  requestId: 'placeholder-value',

  // 请求体
  requestBody: {
    displayName: 'my_displayName',
    description: 'my_description',
    scope: {type: 'REGIONAL'},
    attributes: {
      environment: {type: 'PRODUCTION'},
      criticality: {type: 'HIGH'},
    },
  },
});
console.log(res.data);

6.3 services 与 workloads 资源

applications.services(类定义)与 applications.workloads(类定义)各支持 create、get、list、patch、delete 五个方法,用于在 Application 边界内注册和管理服务与工作负载。它们的请求体都包含 discoveredService / discoveredWorkload(必填、不可变,指向已发现的原始资源名)以及可选的 attributes、displayName、description 等字段。

6.4 discovered 资源:注册前的查找

discoveredServices(类定义)与 discoveredWorkloads(类定义)用于在宿主项目中查找尚未注册的资源:

  • get / list:按资源名或列表方式获取已发现的资源
  • lookup:按底层资源 URI 精确定位某个已发现资源,例如在注册 Service 之前先用它拿到 DiscoveredService 的资源名

6.5 operations 与 serviceProjectAttachments

  • operations(类定义):提供 cancel、delete、get、list,用于管理 create / delete 等返回的长时运行操作(LRO);
  • serviceProjectAttachments(类定义):提供 create、get、list、delete,用于把服务项目挂载到宿主项目,挂载后宿主项目才能发现服务项目中的资源。

七、核心数据模型速查

从 v1.ts 的 Schema 定义 可以整理出 App Hub API 的主要数据模型:

Schema 关键字段与约束 说明
Schema$Application displayName(≤63 字符)、description(≤2048 字符)、scope(必填、不可变)、attributes、state、uid、createTime、updateTime 治理边界,资源名格式 projects/{host-project-id}/locations/{location}/applications/{application-id}
Schema$Attributes businessOwners、developerOwners、operatorOwners(均为 ContactInfo[])、criticality、environment 消费者自定义的业务属性
Schema$Criticality type(必填) 关键性等级
Schema$Environment type(必填) 环境类型
Schema$Scope type(必填) 定义 Application 可纳入的数据范围,限制可注册的 Service/Workload
Schema$Service discoveredService(必填、不可变)、serviceProperties、serviceReference、attributes、displayName、description、state 注册后的服务,资源名格式 .../applications/{application-id}/services/{service-id}
Schema$Workload discoveredWorkload(必填、不可变)、workloadProperties、workloadReference、attributes 注册后的工作负载
Schema$DiscoveredService / Schema$DiscoveredWorkload name、serviceProperties / workloadProperties、serviceReference / workloadReference 底层已发现资源,properties 与 reference 均为只读(Output only)
Schema$Operation name、metadata、done、error、response 长时运行操作的标准结构
Schema$ServiceProjectAttachment — 服务项目与宿主项目的挂载关系

一个典型的业务流如下:

  1. 用 serviceProjectAttachments.create 将服务项目挂载到宿主项目;
  2. 用 discoveredServices.lookup / discoveredWorkloads.lookup 找到要纳入的底层资源;
  3. 用 applications.create 创建 Application 边界(定义 scope 与 attributes);
  4. 用 applications.services.create、applications.workloads.create 将已发现资源注册进 Application;
  5. 用 operations.get 轮询各创建操作直到完成。

八、TypeScript 支持

本模块是 TypeScript 编写并自动生成的(v1.ts、v1alpha.ts 文件头部均标注 "THIS FILE IS AUTO-GENERATED"),发布包通过 build/index.d.ts 提供完整类型声明。类型安全体现在:

  • apphub() 函数针对 'v1' / 'v1alpha' 分别做了重载,返回对应的 Apphub 类实例(见 index.ts);
  • 每个方法都有对应的 Params$Resource$... 参数接口与 Schema$... 响应类型(如 Params$Resource$Projects$Locations$Applications$Create、Schema$Application);
  • 回调与 Promise 两种风格都支持:create 等方法的签名同时提供 BodyResponseCallback 重载与返回 Promise<GaxiosResponseWithHTTP2<T>> 的重载(见 v1.ts create 方法签名)。

因此,在 TypeScript 项目中使用时,requestBody、返回的 res.data 都会获得完整的字段提示与约束检查。

九、许可与参与贡献

该库遵循 Apache 2.0 许可证,完整许可证文本见仓库根目录的 LICENSE。仓库的 CONTRIBUTING.md 与 CODE_OF_CONDUCT.md 描述了贡献方式与行为准则,其中 README 特别强调:提交 Pull Request 之前,建议先创建 issue 进行沟通。相关讨论与问题反馈入口均收录在仓库根目录文档中(参见 README 的问题反馈章节)。

十、总结

@googleapis/apphub 是 google-api-nodejs-client 官方仓库中为 App Hub 服务生成的 Node.js 客户端,提供 v1 与 v1alpha 两个版本,覆盖 Application、Service、Workload、Discovered 资源、Operation、服务项目挂载与 IAM 等完整 API 面。虽然该库当前处于维护模式、新项目被官方引导迁移至 @google-cloud/apphub,但对于既有存量应用,它依然是稳定、可用且类型完备的调用方案:安装 @googleapis/apphub、通过 google.apphub('v1') 初始化、使用 GoogleAuth 完成云平台 scope 认证后,即可按 projects.locations.* 的资源层次逐级调用。详细的类型定义与逐方法示例都沉淀在 v1.ts 与 v1alpha.ts 中,是查阅参数、字段约束与返回值结构的首选参考资料。

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