★ 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点击查看免费下载导读Cloud Error ReportingGoogle Cloud Error Reporting是一项用于聚合、计数并分析云服务与应用中相似错误的服务它既能接收新上报的错误事件也能对外提供按错误组Error Group维度的查询与统计能力。本篇文章以官方 Node.js 客户端库google-api-nodejs-client中的clouderrorreporting模块为切入点结合仓库源码src/apis/clouderrorreporting/v1beta1.ts与包定义src/apis/clouderrorreporting/package.json完整讲解该模块的安装、认证、错误事件上报、事件查询、错误组读取、分组统计以及多区域locations操作等实战用法。读完本文你将能在自己的 Node.js 服务中直接使用googleapis/clouderrorreporting包把异常接入 Google Cloud 的 Error Reporting 体系并学会如何从源码层理解每个方法背后的参数与接口契约。一、模块定位Error Reporting API 能做什么在官方生成的自述文档src/apis/clouderrorreporting/README.md中对该服务的定义是Groups and counts similar errors from cloud services and applications, reports new errors, and provides access to error groups and their associated errors.翻译成核心技术能力就是三件事上报新错误应用通过projects.events.report把单个错误事件主动推送到 Error Reporting分组与计数后端将相似错误自动聚合成错误组Error Group并统计各组的出现次数与受影响用户数查询访问对外提供错误组、组内错误事件以及分组统计数据Group Stats的读取接口。这些描述在生成代码的类注释中有完全一致的体现见 v1beta1.ts。从版本角度看当前仓库为这个 API 生成的是v1beta1版本在 src/apis/clouderrorreporting/index.ts 中可以看到VERSIONS映射表其定义与发现文档 discovery/clouderrorreporting-v1beta1.json 一一对应。二、安装与包结构官方文档给出的安装命令是$ npm install googleapis/clouderrorreporting这里安装的是独立子包适用于只使用 Error Reporting 的场景。从 package.json 可以看到该包的几个关键事实包名googleapis/clouderrorreporting当前版本13.0.1入口main指向build/index.js类型声明在build/index.d.ts运行时要求engines.node 22.0.0即需要 Node.js 22 及以上版本核心依赖googleapis-common^9.0.0它是所有 Google API 客户端的公共底座负责请求构造、认证整合、流式响应等底层能力LicenseApache-2.0。如果你正在使用聚合包googleapis则无需单独安装直接通过入口文件src/googleapis.ts按需取用即可。两种方式的客户端实例完全一致。从源码看包结构安装后在node_modules/googleapis/clouderrorreporting下你会得到这样的组成build/index.js/build/index.d.ts模块入口导出clouderrorreporting工厂函数、clouderrorreporting_v1beta1命名空间以及auth实例build/v1beta1.jsv1beta1版本的完整类型定义与所有资源类实现build/*.mapSource Map 文件。在 index.ts 中clouderrorreporting是一个重载工厂函数支持两种调用形态// 形态一直接传版本字符串 clouderrorreporting(v1beta1); // 形态二传全局 Options含 version 字段 clouderrorreporting({version: v1beta1, ...其他全局配置});它内部调用getAPI(clouderrorreporting, versionOrOptions, VERSIONS, this)完成客户端实例化这也是整个google-api-nodejs-client所有 API 模块的统一实例化模式。三、初始化客户端与认证要调用 Error Reporting 的任何接口都需要先获取客户端实例并配置认证。生成的示例代码见 v1beta1.ts给出了标准的初始化流程const {google} require(googleapis); const clouderrorreporting google.clouderrorreporting(v1beta1); async function main() { const auth new google.auth.GoogleAuth({ // Scopes 可以传数组也可以传单个以空格分隔的字符串 scopes: [https://www.googleapis.com/auth/cloud-platform], }); // 获取 auth client并绑定到之后的所有调用 const authClient await auth.getClient(); google.options({auth: authClient}); // ... 业务调用 }认证方式说明GoogleAuth是googleapis推荐的应用默认凭据ADC方式它会自动按顺序寻找环境变量GOOGLE_APPLICATION_CREDENTIALS指向的服务账号 JSON、gcloud 登录凭据、GCE 元数据服务等。在使用独立包googleapis/clouderrorreporting时同样可以从index.ts导出中拿到authAuthPlus实例做等价配置。此外从 v1beta1.ts 的StandardParameters定义可以看到每个请求还支持直接传入OAuth2ClientOAuth 2.0 客户端JWT服务账号令牌ComputeGCE 实例元数据认证UserRefreshClient用户刷新令牌BaseExternalAccountClient外部账号如 Workload Identity Federation或直接传GoogleAuth实例Error Reporting 的全部操作上报、查询、删除都需要https://www.googleapis.com/auth/cloud-platform作用域。运行前准备根据源码注释v1beta1.ts在运行任何示例前需要完成三步在 Google Cloud 控制台启用 Error Reporting API服务名clouderrorreporting.googleapis.com执行gcloud auth application-default login完成本地 ADC 登录安装 npm 模块聚合包用npm install googleapis独立包用npm install googleapis/clouderrorreporting。四、上报错误事件projects.events.report上报单个错误事件是接入 Error Reporting 的第一步对应客户端中的clouderrorreporting.projects.events.report方法源码示例见 v1beta1.ts方法签名在 L781-L803。const res await clouderrorreporting.projects.events.report({ // Required. 项目资源名形如 projects/{projectId} projectName: projects/my-project-123, // Request body 元数据 requestBody: { // 错误发生时的上下文HTTP 请求、源码位置、用户等 context: {}, // 错误发生时间RFC 3339 格式时间戳 eventTime: my_eventTime, // 错误消息内容必填 message: my_message, // 服务上下文service、version、resourceType serviceContext: {}, }, }); console.log(res.data);请求体核心字段从生成代码中的请求体注释v1beta1.ts可以看到requestBody支持四个顶层字段字段类型说明messagestring错误消息内容通常包含堆栈跟踪是分组的主要依据之一eventTimestring错误发生的时间戳不填则由服务端使用接收时间serviceContextobject服务标识含service服务名、version版本、resourceType资源类型contextobject错误上下文见下文展开context即ErrorContextschema在 v1beta1.ts 中有完整定义包含四个子字段httpRequest触发错误的 HTTP 请求信息HttpRequestContextreportLocation源码中决定上报错误的位置通常是记录日志的源码行SourceLocationsourceReferences构建产生该错误的可执行文件所用的源码引用SourceReference[]user导致或受该崩溃影响的用户标识——可以是用户 ID、邮箱或任意唯一 token未登录用户应留空此时系统会用远端 IP 等其他数据区分受影响用户对应统计中的affected_users_count。注意文档注释特别强调上报错误时若用户未登录请将user字段留空以免污染按用户维度的统计。响应的两种形态report方法的重载签名表明它返回Schema$ReportErrorEventResponse若传入StreamMethodOptions则返回可读流Readable。所有方法都同时支持 Promiseasync/await与回调callback两种风格这是googleapis-common的统一约定。五、查询错误事件projects.events.listclouderrorreporting.projects.events.list用于列出指定错误组内的错误事件源码示例见 v1beta1.tsconst res await clouderrorreporting.projects.events.list({ // Required. 错误组 ID由错误日志的关键内容派生而来 groupId: my-group-id, // Optional. 每页最大返回条数 pageSize: placeholder-value, // Optional. 上一响应返回的 next_page_token用于翻页 pageToken: placeholder-value, // Required. 项目资源名projects/{projectID} 或 projects/{projectID}/locations/{location} projectName: projects/my-project, // Optional. 精确匹配 ServiceContext.resourceType serviceFilter.resourceType: placeholder-value, // Optional. 精确匹配 ServiceContext.service serviceFilter.service: placeholder-value, // Optional. 精确匹配 ServiceContext.version serviceFilter.version: placeholder-value, // Optional. 限制查询的时间范围 timeRange.period: placeholder-value, }); console.log(res.data);参数与响应要点groupId必填错误组唯一标识由错误日志内容的关键部分派生属于 Service DataserviceFilter.*三个可选过滤器分别对应ServiceContext的resource_type、service、version用于把查询收敛到特定服务/版本/资源类型timeRange.period时间范围枚举取值形如PERIOD_1_HOUR、PERIOD_6_HOURS、PERIOD_1_DAY、PERIOD_1_WEEK、PERIOD_30_DAYS具体枚举以 API 文档为准响应结构errorEvents本页事件数组、nextPageToken下一页游标、timeRangeBegin本次查询时间范围的起始时间示例响应见 v1beta1.ts。六、读取错误组信息projects.groups.get错误组Error Group是 Error Reporting 聚合错误的基本单位。clouderrorreporting.projects.groups.get用于获取单个错误组的元数据源码示例见 v1beta1.tsconst res await clouderrorreporting.projects.groups.get({ // Required. 组资源名形如 // projects/{projectID}/groups/{group_id} // 或 projects/{projectID}/locations/{location}/groups/{group_id} groupName: projects/my-project/groups/my-group, });其中groupName的取值有两种形态v1beta1.tsprojects/my-project-123/groups/my-group全局projects/my-project-123/locations/global/groups/my-group带区域。典型的使用方式是先通过groupStats.list拿回项目内的组列表再对感兴趣的group_id调用groups.get获取该组的详细信息如ErrorGroup的name、groupId、trackingIssues等元数据字段。七、分组统计projects.groupStats.listclouderrorreporting.projects.groupStats.list是 Error Reporting 的核心分析接口它返回按错误组聚合的统计信息源码示例见 v1beta1.tsconst res await clouderrorreporting.projects.groupStats.list({ // Optional. 时间计数对齐方式默认 ALIGNMENT_EQUAL_AT_END alignment: placeholder-value, // Optional. 选择取整对齐时的时间锚点默认 00:00 UTC alignmentTime: placeholder-value, // Optional. 只列出指定 ID 的错误组 groupId: placeholder-value, // Optional. 结果排序默认 COUNT_DESC按错误数降序 order: placeholder-value, // Optional. 每页最大返回条数默认 20 pageSize: placeholder-value, // Optional. 翻页 token需与原查询参数完全一致 pageToken: placeholder-value, // Required. 项目资源名支持项目 ID 或项目编号 projectName: projects/my-project, // Optional. 服务过滤器resourceType / service / version serviceFilter.resourceType: placeholder-value, serviceFilter.service: placeholder-value, serviceFilter.version: placeholder-value, // Optional. 查询时间范围 timeRange.period: placeholder-value, });值得注意的默认值与用法order默认COUNT_DESC即按错误发生次数降序这决定了最严重的错误排在最前的默认视图pageSize默认 20翻页时必须携带与首次请求完全一致的查询参数仅替换pageTokenprojectName的多样性源码注释v1beta1.ts明确指出这里既可以传项目 IDprojects/my-project-123也可以传项目编号projects/5551234还可以带区域projects/my-project-123/locations/us-central1其中-是通配符可用于请求所有区域的统计alignment与alignmentTime控制按时间分桶的对齐方式与锚点配合timedCounts响应字段可用于绘制错误随时间变化的曲线。八、删除错误事件projects.deleteEventsclouderrorreporting.projects.deleteEvents用于删除指定项目的全部错误事件源码示例见 v1beta1.tsconst res await clouderrorreporting.projects.deleteEvents({ // Required. 项目资源名 projectName: projects/my-project, }); console.log(res.data);该接口返回Schema$DeleteEventsResponse空对象见 v1beta1.ts 的定义。需要注意的是它删除的是事件events而非错误组本身调用前请确认操作影响范围此操作通常用于测试环境或合规清理场景。九、多区域支持projects.locations 资源树除全局资源路径外v1beta1版本还完整支持**区域化locations**操作。在 v1beta1.ts 的资源树定义中Resource$Projects下除了events、groups、groupStats还有一个locations资源而Resource$Projects$LocationsL1453-L1461下又挂载了locations.events区域化事件上报与查询locations.groups区域化错误组读取locations.groupStats区域化分组统计调用方式与全局接口一一对应只需把projectName写成projects/{projectID}/locations/{location}形态即可例如// 区域化列出事件 const res await clouderrorreporting.projects.locations.events.list({ groupId: my-group-id, projectName: projects/my-project/locations/us-central1, }); // 区域化删除事件 await clouderrorreporting.projects.locations.deleteEvents({ projectName: projects/my-project/locations/my-location, });在groupStats.list中位置参数还可以用-通配符一次性聚合所有区域的数据见 v1beta1.ts 注释。当 location 未指定时global是默认值。这种全局 区域的双轨设计让用户可以按数据驻留要求把错误数据就近归集到特定 Cloud 区域。十、从源码理解客户端结构如果你打算深入二次开发或调试理解生成代码的组织方式会很有帮助。以v1beta1.ts共 2339 行为例其结构可分为四层顶层Clouderrorreporting类L113-L125构造函数接收全局Options与可选的GoogleConfigurable并挂载顶层资源projects资源类Resource$...Resource$Projects、Resource$Projects$Events、Resource$Projects$Groups、Resource$Projects$Groupstats、Resource$Projects$Locations及其子资源共 8 个类与 API 的 REST 资源路径一一对应方法重载签名每个方法如report、list、get、deleteEvents都声明了 Promise、回调与流式StreamMethodOptions三种调用形态Schema 接口Schema$ErrorContext、Schema$ListEventsResponse、Schema$ReportErrorEventResponse、Schema$DeleteEventsResponse等全部由发现文档 discovery/clouderrorreporting-v1beta1.json 自动生成是 TypeScript 类型提示的来源。所有请求最终都经由createAPIRequest进入googleapis-common的传输层gaxios因此统一支持拦截器、超时、重试与 HTTP/2 等全局能力。若你需要查看该模块的版本演进可以阅读同目录下的 src/apis/clouderrorreporting/CHANGELOG.md。十一、实战串联一个完整的接入示例把上面的方法组合起来一个典型的上报 → 查看统计 → 展开事件工作流如下const {google} require(googleapis); const clouderrorreporting google.clouderrorreporting(v1beta1); 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 projectName projects/my-project-123; // 1. 上报一条错误事件 await clouderrorreporting.projects.events.report({ projectName, requestBody: { message: TypeError: Cannot read property of undefined, serviceContext: {service: my-service, version: v1.0.0}, context: {user: user-42}, }, }); // 2. 查询该项目的分组统计按错误数降序默认每页 20 条 const stats await clouderrorreporting.projects.groupStats.list({ projectName, timeRange: {period: PERIOD_1_DAY}, // 以 API 实际枚举为准 }); // 3. 取第一个错误组列出其包含的具体错误事件 if (stats.data.errorGroupStats stats.data.errorGroupStats.length) { const groupId stats.data.errorGroupStats[0].group.groupId; const events await clouderrorreporting.projects.events.list({ projectName, groupId, }); console.log(events.data.errorEvents); } } main().catch(e { console.error(e); throw e; });小结googleapis/clouderrorreporting是google-api-nodejs-client生态中专门封装 Google Cloud Error Reporting 的官方客户端覆盖了从错误事件上报events.report、事件查询events.list、错误组读取groups.get、分组统计groupStats.list到事件清除deleteEvents的完整链路并通过projects.locations.*支持区域化数据归集。掌握本文介绍的参数语义与源码组织方式后你既可以快速把服务异常接入 Error Reporting也能在需要时直接查阅 v1beta1.ts 与 discovery/clouderrorreporting-v1beta1.json 确认每个接口的精确契约为生产环境的可观测性建设打下坚实基础。赞分享后端【免费下载链接】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点击查看免费下载相关推荐Trump2Cash的错误报告系统Google Cloud Error Reporting实战指南想要打造一个稳定可靠的股票交易机器人Trump2Cash项目通过Google Cloud Error Reporting构建了强大的错误报告系统让你的交易机金融科技后端NLPGoogle Cloud Error Reporting 实战基于 fluentd 的 GCE 实例错误上报配置python-docs-samples 详解Google Cloud Error Reporting 实战基于 fluentd 的 GCE 实例错误上报配置python docs samples 详解示例工程使用 google-api-nodejs-client 集成 Cloud Channel APIgoogleapis/cloudchannel 客户端库完整指南使用 google api nodejs client 集成 Cloud Channel APIgoogleapis/cloudchannel 客户端库完整后端创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
阅读完成 · 觉得有帮助？
