GA4 Analytics

核心用法

GA4 技能通过调用 Google Analytics Data API v1，允许用户以命令行方式查询任意 GA4 资产的实时或历史数据。支持标准指标（screenPageViews、sessions、totalUsers、bounceRate 等）与维度（pagePath、sessionSource、deviceCategory 等）的自由组合，并可指定日期范围、过滤条件及输出格式（表格/JSON/CSV）。

典型查询场景：

• 流量分析：--metric sessions --dimension sessionSource 识别核心流量渠道
• 内容表现：--metrics screenPageViews,sessions --dimension pagePath 评估页面价值
• 落地页优化：--metric sessions --dimension landingPage 分析用户入口
• 时间对比：通过 --start/--end 参数自定义分析周期
• 路径过滤：--filter "pagePath=~/blog/" 限定特定内容板块

显著优点

1. 官方数据源：直接对接 Google Analytics 4 原生 API，数据权威性与实时性优于第三方工具
2. 查询灵活性：支持多指标、多维度、自定义过滤器的复杂组合，满足精细化分析需求
3. 输出标准化：内置 JSON/CSV 导出，便于对接 BI 工具或自动化报表流程
4. 无界面依赖：纯 CLI 操作，适合服务器定时任务或 CI/CD 集成

潜在局限

• 认证门槛：需配置 OAuth 2.0（client_id/client_secret/refresh_token）及 GA4 Property ID，首次部署较繁琐
• 配额限制：受 Google API 默认配额约束（如 1,200 请求/分钟/项目），大规模数据提取需分批处理
• 技术依赖：依赖本地 Python3 环境及 scripts/ga4_query.py 脚本，跨平台兼容性未明确说明
• 无可视化：仅输出原始数据，需额外工具生成图表

适合人群

• 数据分析师/增长运营：快速提取 GA4 数据用于自定义分析
• 开发者/运维：构建自动化数据管道或监控告警
• 已有 GCP 项目的企业用户：可复用现有 OAuth 凭证降低配置成本

常规风险

• 凭证泄露风险：OAuth refresh_token 长期有效，若环境变量配置不当可能导致数据泄露
• 权限越界：refresh_token 通常关联完整 GA4 读取权限，建议通过 GCP IAM 限制至最小必要范围
• 数据隐私合规：导出用户级数据（如结合 user_pseudo_id）需确保符合 GDPR/CCPA 等法规要求

核心用法

GA4 Skill 是一个专门用于查询 Google Analytics 4 数据的命令行工具，通过官方 Analytics Data API 获取网站流量、用户行为和转化数据。使用前需一次性配置 OAuth 凭证：设置 GA4_PROPERTY_ID、GOOGLE_CLIENT_ID、GOOGLE_CLIENT_SECRET 和 GOOGLE_REFRESH_TOKEN 四个环境变量。

常用查询场景包括：

• 页面分析：--metric screenPageViews --dimension pagePath 查看热门页面
• 流量来源：--dimension sessionSource 分析各渠道会话数
• 多维指标：同时查询浏览量、会话数、用户数等组合指标
• 自定义筛选：支持日期范围 (--start/--end) 和路径过滤 (--filter)

输出支持表格（默认）、JSON 和 CSV 三种格式，便于对接数据管道。

显著优点

1. 官方接口，数据权威：直接调用 Google Analytics Data API，数据实时准确，非第三方爬虫或模拟登录方案
2. OAuth 安全认证：采用标准 OAuth 2.0 流程，用户自有凭证，工具不接触账号密码
3. 功能完备：覆盖 GA4 核心指标（screenPageViews、sessions、conversions 等）和常用维度（页面、来源、设备、地域等）
4. 实现规范：代码结构清晰，使用官方 google-analytics-data 和 google-auth-oauthlib 库，无自定义网络请求
5. 隐私合规：通过 GDPR 数据最小化、加密传输、用户授权等合规检查

潜在缺点与局限性

• 配置门槛较高：首次使用需完成 Google Cloud 项目设置、API 启用、OAuth 凭证创建和 token 获取流程，对非技术用户不够友好
• 环境变量依赖：凭证存储于环境变量，若运行环境不安全存在泄露风险（需配合 Vault 等 secret 管理工具）
• Token 终端输出：认证脚本将 token 打印至终端，可能被 shell 历史记录捕获（建议使用后清除历史）
• 无内置缓存：重复查询会多次调用 API，可能触及 GA4 配额限制
• 仅限 GA4：不支持 Universal Analytics (UA) 历史数据查询

适合人群

• 网站运营团队：日常监控流量波动、页面表现、转化漏斗
• 产品经理：分析用户行为路径、功能使用热度
• 数据分析师：将 GA4 数据接入 ETL 流程，与其他数据源整合
• 营销团队：追踪 campaign 效果、渠道 ROI

常规风险

| 风险项 | 等级 | 说明 |

|--------|------|------|

| 敏感凭证读取 | 中 | 读取 OAuth 环境变量为功能必需，需确保运行环境安全 |

| 外部 API 调用 | 低 | 仅访问 Google 官方服务，TLS 加密传输 |

| Token 泄露 | 低 | 认证时 token 输出至终端，需妥善保管并清理历史记录 |

总体安全评级 A 级（78分），标准安全级别，适合生产环境使用。建议生产环境采用专用 secret 管理工具替代环境变量存储凭证。