google-analytics

核心用法

本Skill提供Google Analytics 4（GA4）的双API集成能力，通过Maton网关服务代理所有请求。用户需先在Maton平台创建OAuth连接，获取MATON_API_KEY后即可调用：

• Admin API：管理账户层级结构（accounts）、媒体资源（properties）、数据流（dataStreams）、自定义维度（customDimensions）及转化事件（conversionEvents）
• Data API：执行标准报告（runReport）、实时报告（runRealtimeReport）及批量报告（batchRunReports），支持日期范围、维度、指标、排序等完整参数

典型工作流为：通过accountSummaries快速定位可访问资源 → 使用runReport查询活跃用户、页面浏览、转化等核心指标 → 利用metadata端点发现可用维度/指标。

显著优点

1. 零OAuth开发成本：Maton托管Google OAuth流程，用户无需处理token刷新、授权回调等复杂逻辑
2. 双API统一入口：Admin与Data API通过同一网关访问，降低多端点管理成本
3. 多语言示例完备：提供Python（urllib/requests）和JavaScript（fetch）的即插即用代码
4. 连接隔离机制：支持多Google账户场景，通过Maton-Connection头指定特定连接
5. 原生API兼容：网关路径直接映射Google官方API，文档与官方参考100%对应

潜在缺点与局限性

1. 第三方网关锁定：所有数据流经Maton基础设施，存在供应商依赖风险
2. 仅支持GA4：Universal Analytics已废弃，历史UA数据无法查询
3. 速率限制：10 req/sec/账户的硬限制，大规模数据抽取需分批处理
4. 连接管理复杂度：Admin与Data API需分别创建连接，新手易混淆
5. 环境变量敏感：MATON_API_KEY泄露将导致账户级访问权限暴露

适合的目标群体

• 数据分析师：需要快速搭建GA4报表流水线，无需后端开发资源
• 营销运营团队：监控campaign效果、转化漏斗，实时获取流量洞察
• SaaS产品经理：集成用户行为数据至内部BI系统
• 中小技术团队：缺乏专职数据工程师，希望以低代码方式接入Google生态

使用风险

• 数据隐私合规：业务数据经Maton中转，需评估其SOC 2/ISO 27001认证状态
• 服务连续性：Maton网关故障将完全阻断功能，建议设计降级方案
• OAuth范围过度授权：默认连接可能请求超出必要范围的权限，应在Google账户侧定期审计
• 密钥管理：MATON_API_KEY需纳入企业密钥管理系统，避免硬编码或日志泄露

核心功能与用法

Google Analytics Skill 提供完整的 GA4 数据管理能力，通过 Maton 网关代理实现托管式 OAuth 认证，无需自行处理复杂的 Google OAuth 流程。Skill 涵盖两大 API 体系：

Admin API（账户管理）：支持账户查询、媒体资源（Property）创建与管理、数据流配置、自定义维度和转化事件设置。典型场景包括批量创建网站数据流、配置跨域跟踪、设置电商转化事件等。

Data API（报表分析）：支持标准报表、实时报表和批量报表查询，覆盖用户数、会话、页面浏览、跳出率、转化等核心指标，可按地域、设备、流量来源、页面路径等维度切片分析。

使用方式

1. 在 maton.ai 获取 API Key 并设置环境变量 MATON_API_KEY
2. 在 ctrl.maton.ai 分别创建 google-analytics-admin 和 google-analytics-data 两个 OAuth 连接
3. 通过 gateway.maton.ai 代理地址调用 API，Maton 自动注入 OAuth Token

请求示例（Python）：

import requests, os
# 查询账户摘要
accounts = requests.get(
    'https://gateway.maton.ai/google-analytics-admin/v1beta/accountSummaries',
    headers={'Authorization': f'Bearer {os.environ["MATON_API_KEY"]}'}
)

# 运行流量来源报表
report = requests.post(
    'https://gateway.maton.ai/google-analytics-data/v1beta/properties/123456:runReport',
    headers={'Authorization': f'Bearer {os.environ["MATON_API_KEY"]}'},
    json={
        'dateRanges': [{'startDate': '30daysAgo', 'endDate': 'today'}],
        'dimensions': [{'name': 'sessionSource'}, {'name': 'sessionMedium'}],
        'metrics': [{'name': 'sessions'}, {'name': 'conversions'}]
    }
)

显著优势

• 零 OAuth 开发成本：Maton 托管 OAuth 流程，用户仅需完成浏览器授权即可调用 API
• 双 API 统一入口：Admin API 与 Data API 在同一 Skill 内整合，避免多工具切换
• 实时+批量能力：支持实时活跃用户查询（runRealtimeReport）和批量多报表请求（batchRunReports）
• 丰富代码示例：提供 Bash、Python、JavaScript 完整示例，涵盖连接管理、报表查询、错误排查
• 安全设计：API Key 通过环境变量管理，无硬编码风险；仅访问 Google Analytics 数据，不涉及用户隐私数据收集

潜在局限与风险

API 限制与依赖：

• 仅支持 GA4 属性，Universal Analytics 已淘汰不可用
• 依赖 Maton 网关服务可用性，若服务中断则无法调用
• 速率限制为每账户 10 请求/秒，高并发场景需设计队列

功能边界：

• 不支持数据导入（Data Import）和受众群体（Audience）管理
• 自定义查询需熟悉 GA4 维度/指标命名规范，学习成本较高
• 实时报表仅保留 30 分钟活动数据，历史分析需用标准报表

安全注意事项：

• MATON_API_KEY 泄露将导致账号下所有 GA 连接被滥用
• OAuth 连接需分别创建 Admin 和 Data 两种类型，配置错误会导致 400 错误
• 多连接场景需显式指定 Maton-Connection Header，否则可能使用非预期账号

适合人群

• 数据分析师/工程师：需自动化提取 GA4 数据至数据仓库或 BI 系统
• 营销技术团队：需批量配置跟踪属性、管理多账户数据流
• SaaS 产品经理：需在产品内嵌入网站流量分析或用户行为看板
• 运维人员：需监控网站实时流量、设置异常告警

常规风险提示

1. 密钥管理：MATON_API_KEY 应配置在 CI/CD 密钥管理服务或本地环境变量，禁止提交至代码仓库
2. 连接状态监控：定期检查 ctrl.maton.ai 中的连接状态，OAuth Token 过期需重新授权
3. 数据合规：GA4 数据可能包含用户位置、设备信息，需确保符合 GDPR/CCPA 等隐私法规
4. 错误处理：关注 400（连接缺失）、401（密钥无效）、429（速率限制）三类典型错误，实现重试与告警机制