使用 Java 客户端库调用 Google Analytics Data API v1beta从环境准备到报表查询实战【免费下载链接】skillsAgent Skills for Google products and technologies项目地址: https://gitcode.com/GitHub_Trending/skills29/skillsGoogle Analytics Data APIv1beta为开发者提供了以编程方式访问 Google Analytics 报表数据的通道可用于构建定制化数据看板、自动化报表工作流以及将分析数据集成到企业应用中。本指南围绕本仓库中 google-analytics-data-api-basics 技能所沉淀的实践聚焦Java 客户端库的完整接入流程涵盖 API 启用、ADC 认证、Maven/Gradle 依赖安装、BetaAnalyticsDataClient报表查询以及维度与指标的 Schema 与兼容性校验。读完本文你将能够在自己的 Java 工程中快速跑通RunReport把 Google Analytics 数据安全、稳定地查询出来。一、环境前置条件在开始安装 Java 客户端库之前请确保开发环境满足以下三项基础要求与 java.md 中 Prerequisites 一节保持一致项目要求JDKJava 8 及以上推荐 Java 11构建工具Maven 或 Gradle二选一认证通过gcloud auth application-default login配置好的 Application Default CredentialsADC其中**ADC应用默认凭据**是客户端库自动完成认证的前提Java 客户端库在初始化BetaAnalyticsDataClient时会按照标准顺序自动查找凭据来源如环境变量GOOGLE_APPLICATION_CREDENTIALS、gcloud 生成的 ADC 文件、GCE/Cloud Run 等元数据服务开发者无需在代码中硬编码密钥。二、启用 Google Analytics Data API在发起任何 API 调用之前必须先在 Google Cloud 项目中启用analyticsdata.googleapis.com服务。该技能在 SKILL.md 中给出了标准的 Cloud CLI 操作流程# 1. 启用 API gcloud services enable analyticsdata.googleapis.com --quiet如果gcloud命令不存在需要先安装 Google Cloud CLI 再执行上述命令。# 2. 验证 API 是否已启用 gcloud services list --enabled --filteranalyticsdata.googleapis.com启用 API 的意义在于Cloud 项目会为 Analytics 报表运行分配必要的配额quota与权限这是后续所有数据请求能够成功执行的前提。若跳过此步骤客户端库调用时会返回类似PERMISSION_DENIED或服务未启用的错误。三、配置 ADC 认证与授权范围启用 API 后需要为本机环境生成 ADC并赋予必要的授权范围scope。该技能推荐的命令如下gcloud auth application-default login --scopeshttps://www.googleapis.com/auth/cloud-platform,https://www.googleapis.com/auth/analytics.readonly该命令会把 Cloud Platform 与 Google Analytics 只读两个 scope 写入本机 ADC 配置之后客户端库即可自动携带这些权限发起请求。**只读 scopeanalytics.readonly**意味着调用方只能查询报表数据无法修改属性或配置符合分析报表场景的最小权限原则。四、安装 Java 客户端库依赖官方 Java 客户端库的 Maven 坐标如下groupIdcom.google.cloudartifactIdgoogle-cloud-analytics-data版本以 Maven Central 上的最新稳定版本为准下文以LATEST_LIBRARY_VERSION占位方式 AMavenpom.xml在pom.xml的dependencies标签内添加以下依赖dependency groupIdcom.google.cloud/groupId artifactIdgoogle-cloud-analytics-data/artifactId versionLATEST_LIBRARY_VERSION/version /dependency为什么用 Maven引入该依赖后构建工具会自动把运行所需的 gRPC 传输层与 protobuf 消息类一并加入运行时 classpathBetaAnalyticsDataClient及RunReportRequest等类型才能被正确解析与序列化。方式 BGradlebuild.gradle在dependencies块中添加implementation com.google.cloud:google-cloud-analytics-data:LATEST_LIBRARY_VERSION[!TIP] 请务必把LATEST_LIBRARY_VERSION替换为 Maven Central 上该依赖的最新稳定版本号。仓库文档刻意使用占位符是为了避免固化某个过期版本误导读者。五、快速开始用 Java 跑通第一份报表安装依赖并完成 ADC 认证后即可使用如下完整示例查询某个 GA4 属性的数据。该示例完整继承自 java.md 的 Quickstart 代码import com.google.analytics.data.v1beta.BetaAnalyticsDataClient; import com.google.analytics.data.v1beta.RunReportRequest; import com.google.analytics.data.v1beta.RunReportResponse; import com.google.analytics.data.v1beta.DateRange; import com.google.analytics.data.v1beta.Dimension; import com.google.analytics.data.v1beta.Metric; public class DataApiDemo { public static void main(String[] args) throws Exception { // 在 try-with-resources 中初始化 BetaAnalyticsDataClient。 // 客户端默认读取环境中的 ADC无需在代码中手动传凭证。 try (BetaAnalyticsDataClient client BetaAnalyticsDataClient.create()) { RunReportRequest request RunReportRequest.newBuilder() .setProperty(properties/1234567) .addDimensions(Dimension.newBuilder().setName(city)) .addMetrics(Metric.newBuilder().setName(activeUsers)) .addDateRanges(DateRange.newBuilder().setStartDate(2026-05-01).setEndDate(today)) .build(); RunReportResponse response client.runReport(request); response.getRowsList().forEach(row - { System.out.printf(%s, %s%n, row.getDimensionValues(0).getValue(), row.getMetricValues(0).getValue()); }); } } }代码要点拆解BetaAnalyticsDataClientv1beta 端点的服务客户端通过静态工厂create()创建。由于实现了AutoCloseable放在 try-with-resources 中可确保底层 gRPC 连接与资源被正确释放。RunReportRequest.newBuilder()采用 protobuf Builder 模式构造请求字段类型强约束编译期即可发现拼写错误。setProperty(properties/1234567)属性标识符必须使用properties/{PROPERTY_ID}前缀格式1234567仅为示例请替换为你实际的 GA4 属性 ID。addDimensions(...)/addMetrics(...)逐个添加要查询的维度与指标其name必须是 Data API Schema 中的合法 API 名称详见下一节。addDateRanges(...)时间范围支持YYYY-MM-DD格式endDate也接受today/yesterday/NdaysAgo等相对日期写法示例中2026-05-01到today表示近期的活跃数据。结果遍历response.getRowsList()中每行按请求中维度、指标的声明顺序排列row.getDimensionValues(0)对应cityrow.getMetricValues(0)对应activeUsers。为什么使用 v1beta 版本该技能在 SKILL.md 中明确建议始终优先选用 v1beta 版本的 API因为它具备稳定性保证且覆盖当前 Google Analytics 最新的报表能力。六、维度与指标 Schema 速查构造RunReportRequest时Dimension.name与Metric.name必须使用合法的 API 名称。技能文档整理了常用字段可直接参考常用维度Dimension维度描述数据的分类型属性city用户所在的城市country用户所在的国家date事件发生的日期格式为YYYYMMDDdeviceCategory移动设备类别如 desktop、mobile、tableteventName触发事件的名称pageTitle网页的标题常用指标Metric指标描述定量度量值activeUsers活跃用户数eventCount事件总数sessions会话总数screenPageViews应用内屏幕或网页的浏览数totalRevenue来自购买、订阅与广告的总收入兼容性校验与元数据查询并非所有维度与指标都能组合进同一个报表请求。如果请求中包含互不兼容的字段组合服务端会返回INVALID_ARGUMENT错误。技能文档给出了两条程序化应对路径getMetadata()以编程方式获取指定属性可用的维度/指标元数据API 名称、说明、类别等用于在开发阶段确认字段拼写与可用性。checkCompatibility()在真正运行报表之前预先校验特定维度与指标组合是否兼容。该技能在 SKILL.md 中提供了 Python 实现示例在 Java 中同样通过BetaAnalyticsDataClient.checkCompatibility(CheckCompatibilityRequest)调用返回结果中每个维度/指标都会带有一个Compatibility枚举COMPATIBLE/INCOMPATIBLE据此可在构建请求前过滤掉不兼容字段避免无效调用浪费配额。七、与仓库中其他语言参考的横向对照本技能为常用编程语言都准备了独立的安装参考文档Java 是其中之一Java 参考com.google.cloud:google-cloud-analytics-dataMaven/GradlePython 参考google-analytics-datapipPython 3.8Node.js 参考google-analytics/datanpmNode v14Go 参考cloud.google.com/go/analytics/data/apiv1betaGo 1.19.NET 参考Google.Analytics.Data.V1BetaNuGetPHP 参考google/analytics-dataComposerPHP 8.0Ruby 参考google-analytics-data-v1betaRubyGemsRuby 3.0各语言的调用模式高度一致都通过各自生态中的客户端工厂创建服务对象以property properties/{ID}、dimensions、metrics、date_ranges四个核心字段构造请求再调用runReport并遍历rows。因此即便你的团队后端是 Java、数据脚本是 Python核心概念属性 ID 前缀、API 字段名、日期范围写法完全可以无缝迁移。八、常见问题与排查建议PERMISSION_DENIED/ 未启用 API回到第二节用gcloud services list --enabled --filteranalyticsdata.googleapis.com确认服务状态并检查项目是否正确。认证失败确认已执行第三节的gcloud auth application-default login且当前 gcloud 账号对该 GA4 属性有访问权限。INVALID_ARGUMENT多为维度/指标名称拼写错误或字段组合不兼容见第六节可先用getMetadata()核对字段再用checkCompatibility()预检。版本号问题LATEST_LIBRARY_VERSION必须替换为 Maven Central 上真实存在的稳定版本避免使用过旧版本导致与 v1beta 端点能力不匹配。九、延伸阅读技能总入口 SKILL.md 包含了 API 启用、ADC 认证、Python 快速上手示例以及完整的维度/指标 Schema 与兼容性校验逻辑是本文 Java 部分的上层指导文档。本技能在仓库 README.md 的 Others 分类中以Getting Started with Google Analytics Data API名义收录见skills/analytics/google-analytics-data-api-basics属于面向 Google 产品与技术的 Agent Skills 集合的一部分。若需管理属性、用户等管理类操作请参考同目录下的 google-analytics-admin-api-basics而不要混用 Data APIData API 不负责创建属性、管理用户等管理端操作也不负责前端埋点安装。以上内容均以本仓库 java.md 为主体骨架并结合 SKILL.md 的 API 启用、认证、Schema 与兼容性说明扩展而成。将代码中的1234567换成你的真实属性 ID即可在本地 Java 工程中运行第一份 GA4 报表查询。【免费下载链接】skillsAgent Skills for Google products and technologies项目地址: https://gitcode.com/GitHub_Trending/skills29/skills创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 使用 Java 客户端库调用 Google Analytics Data API v1beta：从环境准备到报表查询实战
使用 Java 客户端库调用 Google Analytics Data API v1beta从环境准备到报表查询实战【免费下载链接】skillsAgent Skills for Google products and technologies项目地址: https://gitcode.com/GitHub_Trending/skills29/skillsGoogle Analytics Data APIv1beta为开发者提供了以编程方式访问 Google Analytics 报表数据的通道可用于构建定制化数据看板、自动化报表工作流以及将分析数据集成到企业应用中。本指南围绕本仓库中 google-analytics-data-api-basics 技能所沉淀的实践聚焦Java 客户端库的完整接入流程涵盖 API 启用、ADC 认证、Maven/Gradle 依赖安装、BetaAnalyticsDataClient报表查询以及维度与指标的 Schema 与兼容性校验。读完本文你将能够在自己的 Java 工程中快速跑通RunReport把 Google Analytics 数据安全、稳定地查询出来。一、环境前置条件在开始安装 Java 客户端库之前请确保开发环境满足以下三项基础要求与 java.md 中 Prerequisites 一节保持一致项目要求JDKJava 8 及以上推荐 Java 11构建工具Maven 或 Gradle二选一认证通过gcloud auth application-default login配置好的 Application Default CredentialsADC其中**ADC应用默认凭据**是客户端库自动完成认证的前提Java 客户端库在初始化BetaAnalyticsDataClient时会按照标准顺序自动查找凭据来源如环境变量GOOGLE_APPLICATION_CREDENTIALS、gcloud 生成的 ADC 文件、GCE/Cloud Run 等元数据服务开发者无需在代码中硬编码密钥。二、启用 Google Analytics Data API在发起任何 API 调用之前必须先在 Google Cloud 项目中启用analyticsdata.googleapis.com服务。该技能在 SKILL.md 中给出了标准的 Cloud CLI 操作流程# 1. 启用 API gcloud services enable analyticsdata.googleapis.com --quiet如果gcloud命令不存在需要先安装 Google Cloud CLI 再执行上述命令。# 2. 验证 API 是否已启用 gcloud services list --enabled --filteranalyticsdata.googleapis.com启用 API 的意义在于Cloud 项目会为 Analytics 报表运行分配必要的配额quota与权限这是后续所有数据请求能够成功执行的前提。若跳过此步骤客户端库调用时会返回类似PERMISSION_DENIED或服务未启用的错误。三、配置 ADC 认证与授权范围启用 API 后需要为本机环境生成 ADC并赋予必要的授权范围scope。该技能推荐的命令如下gcloud auth application-default login --scopeshttps://www.googleapis.com/auth/cloud-platform,https://www.googleapis.com/auth/analytics.readonly该命令会把 Cloud Platform 与 Google Analytics 只读两个 scope 写入本机 ADC 配置之后客户端库即可自动携带这些权限发起请求。**只读 scopeanalytics.readonly**意味着调用方只能查询报表数据无法修改属性或配置符合分析报表场景的最小权限原则。四、安装 Java 客户端库依赖官方 Java 客户端库的 Maven 坐标如下groupIdcom.google.cloudartifactIdgoogle-cloud-analytics-data版本以 Maven Central 上的最新稳定版本为准下文以LATEST_LIBRARY_VERSION占位方式 AMavenpom.xml在pom.xml的dependencies标签内添加以下依赖dependency groupIdcom.google.cloud/groupId artifactIdgoogle-cloud-analytics-data/artifactId versionLATEST_LIBRARY_VERSION/version /dependency为什么用 Maven引入该依赖后构建工具会自动把运行所需的 gRPC 传输层与 protobuf 消息类一并加入运行时 classpathBetaAnalyticsDataClient及RunReportRequest等类型才能被正确解析与序列化。方式 BGradlebuild.gradle在dependencies块中添加implementation com.google.cloud:google-cloud-analytics-data:LATEST_LIBRARY_VERSION[!TIP] 请务必把LATEST_LIBRARY_VERSION替换为 Maven Central 上该依赖的最新稳定版本号。仓库文档刻意使用占位符是为了避免固化某个过期版本误导读者。五、快速开始用 Java 跑通第一份报表安装依赖并完成 ADC 认证后即可使用如下完整示例查询某个 GA4 属性的数据。该示例完整继承自 java.md 的 Quickstart 代码import com.google.analytics.data.v1beta.BetaAnalyticsDataClient; import com.google.analytics.data.v1beta.RunReportRequest; import com.google.analytics.data.v1beta.RunReportResponse; import com.google.analytics.data.v1beta.DateRange; import com.google.analytics.data.v1beta.Dimension; import com.google.analytics.data.v1beta.Metric; public class DataApiDemo { public static void main(String[] args) throws Exception { // 在 try-with-resources 中初始化 BetaAnalyticsDataClient。 // 客户端默认读取环境中的 ADC无需在代码中手动传凭证。 try (BetaAnalyticsDataClient client BetaAnalyticsDataClient.create()) { RunReportRequest request RunReportRequest.newBuilder() .setProperty(properties/1234567) .addDimensions(Dimension.newBuilder().setName(city)) .addMetrics(Metric.newBuilder().setName(activeUsers)) .addDateRanges(DateRange.newBuilder().setStartDate(2026-05-01).setEndDate(today)) .build(); RunReportResponse response client.runReport(request); response.getRowsList().forEach(row - { System.out.printf(%s, %s%n, row.getDimensionValues(0).getValue(), row.getMetricValues(0).getValue()); }); } } }代码要点拆解BetaAnalyticsDataClientv1beta 端点的服务客户端通过静态工厂create()创建。由于实现了AutoCloseable放在 try-with-resources 中可确保底层 gRPC 连接与资源被正确释放。RunReportRequest.newBuilder()采用 protobuf Builder 模式构造请求字段类型强约束编译期即可发现拼写错误。setProperty(properties/1234567)属性标识符必须使用properties/{PROPERTY_ID}前缀格式1234567仅为示例请替换为你实际的 GA4 属性 ID。addDimensions(...)/addMetrics(...)逐个添加要查询的维度与指标其name必须是 Data API Schema 中的合法 API 名称详见下一节。addDateRanges(...)时间范围支持YYYY-MM-DD格式endDate也接受today/yesterday/NdaysAgo等相对日期写法示例中2026-05-01到today表示近期的活跃数据。结果遍历response.getRowsList()中每行按请求中维度、指标的声明顺序排列row.getDimensionValues(0)对应cityrow.getMetricValues(0)对应activeUsers。为什么使用 v1beta 版本该技能在 SKILL.md 中明确建议始终优先选用 v1beta 版本的 API因为它具备稳定性保证且覆盖当前 Google Analytics 最新的报表能力。六、维度与指标 Schema 速查构造RunReportRequest时Dimension.name与Metric.name必须使用合法的 API 名称。技能文档整理了常用字段可直接参考常用维度Dimension维度描述数据的分类型属性city用户所在的城市country用户所在的国家date事件发生的日期格式为YYYYMMDDdeviceCategory移动设备类别如 desktop、mobile、tableteventName触发事件的名称pageTitle网页的标题常用指标Metric指标描述定量度量值activeUsers活跃用户数eventCount事件总数sessions会话总数screenPageViews应用内屏幕或网页的浏览数totalRevenue来自购买、订阅与广告的总收入兼容性校验与元数据查询并非所有维度与指标都能组合进同一个报表请求。如果请求中包含互不兼容的字段组合服务端会返回INVALID_ARGUMENT错误。技能文档给出了两条程序化应对路径getMetadata()以编程方式获取指定属性可用的维度/指标元数据API 名称、说明、类别等用于在开发阶段确认字段拼写与可用性。checkCompatibility()在真正运行报表之前预先校验特定维度与指标组合是否兼容。该技能在 SKILL.md 中提供了 Python 实现示例在 Java 中同样通过BetaAnalyticsDataClient.checkCompatibility(CheckCompatibilityRequest)调用返回结果中每个维度/指标都会带有一个Compatibility枚举COMPATIBLE/INCOMPATIBLE据此可在构建请求前过滤掉不兼容字段避免无效调用浪费配额。七、与仓库中其他语言参考的横向对照本技能为常用编程语言都准备了独立的安装参考文档Java 是其中之一Java 参考com.google.cloud:google-cloud-analytics-dataMaven/GradlePython 参考google-analytics-datapipPython 3.8Node.js 参考google-analytics/datanpmNode v14Go 参考cloud.google.com/go/analytics/data/apiv1betaGo 1.19.NET 参考Google.Analytics.Data.V1BetaNuGetPHP 参考google/analytics-dataComposerPHP 8.0Ruby 参考google-analytics-data-v1betaRubyGemsRuby 3.0各语言的调用模式高度一致都通过各自生态中的客户端工厂创建服务对象以property properties/{ID}、dimensions、metrics、date_ranges四个核心字段构造请求再调用runReport并遍历rows。因此即便你的团队后端是 Java、数据脚本是 Python核心概念属性 ID 前缀、API 字段名、日期范围写法完全可以无缝迁移。八、常见问题与排查建议PERMISSION_DENIED/ 未启用 API回到第二节用gcloud services list --enabled --filteranalyticsdata.googleapis.com确认服务状态并检查项目是否正确。认证失败确认已执行第三节的gcloud auth application-default login且当前 gcloud 账号对该 GA4 属性有访问权限。INVALID_ARGUMENT多为维度/指标名称拼写错误或字段组合不兼容见第六节可先用getMetadata()核对字段再用checkCompatibility()预检。版本号问题LATEST_LIBRARY_VERSION必须替换为 Maven Central 上真实存在的稳定版本避免使用过旧版本导致与 v1beta 端点能力不匹配。九、延伸阅读技能总入口 SKILL.md 包含了 API 启用、ADC 认证、Python 快速上手示例以及完整的维度/指标 Schema 与兼容性校验逻辑是本文 Java 部分的上层指导文档。本技能在仓库 README.md 的 Others 分类中以Getting Started with Google Analytics Data API名义收录见skills/analytics/google-analytics-data-api-basics属于面向 Google 产品与技术的 Agent Skills 集合的一部分。若需管理属性、用户等管理类操作请参考同目录下的 google-analytics-admin-api-basics而不要混用 Data APIData API 不负责创建属性、管理用户等管理端操作也不负责前端埋点安装。以上内容均以本仓库 java.md 为主体骨架并结合 SKILL.md 的 API 启用、认证、Schema 与兼容性说明扩展而成。将代码中的1234567换成你的真实属性 ID即可在本地 Java 工程中运行第一份 GA4 报表查询。【免费下载链接】skillsAgent Skills for Google products and technologies项目地址: https://gitcode.com/GitHub_Trending/skills29/skills创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考