google-analytics-automation

通过 Rube MCP 实现 Google Analytics 自动化

通过 Rube MCP 使用 Composio 的 Google Analytics 工具包，自动化 Google Analytics 4（GA4）报告和资源管理。

前提条件

• 必须已连接 Rube MCP（可用 RUBE_SEARCH_TOOLS）
• 通过 RUBE_MANAGE_CONNECTIONS 建立有效的 Google Analytics 连接，并使用工具包 google_analytics
• 始终先调用 RUBE_SEARCH_TOOLS 以获取当前工具架构

设置

获取 Rube MCP：在客户端配置中将 https://rube.app/mcp 添加为 MCP 服务。添加端点并不代表已授权访问 Google；请使用主机支持的身份验证方式和用户批准的账号。

1. 确认 RUBE_SEARCH_TOOLS 有响应，验证 Rube MCP 是否可用
2. 调用 RUBE_MANAGE_CONNECTIONS，并使用工具包 google_analytics
3. 如果连接状态不是 ACTIVE，请通过返回的身份验证链接完成 Google OAuth
4. 运行任何工作流前，确认连接状态显示为 ACTIVE

核心工作流

确认具体的 GA4 资源/账号和报告时区。解读结果时，记录日期范围、归因范围和响应元数据（阈值处理、抽样以及数据丢失/其他行标记）。不同日期或行中的独立用户数不能相加。请使用当前元数据中的关键事件指标名称，不要假设 conversions 仍受支持。只读分析不代表获准创建/删除关键事件或更改资源设置；仅在用户明确提出请求时执行此类写入操作，并读取结果进行确认。

1. 列出账号和资源

适用场景：用户想要查找可用的 GA4 账号和资源

工具调用顺序：

1. GOOGLE_ANALYTICS_LIST_ACCOUNTS - 列出所有可访问的 GA4 账号［必需］
2. GOOGLE_ANALYTICS_LIST_PROPERTIES - 列出某个账号下的资源［必需］

关键参数：

• pageSize：每页结果数
• pageToken：上一条响应中的分页令牌
• filter：资源的过滤表达式（例如，parent:accounts/12345）

注意事项：

• 资源 ID 是以 properties/ 为前缀的数字字符串（例如，properties/123456）
• 账号 ID 以 accounts/ 为前缀（例如，accounts/12345）
• 始终先列出账号，再列出各账号下的资源
• 资源较多的组织需要分页

2. 运行标准报告

适用场景：用户想要查询 GA4 数据中的指标和维度

工具调用顺序：

1. GOOGLE_ANALYTICS_LIST_PROPERTIES - 获取资源 ID［前置步骤］
2. GOOGLE_ANALYTICS_GET_METADATA - 查看可用维度和指标［可选］
3. GOOGLE_ANALYTICS_CHECK_COMPATIBILITY - 验证维度和指标是否兼容［可选］
4. GOOGLE_ANALYTICS_RUN_REPORT - 执行报告查询［必需］

关键参数：

• property：资源 ID（例如，properties/123456）
• dateRanges：日期范围对象数组，包含 startDate 和 endDate
• dimensions：维度对象数组，包含 name 字段
• metrics：指标对象数组，包含 name 字段
• dimensionFilter / metricFilter：过滤表达式
• orderBys：排序配置
• limit：返回的最大行数
• offset：分页行偏移量

注意事项：

• 日期格式为 YYYY-MM-DD，也可使用 today、yesterday、7daysAgo、30daysAgo 等相对值
• 并非所有维度和指标都兼容；请先使用 CHECK_COMPATIBILITY
• 使用 GET_METADATA 查找有效的维度和指标名称
• 每个报告请求最多可包含 9 个维度
• 行数限制的默认值可能不同；对于大型数据集，请明确设置
• offset 用于结果分页，而非日期分页

3. 运行批量报告

适用场景：用户需要在一次调用中获取同一媒体资源的多种不同报告

工具调用顺序：

1. GOOGLE_ANALYTICS_LIST_PROPERTIES - 获取媒体资源 ID [前置条件]
2. GOOGLE_ANALYTICS_BATCH_RUN_REPORTS - 一次执行多份报告 [必需]

关键参数：

• property：媒体资源 ID（必需）
• requests：各个报告请求对象组成的数组（结构与 RUN_REPORT 相同）

注意事项：

• 每次批量调用最多包含 5 个报告请求
• 批次中的所有报告都必须针对同一媒体资源
• 每份报告的维度和指标限制与 RUN_REPORT 相同
• 批量调用出错可能影响所有报告；请检查各份报告的响应

4. 运行透视报告

适用场景：用户需要类似数据透视表的交叉汇总数据（行与列）

工具调用顺序：

1. GOOGLE_ANALYTICS_LIST_PROPERTIES - 获取媒体资源 ID [前置条件]
2. GOOGLE_ANALYTICS_RUN_PIVOT_REPORT - 执行透视报告 [必需]

关键参数：

• property：媒体资源 ID（必需）
• dateRanges：日期范围对象
• dimensions：所有透视中使用的维度
• metrics：要汇总的指标
• pivots：透视定义数组，包含 fieldNames、limit 和 orderBys

注意事项：

