关于本文
关于本文
本文是通过利用生成式 AI 的自动化生成流程创建的。
查阅 Google Analytics Data API 的官方文档与快速入门，梳理不仅在“界面上查看”，还通过 Python 或 REST 安全地获取 GA4 报告并将其应用于业务的流程。信息确认基准日：2026-09-19
Google 的 API、认证方式、价格与配额、界面名称可能会发生变更。使用时请同时参考文末的 Google 官方信息。
一句话概括
Google Analytics Data API 是以编程方式提取 GA4 报告的官方接口。
GA4（Google Analytics 4）是一项用于分析网站或应用中“来了多少人”、“看了哪些页面”、“发生了哪些事件”等数据的服务。使用 Data API，你可以通过 Python 或 REST 获取报告，而不必每次都打开浏览器进行复制粘贴。 你将了解以下 4 个要点：
Data API 在 Google 整体生态中的位置
GA4 界面、媒体资源（Property）、API 与认证是如何连接的
在制作自动化报告时，Data API 的工作范围在哪里
熟悉微软系分析 API 的人员该如何理解它
它在 Google 整体中属于什么部件？
| 视角 | 定位 |
|---|---|
| 大分类 | Google Marketing Platform / Analytics |
| 分类 | 分析与报告 API |
| 核心目的 | 衡量网站或应用的使用情况，并将其用于改进决策 |
| Data API 的角色 | 将 GA4 媒体资源（Property）的报告数据传递给程序的“获取端” |
| 配合使用的工具 | Google Analytics、Google Cloud Project、OAuth / 服务账号、Search Console、BigQuery 等 |
| 主要使用者 | 网站运营人员、数据分析师、开发人员、运维自动化人员 |
Data API 本身不负责统计访问量。负责统计的是 GA4，而 Data API 是提取已统计数据的部件。
flowchart LR U[サイト利用者] --> SITE[Webサイト / アプリ] SITE --> GA[GA4 Property<br/>計測・集計] GA --> API[Google Analytics Data API<br/>レポート取得口] API --> PY[Python / REST / SDK] PY --> OUT[CSV・社内レポート・ダッシュボード] OUT --> DEC[改善判断]
先梳理术语
| 术语 | 简单来说 |
|---|---|
| Property（媒体资源） | GA4 中汇总统计对象的容器。在 Data API 中需要指定数字形式的 Property ID |
| Dimension（维度） | “按什么查看”数据。例如：日期、国家、页面 |
| Metric（指标） | 统计的数值。例如：activeUsers（活跃用户数）、sessions（会话数） |
| API | 软件之间以规定方式交互功能和数据的接口 |
| SDK / 客户端库（Client Library） | 使 Python 等语言能够更轻松地调用 API 的官方库 |
| ADC | 应用默认凭据（Application Default Credentials）。根据执行环境自动查找认证信息的通用机制 |
能做什么？
典型的报告操作如下：
| 操作 | 用途 |
|---|---|
runReport | 获取常规自定义报告 |
batchRunReports | 批量获取多个报告 |
runPivotReport | 以透视表格式汇总 |
runRealtimeReport | 获取实时数据 |
getMetadata | 检查可用的维度 / 指标 |
最初 runReport 比较容易理解。例如，你可以每天早晨获取“过去 7 天按日期划分的 activeUsers”。
与 GA4 界面的关系
Data API 并不是“另一个 Analytics”。它是从程序端处理 GA4 媒体资源报告的入口。
sequenceDiagram participant Job as Ubuntu / Python participant Auth as Google認証 participant API as Analytics Data API participant GA as GA4 Property Job->>Auth: 認証情報を使って認証 Auth-->>Job: 利用可能な資格情報 Job->>API: runReport(Property ID, Dimension, Metric) API->>GA: レポートデータを参照 GA-->>API: 集計結果 API-->>Job: レポート応答 Job->>Job: 必要列だけ保存・加工
这里重要的一点是：完成认证与能够读取目标媒体资源是两码事。调用主体必须在目标 GA4 媒体资源侧拥有必要的访问权限。
如何看待认证？
根据 2026-09-19 的官方快速入门，同时介绍了用户账号和服务器账号（Service Account）。在本地开发时会使用用户凭据，而在自动处理时则会选择符合执行环境的服务账号等配置。
ADC（应用默认凭据）是一种不将敏感信息直接写入代码、而是从执行环境中查找可用凭据的机制。在 Google Cloud 上的生产环境中，应优先考虑尽可能将服务账号绑定到资源并使用短期凭据的方式，避免轻率分发长期的服务账号密钥。
在 Python 中尝试安全读取
接下来是一个类似于官方快速入门的读取示例。其中的媒体资源 ID 为虚拟数据。
from google.analytics.data_v1beta import BetaAnalyticsDataClient
from google.analytics.data_v1beta.types import DateRange, Dimension, Metric, RunReportRequest
PROPERTY_ID = "000000000" # ダミー。実値を公開リポジトリへ固定しない
client = BetaAnalyticsDataClient()
request = RunReportRequest(
property=f"properties/{PROPERTY_ID}",
dimensions=[Dimension(name="date")],
metrics=[Metric(name="activeUsers")],
date_ranges=[DateRange(start_date="7daysAgo", end_date="yesterday")],
)
response = client.run_report(request)
for row in response.rows:
print(row.dimension_values[0].value, row.metric_values[0].value)
看什么？
确认是否按行返回了日期和 activeUsers 的值。
成功条件
如果没有出现认证错误或权限错误，并且返回了目标时间段的报告行，则说明基础确认成功。如果返回 0 行，请不要直接断定为“API 失败”，而应检查时间段、维度 / 指标、媒体资源以及是否存在实际数据。
尝试修改一处
Dimension(name="date") 将其更改为其他可用的维度，可以改变“按什么进行汇总”。在修改前先检查元数据或官方的维度 / 指标列表会更安全。
如果在 Ubuntu 上进行定期执行
systemd timer
↓
Python
↓
ADC / 実行環境の認証
↓
Analytics Data API
↓
必要な列だけ抽出
↓
CSV / レポート
即使不得不使用服务账号密钥文件，也不要在正文、GitHub 或 systemd unit 中写入私钥本身。即使通过环境变量传递文件路径，也应将该文件本身排除在 Git 管理之外。
如何在工作中应用？
普通用户、文职人员 / 网站运营人员
可以用固定的指标生成 CSV，来代替每周手动复制访问报告。建议先从“日期・activeUsers”这样的小型报告开始，这样更容易确认数字的含义。
IT 管理员
负责管理以谁的凭据运行、目标媒体资源的权限、Cloud Project、API 启用状态、配额、敏感信息存储方式以及失败日志。有时认证与权限设计比自动化脚本本身更为重要。
开发人员
runReport将 、Realtime、Pivot 等集成到应用或批处理中。设计时应避免直接公开 API 响应，而只保存业务所需的数据。
与 Search Console、AdSense、BigQuery 的职责分工
| 服务 | 主要观察对象 | 与 Data API 的关系 |
|---|---|---|
| Analytics Data API | 网站/应用内的使用情况 | 获取 GA4 报告 |
| Search Console API | Google 搜索中的展示与点击 | 补充搜索引流侧的数据 |
| AdSense Management API | 广告报告 | 补充收益侧的数据 |
| BigQuery | 海量数据存储与 SQL 分析 | 可用作更自由的数据分析平台 |
flowchart LR SC[Search Console API<br/>検索前] --> SAFE[必要項目だけの分析データ] GA[Analytics Data API<br/>サイト内] --> SAFE AD[AdSense API<br/>収益] --> SAFE SAFE --> REPORT[改善レポート]
即使将这三者结合使用，也无需保存个人信息或不必要的标识符。应将其精简为分析目的所需的最小限度项目。
熟悉微软技术的人应该如何理解？
虽然没有完全一一对应的产品，但“通过 API 获取管理后台数据并连接到自动报告”这一思路，类似于 Microsoft Graph 以及各微软服务的报告 API。
| 视角 | Google Analytics Data API | 面向熟悉微软系 API 人员的理解方式 |
|---|---|---|
| 对象 | GA4 报告 | 类似于特定微软服务的报告/数据 API |
| 认证 | Google OAuth / ADC 等 | 类似于在 Entra ID 中获取 Token 后调用 API 的思路 |
| 数据容器 | GA4 Property | 与 Tenant 或 Workspace 等并非同一概念。这是 GA4 专有的统计单位 |
| API 的角色 | 获取已分析的报告 | 类似于将管理后台替换为自动化获取路径的印象 |
将其完全视为“Google 版 Microsoft Graph”进行替换理解是不准确的。Data API 是针对 GA4 这一特定服务的分析报告 API。
切勿凭固定值记忆价格与配额
API 的使用条件和配额可能会发生变化。在实现时，请根据基准日确认 Google 官方的 Data API 文档和配额页面。就像需要为 Google Cloud Project 设置计费的其他服务一样，重要的一点是不要盲目猜测固定费用。
安全方面的底线要求
切勿将服务账号 JSON、私钥（private key）、访问令牌（access token）、刷新令牌（refresh token）保存到 GitHub 中
将目标 GA4 媒体资源的权限限制在最低必要范围内
公开数据中不得包含电子邮箱或不必要的标识符
在生产环境中，如果条件允许，相比长期的服务账号密钥，应优先使用已绑定的服务账号等短期凭据
切勿在日志中输出 Token 或敏感信息
常见的误解
Property ID 就是 Measurement ID 吗？
不是。Data API 中指定的是数字形式的 GA4 Property ID。它与网页统计中看到的 G-... 的 Measurement ID 作用不同。
创建了服务账号就能立即读取吗？
不是。除了创建认证主体之外，还需要在目标 GA4 媒体资源侧赋予必要的访问权限。
Data API 会自动帮我们统计网站数据吗？
不会。Data API 只是获取已统计的 GA4 报告的部件。
这到底是一个怎样的服务？
Google Analytics Data API 是连接GA4 分析结果与个人程序的官方出口。它并不是负责网站统计本身的服务，而是将累积并汇总在 GA4 媒体资源中的报告传递给 Python 或 REST。
因此在实际业务中，不仅要“编写 API 代码”，还应遵循GA4 媒体资源 → 权限 → 认证 → Data API → 仅保存必要项目 → 改进决策这一连串的流程来思考，会更容易理解。
通过 Papanda 实践理解：将 GA4 报告从“表格转换为图表”
可见成果：将包含维度/指标的小型报告转换为 CSV，并在浏览器或 Excel 中以图表形式展示。Daily Code 将实际的 API 获取部分与可视化部分分离，公开版本中使用虚拟 analytics 数据。以更改一处日期范围后结果条数会发生变化作为成功条件。
