Supermetrics

核心功能

Supermetrics 是营销数据整合领域的头部 SaaS 服务商，本技能为其官方 API 封装，允许用户通过自然语言直接查询100+营销平台的核心指标。

核心能力矩阵：

• 数据发现层：discover_sources() 列出全部数据源，discover_accounts() 获取授权账号，discover_fields() 枚举可用指标与维度
• 数据查询层：query_data() 支持异步任务调度，可配置日期范围、时区、多条件过滤（含正则匹配）
• 结果获取层：get_results() 通过 schedule_id 轮询获取最终数据
• 辅助工具：search() 提供智能资源检索，health() 监控服务状态

显著优点：
1. 平台覆盖度极广：单一接口统一接入 Meta、Google、Microsoft、LinkedIn 等主流广告生态，避免多 API 对接成本
2. 异步架构设计：大数据量查询不阻塞，符合生产环境稳定性要求
3. 字段级灵活性：支持 metrics/dimensions 自由组合，满足定制化报表需求
4. 企业级过滤语法：支持正则、包含、比较等多类操作符，复杂场景无需后处理

潜在局限与风险：

• 依赖外部 API 密钥：需自备 SUPERMETRICS_API_KEY，账号授权流程需人工在 Supermetrics 后台完成
• 异步轮询复杂度：query_data 仅返回 schedule_id，需二次调用 get_results，对即时响应场景不够友好
• 数据新鲜度延迟：部分平台（如 Meta Ads）存在 API 数据延迟，实时性不如直接平台后台
• 成本不透明：Supermetrics 本身按数据源数量计费，高频查询可能产生额外 SaaS 费用

适合人群：
数字营销分析师、增长团队、广告代理商及需跨平台整合报表的数据工程师。特别适合已有 Supermetrics 订阅、需将营销数据自动化接入内部 BI 或 AI 工作流的企业用户。

常规风险提示：

• 需妥善保管 API Key，避免泄露导致数据账户被滥用
• 建议对 get_results 设置超时重试机制，防止异步任务挂起
• 自定义日期范围时注意各平台时区差异，避免数据统计口径偏差

核心用法

Supermetrics Skill 是一个专为营销数据分析设计的智能工具，通过与 Supermetrics 官方 API 的深度集成，实现了对 100+ 主流营销平台数据的统一查询能力。用户可通过 Python 函数调用，完成从数据源发现、账户连接、字段查询到数据获取的完整工作流。

该技能采用异步查询设计：首先通过 discover_sources() 获取支持的平台列表（如 FA 代表 Meta Ads、AW 代表 Google Ads、GAWA/GA4 代表 Google Analytics 等），接着使用 discover_accounts() 获取已授权账户，然后通过 discover_fields() 了解可用的指标和维度，最终调用 query_data() 提交查询任务并获取 schedule_id，最后用 get_results() 拉取实际数据。

查询支持丰富的参数配置：时间范围可选择预设周期（如 last_7_days、last_30_days）或自定义日期；过滤条件支持等于、不等于、包含、正则匹配等多种运算符；时区设置采用 IANA 标准。这种设计既保证了灵活性，又通过异步机制避免了大数据量查询的阻塞问题。

显著优点

平台覆盖全面：支持 Google Analytics 4、Meta Ads、Google Ads、LinkedIn Ads、Microsoft Advertising 等 100+ 营销平台，实现真正的跨渠道数据整合，告别多平台手动导出的繁琐操作。

技术架构纯净：Skill 代码仅依赖 Python 标准库（json、os、typing、urllib），无任何第三方依赖包，从根本上杜绝了供应链安全风险，同时保证了极佳的兼容性和启动速度。

接口设计规范：函数命名清晰（discover_、query_、get_*），返回值统一采用 {"success": True/False, "data/error": ...} 的结构，便于程序化处理和错误处理。完整的类型提示和文档说明降低了学习成本。

安全合规到位：通过 GDPR、CCPA 合规性检测，采用 TLS 1.3 加密传输，API 密钥通过环境变量管理，无硬编码敏感信息。Supermetrics 作为 2013 年成立的芬兰企业，具备成熟的企业级数据安全体系。

潜在缺点与局限性

依赖外部服务稳定性：所有数据查询均通过 Supermetrics 官方 API（mcp.supermetrics.com）完成，若该服务出现故障或网络延迟，将直接影响 Skill 可用性。目前 Skill 未实现内置重试机制，偶发网络失败可能影响用户体验。

配置门槛存在：需要用户预先拥有 Supermetrics 账户并获取 API 密钥，对于未使用过 Supermetrics 服务的用户，需要额外的注册和配置流程。环境变量 SUPERMETRICS_API_KEY 的缺失将导致运行时错误。

数据隐私顾虑：用户的营销数据查询参数（账户 ID、指标选择、过滤条件等）需传输至 Supermetrics 服务器处理，虽为功能必需，但对数据主权敏感的企业可能需要额外评估。当前 Skill 未提供数据本地化或边缘计算选项。

功能边界清晰：Skill 定位为数据查询工具，不提供数据可视化、自动报表生成、AI 洞察分析等高级功能，需要与其他工具配合使用才能形成完整的营销分析闭环。

适合的目标群体

数字营销团队：需要日常监控多平台广告效果、整合 Google Ads 与 Meta Ads 投放数据的营销人员，可大幅节省手动下载和整合报表的时间。

营销数据分析师：从事跨渠道 ROI 分析、归因建模、预算优化的专业分析师，可通过标准化 API 接口构建自动化的数据采集管道。

企业 BI 开发者：需要将营销数据汇入企业数据仓库（如 Snowflake、BigQuery）的技术团队，可作为 ETL 流程的前置数据采集组件。

SaaS 产品经理：开发营销 SaaS 产品时需要集成多平台数据源，可利用该 Skill 快速验证 MVP 或构建原型系统。

使用风险说明

网络与性能风险：数据查询依赖远程 API 调用，响应时间受网络状况和查询复杂度影响。大数据量查询可能耗时较长（默认超时 60 秒），建议在异步架构中使用或设置合理的超时预期。

数据授权风险：使用前需确保已正确授权 Supermetrics 访问目标营销账户（如 Google Analytics、Meta Business Manager），授权过期或权限变更将导致查询失败。

成本控制风险：Supermetrics API 通常按查询量或数据行数计费，高频自动化查询可能产生意外费用，建议在生产环境部署前了解清楚 Supermetrics 的定价策略。

版本兼容性风险：各营销平台的 API 可能迭代更新（如 Google Analytics 4 持续演进），字段可用性存在变化可能，建议在生产使用前通过 discover_fields() 动态获取最新字段定义而非硬编码。