• 透视中使用的维度也必须列在顶层 dimensions 中
• 透视的 fieldNames 引用顶层列表中的维度名称
• 包含多个维度的复杂透视可能生成非常大的结果集
• 每个透视都有独立的 limit 和 orderBys

5. 运行漏斗报告

适用场景：用户需要分析转化漏斗和流失率

工具调用顺序：

1. GOOGLE_ANALYTICS_LIST_PROPERTIES - 获取媒体资源 ID [前置条件]
2. GOOGLE_ANALYTICS_RUN_FUNNEL_REPORT - 执行漏斗分析 [必需]

关键参数：

• property：媒体资源 ID（必需）
• dateRanges：日期范围对象
• funnel：漏斗定义，包含 steps 数组
• funnelBreakdown：可选维度，用于拆分漏斗数据

注意事项：

• 漏斗步骤有先后顺序；每个步骤都定义了用户必须满足的条件
• 步骤使用类似维度/指标过滤器的过滤表达式
• 开放式漏斗允许用户从任意步骤进入；封闭式漏斗要求按顺序逐步推进
• 漏斗报告的处理时间可能长于标准报告

6. 管理关键事件

适用场景：用户需要查看或管理 GA4 中的转化事件（关键事件）

工具调用顺序：

1. GOOGLE_ANALYTICS_LIST_PROPERTIES - 获取媒体资源 ID [前置条件]
2. GOOGLE_ANALYTICS_LIST_KEY_EVENTS - 列出该媒体资源的所有关键事件 [必需]

关键参数：

• parent：媒体资源资源名称（例如，'properties/123456'）
• pageSize：每页结果数
• pageToken：分页令牌

注意事项：

• 关键事件之前在 GA4 中称为“转化”
• 媒体资源必须配置关键事件才能返回结果
• 关键事件名称对应 GA4 事件名称

常见模式

ID 解析

账号名称 -> 账号 ID：

1. Call GOOGLE_ANALYTICS_LIST_ACCOUNTS
2. Find account by displayName
3. Extract name field (e.g., 'accounts/12345')

媒体资源名称 -> 媒体资源 ID：

1. Call GOOGLE_ANALYTICS_LIST_PROPERTIES with filter
2. Find property by displayName
3. Extract name field (e.g., 'properties/123456')

维度/指标查询

1. Call GOOGLE_ANALYTICS_GET_METADATA with property ID
2. Browse available dimensions and metrics
3. Call GOOGLE_ANALYTICS_CHECK_COMPATIBILITY to verify combinations
4. Use verified dimensions/metrics in RUN_REPORT

分页

• 报告：使用 offset 和 limit 对行进行分页
• 账号/媒体资源：使用响应中的 pageToken
• 持续获取，直到没有 pageToken 或达到 rowCount

常见维度和指标

维度：date、city、country、deviceCategory、sessionSource、sessionMedium、pagePath、pageTitle、eventName

指标：activeUsers、sessions、screenPageViews、eventCount、conversions、totalRevenue、bounceRate、averageSessionDuration

已知问题

属性 ID：

• 始终使用完整资源名称格式：'properties/123456'
• 仅使用数字 ID 会导致错误
• 通过 LIST_PROPERTIES 将属性名称解析为 ID

日期范围：

• 格式：'YYYY-MM-DD' 或相对日期（'today'、'yesterday'、'7daysAgo'、'30daysAgo'）
• 由于数据处理延迟，今天的数据可能不完整
• 最大日期范围因属性配置而异

兼容性：

• 并非所有维度都能与所有指标配合使用
• 生成复杂报告前，务必使用 CHECK_COMPATIBILITY 验证
• 自定义维度和指标有特定命名模式

响应解析：

• 报告数据嵌套在 rows 数组中，包含 dimensionValues 和 metricValues
• 返回的值均为字符串；请显式解析数字
• 空报告不会返回 rows 键（而非返回空数组）

快速参考

任务	工具标识	关键参数
列出账号	GOOGLE_ANALYTICS_LIST_ACCOUNTS	pageSize, pageToken
列出属性	GOOGLE_ANALYTICS_LIST_PROPERTIES	filter, pageSize
获取元数据	GOOGLE_ANALYTICS_GET_METADATA	property
检查兼容性	GOOGLE_ANALYTICS_CHECK_COMPATIBILITY	property, dimensions, metrics
运行报告	GOOGLE_ANALYTICS_RUN_REPORT	property, dateRanges, dimensions, metrics
批量运行报告	GOOGLE_ANALYTICS_BATCH_RUN_REPORTS	property, requests
透视报告	GOOGLE_ANALYTICS_RUN_PIVOT_REPORT	property, dateRanges, pivots
漏斗报告	GOOGLE_ANALYTICS_RUN_FUNNEL_REPORT	property, dateRanges, funnel
列出关键事件	GOOGLE_ANALYTICS_LIST_KEY_EVENTS	parent, pageSize

适用场景

此技能适用于执行概述中所述的工作流或操作。

限制

• 仅当任务明确符合上述范围时才使用此技能。
• 请勿将输出视为可替代环境特定的验证、测试或专家审查。
• 如果缺少必需的输入、权限、安全边界或成功标准，请暂停并请求澄清。