 Python 客户端库实战指南：安装、认证与 RunReport 报告查询)
Google Analytics Data API (v1beta) Python 客户端库实战指南安装、认证与 RunReport 报告查询【免费下载链接】skillsAgent Skills for Google products and technologies项目地址: https://gitcode.com/GitHub_Trending/skills29/skills导读本文基于开源仓库 Agent Skills for Google products and technologies 中的google-analytics-data-api-basics技能位于 skills/analytics/google-analytics-data-api-basics/SKILL.md及其 Python 客户端库安装参考文档references/python.md系统讲解如何在本机环境中启用 Google Analytics Data APIv1beta、完成认证并使用官方 Python 客户端库google-analytics-data编写可运行的数据报告查询程序。读完本文你将掌握从虚拟环境搭建、API 启用、ADC 认证到RunReportRequest报告构建与checkCompatibility兼容性校验的完整实战链路可直接应用于自动化报表、自定义看板与数据集成场景。技能定位Data API 与 Admin API 的分工边界该技能面向「管理 Google Analytics 报告数据」的场景通过 Cloud CLI 启用 Analytics Data API并使用 v1beta 版本客户端库创建自定义分析报告查询activeUsers、screenPageViews等指标与city、date等维度校验指标/维度兼容性以及确认 API 是否已启用。技能描述明确划定了使用边界见 SKILL.md适用与 Google Analytics 数据属性交互、运行自定义分析报告、查询指标与维度、检查指标维度兼容性、验证 API 启用状态不适用Google Analytics Admin API 操作如创建属性、管理用户以及前端埋点tracking安装。如需账户/属性级配置管理可参照仓库中相邻的 google-analytics-admin-api-basics 技能。前置条件在安装 Python 客户端库之前需要满足以下环境要求来自 references/python.md前置项要求Python版本 3.8 或更高包管理器pip认证通过gcloud auth application-default login配置的 Application Default Credentials (ADC)提示若系统未安装gcloud需先安装 Google Cloud CLI 再执行后续命令若pip不可用应先安装 Python 与pip再安装客户端库。第一步通过 Cloud CLI 启用 API调用任何 Data API 之前必须先在 Google Cloud 项目中启用analyticsdata.googleapis.com服务。启用 APIgcloud services enable analyticsdata.googleapis.com --quiet为什么这样做启用 API 可确保你的 Cloud 项目为该服务分配了必要的配额与权限从而允许运行 Google Analytics 报告SKILL.md。验证 API 启用状态gcloud services list --enabled --filteranalyticsdata.googleapis.com若输出中包含该服务则说明 API 已成功启用。第二步配置 Application Default CredentialsADC认证客户端库不会硬编码密钥而是依赖 ADC 自动完成请求认证。在终端中执行gcloud auth application-default login --scopeshttps://www.googleapis.com/auth/cloud-platform,https://www.googleapis.com/auth/analytics.readonly为什么这样做该命令为本地环境配置 ADC并授予 Cloud Platform 与 Google Analytics 只读两个 scope使客户端库如BetaAnalyticsDataClient()能自动读取凭据并完成认证SKILL.md。注意analytics.readonlyscope 足够支撑报告查询场景若涉及配置变更类操作则需analytics.editscope参考 google-analytics-admin-api-basics 的说明。第三步在虚拟环境中安装 Python 客户端库官方 Python 客户端库的包名为google-analytics-data建议在独立虚拟环境中安装以保证构建可重复、避免依赖冲突references/python.md。1. 创建并激活虚拟环境python3 -m venv .venv source .venv/bin/activate2. 安装客户端库pip install google-analytics-data该包提供 v1beta 版本的强类型请求/响应模型如RunReportRequest、DateRange、Dimension、Metric与BetaAnalyticsDataClient客户端保证与 v1beta 端点兼容并具备强类型请求校验SKILL.md。第四步编写并运行第一个报告查询最小可用示例以下代码来自 references/python.md演示了按城市统计活跃用户的最小完整流程from google.analytics.data_v1beta import BetaAnalyticsDataClient from google.analytics.data_v1beta.types import DateRange, Dimension, Metric, RunReportRequest def run_report(property_id: str): # Initialize the client. Uses ADC from environment. client BetaAnalyticsDataClient() request RunReportRequest( propertyfproperties/{property_id}, dimensions[Dimension(namecity)], metrics[Metric(nameactiveUsers)], date_ranges[DateRange(start_date2026-05-01, end_datetoday)], ) response client.run_report(request) for row in response.rows: print(fCity: {row.dimension_values[0].value}, Users: {row.metric_values[0].value}) if __name__ __main__: run_report(1234567)要点拆解property参数必须使用properties/{property_id}格式property_id为 Google Analytics 属性的数字 ID示例1234567需替换为真实值DateRangestart_date与end_date支持YYYY-MM-DD格式end_date可使用特殊值today表示截止当日响应结构response.rows中每行按请求顺序返回dimension_values与metric_values通过.value读取字符串值。多维度多指标的进阶示例SKILL.md 给出了同时查询「城市 日期」两个维度与「活跃用户 会话数」两个指标的完整示例from google.analytics.data_v1beta import BetaAnalyticsDataClient from google.analytics.data_v1beta.types import DateRange, Dimension, Metric, RunReportRequest def sample_run_report(property_id: str): # Initialize the client. # Assumes Application Default Credentials (ADC) are configured in your environment. client BetaAnalyticsDataClient() request RunReportRequest( propertyfproperties/{property_id}, dimensions[ Dimension(namecity), Dimension(namedate) ], metrics[ Metric(nameactiveUsers), Metric(namesessions) ], date_ranges[ DateRange(start_date2026-05-01, end_datetoday) ], ) response client.run_report(request) print(fReport result for property {property_id}:) for row in response.rows: print( fCity: {row.dimension_values[0].value}, fDate: {row.dimension_values[1].value}, fActive Users: {row.metric_values[0].value}, fSessions: {row.metric_values[1].value} ) if __name__ __main__: sample_run_report(YOUR-PROPERTY-ID)维度与指标 Schema 速查构造RunReportRequest时必须使用合法的 API 名称dimension/metric API name。以下是该技能文档归纳的常用字段SKILL.md常用维度分类属性API 名称含义city用户所在城镇/城市country用户所在国家date事件日期格式为 YYYYMMDDdeviceCategory移动设备类别desktop、mobile、tablet 等eventName触发的事件名称pageTitle网页标题常用指标定量测量API 名称含义activeUsers活跃用户数eventCount事件总次数sessions会话总数screenPageViews应用屏幕或网页浏览量totalRevenue来自购买、订阅与广告的总收入完整的权威字段清单需要以官方 Data API Schema 文档为准若不确定某个字段可调用getMetadata()以编程方式读取属性可用 schema。指标与维度的兼容性检查并非所有维度与指标都能在同一个报告请求中组合查询。若请求返回INVALID_ARGUMENT错误并提示字段不兼容需先校验组合合法性。除人工核对 schema 外该技能提供了两种程序化手段SKILL.mdgetMetadata()程序化读取 Data API schemacheckCompatibility()在真正运行报告前程序化校验特定维度/指标组合的兼容性。完整示例检查电商维度itemName与activeUsers、totalRevenue的兼容性from google.analytics.data_v1beta import BetaAnalyticsDataClient from google.analytics.data_v1beta.types import CheckCompatibilityRequest, Compatibility, Dimension, Metric def sample_check_compatibility(property_id: str): client BetaAnalyticsDataClient() # Define the dimensions and metrics you want to query together. # For example, checking if itemName (an e-commerce dimension) # is compatible with activeUsers and totalRevenue. request CheckCompatibilityRequest( propertyfproperties/{property_id}, dimensions[ Dimension(nameitemName), Dimension(namedate) ], metrics[ Metric(nameactiveUsers), Metric(nametotalRevenue) ], ) response client.check_compatibility(request) print(fCompatibility check for property {property_id}:) for dim in response.dimension_compatibilities: is_compatible dim.compatibility Compatibility.COMPATIBLE print(fDimension {dim.dimension_metadata.api_name} is compatible: {is_compatible}) for metric in response.metric_compatibilities: is_compatible metric.compatibility Compatibility.COMPATIBLE print(fMetric {metric.metric_metadata.api_name} is compatible: {is_compatible}) if __name__ __main__: sample_check_compatibility(YOUR-PROPERTY-ID)从代码可推断CheckCompatibilityRequest结构上对标RunReportRequest同样由property、dimensions、metrics组成而响应中的dimension_compatibilities与metric_compatibilities各自携带dimension_metadata/metric_metadata含api_name与compatibility枚举通过比对Compatibility.COMPATIBLE即可得到布尔判定。多语言客户端库速览该技能在 SKILL.md 中列出了 Data API 官方支持的全部客户端库Python 只是其中一种。各语言安装参考文档位于技能目录的references/下便于按需查阅语言安装方式包/构件名参考文档Pythonpip install google-analytics-datagoogle-analytics-datareferences/python.mdJavaMaven / Gradlecom.google.cloud:google-cloud-analytics-datareferences/java.mdPHPcomposer require google/analytics-datagoogle/analytics-datareferences/php.mdNode.jsnpm install google-analytics/datagoogle-analytics/datareferences/nodejs.mdGogo get cloud.google.com/go/analytics/data/apiv1betacloud.google.com/go/analytics/data/apiv1betareferences/go.md.NETdotnet add package Google.Analytics.Data.V1BetaGoogle.Analytics.Data.V1Betareferences/dotnet.mdRubygem install google-analytics-data-v1betagoogle-analytics-data-v1betareferences/ruby.md从各参考文档可以看出跨语言的一致性设计所有语言均使用 v1beta 版本的BetaAnalyticsDataClientGo 为data.NewBetaAnalyticsDataClient、Ruby 为Google::Analytics::Data::V1beta::AnalyticsData::Client均基于 ADC 自动认证请求体均由property、dimensions、metrics、date_ranges四要素构成且属性 ID 统一使用properties/{id}格式。例如 Java 通过RunReportRequest.newBuilder()链式构建.NET 通过对象初始化器赋值Node.js 通过对象字面量传入runReport()但底层均映射到同一套 protobuf 消息定义。常见错误与排查要点结合技能文档与代码结构可将高频问题归纳如下现象可能原因处置建议gcloud命令找不到未安装 Google Cloud CLI先安装 gcloud再重新执行启用/认证命令pip不可用Python/pip 未安装先安装 Python 3.8 与 pip再执行安装INVALID_ARGUMENT字段不兼容维度与指标组合不合法使用getMetadata()查 schema或先用checkCompatibility()预校验认证失败未配置 ADC 或 scope 不足重新执行gcloud auth application-default login并带上analytics.readonlyscope报告返回空属性 ID 错误或日期范围内无数据核对properties/{property_id}格式与DateRange区间总结google-analytics-data-api-basics技能为 Google Analytics Data APIv1beta的报告查询提供了端到端的最佳实践先通过gcloud services enable analyticsdata.googleapis.com启用 API再用gcloud auth application-default login配置带正确 scope 的 ADC随后在虚拟环境中安装google-analytics-data即可用BetaAnalyticsDataClient配合RunReportRequest编写自动化报表。构建请求时务必使用合法维度/指标 API 名称并在组合不确定时借助checkCompatibility()提前规避INVALID_ARGUMENT。完整的安装细节可进一步阅读 references/python.md多语言参考位于同目录下其余 6 个语言文档。【免费下载链接】skillsAgent Skills for Google products and technologies项目地址: https://gitcode.com/GitHub_Trending/skills29/skills创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 
长河君 · 2026/9/13 12:13:39 · 阅读 1.2k Google Analytics Data API (v1beta) Python 客户端库实战指南：安装、认证与 RunReport 报告查询
Google Analytics Data API (v1beta) Python 客户端库实战指南安装、认证与 RunReport 报告查询【免费下载链接】skillsAgent Skills for Google products and technologies项目地址: https://gitcode.com/GitHub_Trending/skills29/skills导读本文基于开源仓库 Agent Skills for Google products and technologies 中的google-analytics-data-api-basics技能位于 skills/analytics/google-analytics-data-api-basics/SKILL.md及其 Python 客户端库安装参考文档references/python.md系统讲解如何在本机环境中启用 Google Analytics Data APIv1beta、完成认证并使用官方 Python 客户端库google-analytics-data编写可运行的数据报告查询程序。读完本文你将掌握从虚拟环境搭建、API 启用、ADC 认证到RunReportRequest报告构建与checkCompatibility兼容性校验的完整实战链路可直接应用于自动化报表、自定义看板与数据集成场景。技能定位Data API 与 Admin API 的分工边界该技能面向「管理 Google Analytics 报告数据」的场景通过 Cloud CLI 启用 Analytics Data API并使用 v1beta 版本客户端库创建自定义分析报告查询activeUsers、screenPageViews等指标与city、date等维度校验指标/维度兼容性以及确认 API 是否已启用。技能描述明确划定了使用边界见 SKILL.md适用与 Google Analytics 数据属性交互、运行自定义分析报告、查询指标与维度、检查指标维度兼容性、验证 API 启用状态不适用Google Analytics Admin API 操作如创建属性、管理用户以及前端埋点tracking安装。如需账户/属性级配置管理可参照仓库中相邻的 google-analytics-admin-api-basics 技能。前置条件在安装 Python 客户端库之前需要满足以下环境要求来自 references/python.md前置项要求Python版本 3.8 或更高包管理器pip认证通过gcloud auth application-default login配置的 Application Default Credentials (ADC)提示若系统未安装gcloud需先安装 Google Cloud CLI 再执行后续命令若pip不可用应先安装 Python 与pip再安装客户端库。第一步通过 Cloud CLI 启用 API调用任何 Data API 之前必须先在 Google Cloud 项目中启用analyticsdata.googleapis.com服务。启用 APIgcloud services enable analyticsdata.googleapis.com --quiet为什么这样做启用 API 可确保你的 Cloud 项目为该服务分配了必要的配额与权限从而允许运行 Google Analytics 报告SKILL.md。验证 API 启用状态gcloud services list --enabled --filteranalyticsdata.googleapis.com若输出中包含该服务则说明 API 已成功启用。第二步配置 Application Default CredentialsADC认证客户端库不会硬编码密钥而是依赖 ADC 自动完成请求认证。在终端中执行gcloud auth application-default login --scopeshttps://www.googleapis.com/auth/cloud-platform,https://www.googleapis.com/auth/analytics.readonly为什么这样做该命令为本地环境配置 ADC并授予 Cloud Platform 与 Google Analytics 只读两个 scope使客户端库如BetaAnalyticsDataClient()能自动读取凭据并完成认证SKILL.md。注意analytics.readonlyscope 足够支撑报告查询场景若涉及配置变更类操作则需analytics.editscope参考 google-analytics-admin-api-basics 的说明。第三步在虚拟环境中安装 Python 客户端库官方 Python 客户端库的包名为google-analytics-data建议在独立虚拟环境中安装以保证构建可重复、避免依赖冲突references/python.md。1. 创建并激活虚拟环境python3 -m venv .venv source .venv/bin/activate2. 安装客户端库pip install google-analytics-data该包提供 v1beta 版本的强类型请求/响应模型如RunReportRequest、DateRange、Dimension、Metric与BetaAnalyticsDataClient客户端保证与 v1beta 端点兼容并具备强类型请求校验SKILL.md。第四步编写并运行第一个报告查询最小可用示例以下代码来自 references/python.md演示了按城市统计活跃用户的最小完整流程from google.analytics.data_v1beta import BetaAnalyticsDataClient from google.analytics.data_v1beta.types import DateRange, Dimension, Metric, RunReportRequest def run_report(property_id: str): # Initialize the client. Uses ADC from environment. client BetaAnalyticsDataClient() request RunReportRequest( propertyfproperties/{property_id}, dimensions[Dimension(namecity)], metrics[Metric(nameactiveUsers)], date_ranges[DateRange(start_date2026-05-01, end_datetoday)], ) response client.run_report(request) for row in response.rows: print(fCity: {row.dimension_values[0].value}, Users: {row.metric_values[0].value}) if __name__ __main__: run_report(1234567)要点拆解property参数必须使用properties/{property_id}格式property_id为 Google Analytics 属性的数字 ID示例1234567需替换为真实值DateRangestart_date与end_date支持YYYY-MM-DD格式end_date可使用特殊值today表示截止当日响应结构response.rows中每行按请求顺序返回dimension_values与metric_values通过.value读取字符串值。多维度多指标的进阶示例SKILL.md 给出了同时查询「城市 日期」两个维度与「活跃用户 会话数」两个指标的完整示例from google.analytics.data_v1beta import BetaAnalyticsDataClient from google.analytics.data_v1beta.types import DateRange, Dimension, Metric, RunReportRequest def sample_run_report(property_id: str): # Initialize the client. # Assumes Application Default Credentials (ADC) are configured in your environment. client BetaAnalyticsDataClient() request RunReportRequest( propertyfproperties/{property_id}, dimensions[ Dimension(namecity), Dimension(namedate) ], metrics[ Metric(nameactiveUsers), Metric(namesessions) ], date_ranges[ DateRange(start_date2026-05-01, end_datetoday) ], ) response client.run_report(request) print(fReport result for property {property_id}:) for row in response.rows: print( fCity: {row.dimension_values[0].value}, fDate: {row.dimension_values[1].value}, fActive Users: {row.metric_values[0].value}, fSessions: {row.metric_values[1].value} ) if __name__ __main__: sample_run_report(YOUR-PROPERTY-ID)维度与指标 Schema 速查构造RunReportRequest时必须使用合法的 API 名称dimension/metric API name。以下是该技能文档归纳的常用字段SKILL.md常用维度分类属性API 名称含义city用户所在城镇/城市country用户所在国家date事件日期格式为 YYYYMMDDdeviceCategory移动设备类别desktop、mobile、tablet 等eventName触发的事件名称pageTitle网页标题常用指标定量测量API 名称含义activeUsers活跃用户数eventCount事件总次数sessions会话总数screenPageViews应用屏幕或网页浏览量totalRevenue来自购买、订阅与广告的总收入完整的权威字段清单需要以官方 Data API Schema 文档为准若不确定某个字段可调用getMetadata()以编程方式读取属性可用 schema。指标与维度的兼容性检查并非所有维度与指标都能在同一个报告请求中组合查询。若请求返回INVALID_ARGUMENT错误并提示字段不兼容需先校验组合合法性。除人工核对 schema 外该技能提供了两种程序化手段SKILL.mdgetMetadata()程序化读取 Data API schemacheckCompatibility()在真正运行报告前程序化校验特定维度/指标组合的兼容性。完整示例检查电商维度itemName与activeUsers、totalRevenue的兼容性from google.analytics.data_v1beta import BetaAnalyticsDataClient from google.analytics.data_v1beta.types import CheckCompatibilityRequest, Compatibility, Dimension, Metric def sample_check_compatibility(property_id: str): client BetaAnalyticsDataClient() # Define the dimensions and metrics you want to query together. # For example, checking if itemName (an e-commerce dimension) # is compatible with activeUsers and totalRevenue. request CheckCompatibilityRequest( propertyfproperties/{property_id}, dimensions[ Dimension(nameitemName), Dimension(namedate) ], metrics[ Metric(nameactiveUsers), Metric(nametotalRevenue) ], ) response client.check_compatibility(request) print(fCompatibility check for property {property_id}:) for dim in response.dimension_compatibilities: is_compatible dim.compatibility Compatibility.COMPATIBLE print(fDimension {dim.dimension_metadata.api_name} is compatible: {is_compatible}) for metric in response.metric_compatibilities: is_compatible metric.compatibility Compatibility.COMPATIBLE print(fMetric {metric.metric_metadata.api_name} is compatible: {is_compatible}) if __name__ __main__: sample_check_compatibility(YOUR-PROPERTY-ID)从代码可推断CheckCompatibilityRequest结构上对标RunReportRequest同样由property、dimensions、metrics组成而响应中的dimension_compatibilities与metric_compatibilities各自携带dimension_metadata/metric_metadata含api_name与compatibility枚举通过比对Compatibility.COMPATIBLE即可得到布尔判定。多语言客户端库速览该技能在 SKILL.md 中列出了 Data API 官方支持的全部客户端库Python 只是其中一种。各语言安装参考文档位于技能目录的references/下便于按需查阅语言安装方式包/构件名参考文档Pythonpip install google-analytics-datagoogle-analytics-datareferences/python.mdJavaMaven / Gradlecom.google.cloud:google-cloud-analytics-datareferences/java.mdPHPcomposer require google/analytics-datagoogle/analytics-datareferences/php.mdNode.jsnpm install google-analytics/datagoogle-analytics/datareferences/nodejs.mdGogo get cloud.google.com/go/analytics/data/apiv1betacloud.google.com/go/analytics/data/apiv1betareferences/go.md.NETdotnet add package Google.Analytics.Data.V1BetaGoogle.Analytics.Data.V1Betareferences/dotnet.mdRubygem install google-analytics-data-v1betagoogle-analytics-data-v1betareferences/ruby.md从各参考文档可以看出跨语言的一致性设计所有语言均使用 v1beta 版本的BetaAnalyticsDataClientGo 为data.NewBetaAnalyticsDataClient、Ruby 为Google::Analytics::Data::V1beta::AnalyticsData::Client均基于 ADC 自动认证请求体均由property、dimensions、metrics、date_ranges四要素构成且属性 ID 统一使用properties/{id}格式。例如 Java 通过RunReportRequest.newBuilder()链式构建.NET 通过对象初始化器赋值Node.js 通过对象字面量传入runReport()但底层均映射到同一套 protobuf 消息定义。常见错误与排查要点结合技能文档与代码结构可将高频问题归纳如下现象可能原因处置建议gcloud命令找不到未安装 Google Cloud CLI先安装 gcloud再重新执行启用/认证命令pip不可用Python/pip 未安装先安装 Python 3.8 与 pip再执行安装INVALID_ARGUMENT字段不兼容维度与指标组合不合法使用getMetadata()查 schema或先用checkCompatibility()预校验认证失败未配置 ADC 或 scope 不足重新执行gcloud auth application-default login并带上analytics.readonlyscope报告返回空属性 ID 错误或日期范围内无数据核对properties/{property_id}格式与DateRange区间总结google-analytics-data-api-basics技能为 Google Analytics Data APIv1beta的报告查询提供了端到端的最佳实践先通过gcloud services enable analyticsdata.googleapis.com启用 API再用gcloud auth application-default login配置带正确 scope 的 ADC随后在虚拟环境中安装google-analytics-data即可用BetaAnalyticsDataClient配合RunReportRequest编写自动化报表。构建请求时务必使用合法维度/指标 API 名称并在组合不确定时借助checkCompatibility()提前规避INVALID_ARGUMENT。完整的安装细节可进一步阅读 references/python.md多语言参考位于同目录下其余 6 个语言文档。【免费下载链接】skillsAgent Skills for Google products and technologies项目地址: https://gitcode.com/GitHub_Trending/skills29/skills创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考