google-api-nodejs-client 中的 App Hub 客户端库:安装、认证与 App Hub API 使用指南
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:列出 Applicationpatch:更新 Applicationdelete:删除 ApplicationgetIamPolicy/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 |
— | 服务项目与宿主项目的挂载关系 |
一个典型的业务流如下:
- 用
serviceProjectAttachments.create将服务项目挂载到宿主项目; - 用
discoveredServices.lookup/discoveredWorkloads.lookup找到要纳入的底层资源; - 用
applications.create创建 Application 边界(定义 scope 与 attributes); - 用
applications.services.create、applications.workloads.create将已发现资源注册进 Application; - 用
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 中,是查阅参数、字段约束与返回值结构的首选参考资料。