什么是 Google Analytics Data API？从 Ubuntu 自动获取 GA4 报告

关于本文

关于本文
本文是通过利用生成式 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 整体中属于什么部件？

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[改善判断]

先梳理术语

能做什么？

典型的报告操作如下：

最初 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 的职责分工

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 版 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 数据。以更改一处日期范围后结果条数会发生变化作为成功条件。

Google 官方信息

• Google Analytics Data API 概述

• Google Analytics API 快速入门

• 创建报告

• 应用默认凭据 (Application Default Credentials)

• 设置应用默认凭据