SuperAPI AI 工具集
合作ENAI 行业资讯收藏
Skill 广场yandex-metrika

yandex-metrika

数据与分析

查看项目

更新于 10-16 15:55

技能介绍

yandex-metrika 技能用于通过 API 操作 Yandex Metrika（Яндекс Метрика），提供按来源与 UTM 标记细分流量、转化与搜索引擎报告，以及 API 分段和计数器直接访问权限管理。

配置要求： 需要在 config/.env 中配置 YANDEX_METRIKA_TOKEN。读取操作需要 metrika:read 权限；创建分段和管理访问权限需要 metrika:write 权限。相关说明见 config/README.md，具体内容资料中暂未提供。

设计理念：

  • 缓存优先：配置数据（计数器、目标、信息）长期缓存；报告按 counter+dates+params 作为键缓存。每次 API 请求前先检查缓存。
  • 上下文窗口卫生：标准输出限制为 30 行，完整数据写入 CSV/文件，缓存可通过 grep/rg 搜索而不加载进上下文。
  • 精确数据：accuracy=1（不采样），默认应用 isRobot 过滤。
  • 归因：默认 lastsign（最后一个有效来源）。首次运行时询问用户。

工作流程： 在任何分析之前：

  1. 获取计数器列表：bash scripts/counters.sh
  2. 如果无法从上下文确定计数器，询问用户："涉及哪个计数器/站点？请提供 ID、名称或域名。"
  3. 如果用户提供了站点/域名，通过 --search 查找：bash scripts/counters.sh --search "metallik"。这是对 TSV（id + name + site）执行 grep，因此也能按域名查找。
  4. 获取计数器信息及其目标：bash scripts/counter_info.sh --counter <ID>；bash scripts/goals.sh --counter <ID>
  5. 询问转化目标："这些目标中哪些是您业务的转化目标？[来自 goals.sh 的目标列表] 我将保存所选目标以供未来报告使用。"
  6. 将配置保存到 cache/counter_<id>/config.json，包含 attribution 和 conversion_goals 字段（每个目标含 id 和 name）。
  7. 根据用户任务运行报告。

分段与访问权限： 对于 API 分段，先确定清晰的名称和 filters 表达式。不带 --apply 的创建和删除会显示计划，不做任何更改。写入前脚本会读取计数器上的最新角色；API 服务端始终是权限的最终来源。创建分段示例：bash scripts/segments.sh --counter <ID> --action create --name "卡片的访问者" --expression "EXISTS(ym:pv:URL=@'/catalog/')"，检查计划后加上 --apply 重试。 获取调用任务的精确登录名，然后检查对计数器的直接访问，必要时准备最小角色：bash scripts/grants.sh --counter <ID> --action get --login <LOGIN>；bash scripts/grants.sh --counter <ID> --action add --login <LOGIN> --permission view，检查计划后加上 --apply 重试。 使用分段通常 view 即可。如果任务不需要修改计数器，不要授予 edit。如果用户选择 analyst 或 edit，通过 --permission 传递该角色；现有角色通过 update 更改。grants 列表包含直接权限；所有者单独显示，账户代表不在此列表中。写入后返回调用任务：计数器编号、分段 ID、登录名和已确认的角色。

脚本： 通用调用模式：bash scripts/<script>.sh --counter <ID> --date1 YYYY-MM-DD [--date2 ...] [--group month] [--csv path]

可用脚本：

  • counters.sh：计数器列表（支持 --search "query"）
  • goals.sh：计数器目标
  • counter_info.sh：计数器元数据
  • traffic_summary.sh：按来源的流量
  • conversions.sh：目标达成（--goals "ID,ID" / --all-goals；默认来自 config.json）
  • utm_report.sh：UTM 细分
  • search_engines.sh：搜索引擎（organic）
  • ecommerce.sh：购买、收入、平均客单价（--currency RUB|USD|EUR；自动来自 counter_info）
  • direct_clients.sh：Direct 登录名
  • direct_costs.sh：Direct 支出（ym:ad:*）（--direct-client-logins "login"；无 --group/--device/--source）
  • comparison.sh：两个时期对比（--date1a/--date2a/--date1b/--date2b；--dimension、--metrics）
  • segments.sh：列出、查看、创建和删除 API 分段（--action；仅带 --apply 写入）
  • grants.sh：按登录名查看所有者和直接访问权限；角色 view、analyst、edit（--action；仅带 --apply 写入）

并非所有脚本都支持所有通用参数，详见各脚本特殊参数。segments.sh 和 grants.sh 管理场景需要 Python 3.10+ 或 uv 来可靠解析 JSON；普通报告仍可在没有它们的情况下运行。

目标报告： conversions.sh 自动按每批六个请求目标并合并为一个 CSV。这适用于 --all-goals、--goals 和 config.json 中的目标。使用 --all-goals 时，先通过 Management API 更新目标列表。合并使用普通 awk；运行报告不需要 Python 和 uv。每个目标保存三个指标：达成目标的访问、达成次数和转化率。列中目标的顺序与所选列表对应。 请求中添加总访问指标，以免零达成的来源在各部分中消失。最终 CSV 中没有服务指标，但无转化的来源会保留；最终转化率计入其访问量。来源按第一个所选目标的达成访问排序，相同时按来源排序。 --limit 限制来源数量：无 --group 时允许 1–100000（默认 100）；有 --group 时为 1–30（默认 30，API 参数 top_keys）。日期不缩短。报告仅在成功获取并合并所有部分后才进入缓存和 --csv。

通用报告参数：

  • --counter：必填，计数器 ID
  • --date1：必填，YYYY-MM-DD
  • --date2：可选，默认今天，YYYY-MM-DD
  • --group：可选，day、week、month
  • --device：可选，默认 all，desktop、mobile、tablet
  • --source：可选，默认 all，organic、ad、referral、direct、social
  • --attribution：可选，默认 lastsign，lastsign、last、first
  • --filters：可选，默认无机器人，报告 API 分段表达式
  • --limit：可选，默认 API 默认值，行数
  • --csv：可选，导出路径
  • --no-cache：可选，跳过缓存

缓存策略： 缓存存储在 cache/ 中：

  • counters.json + counters.tsv：所有计数器
  • counter_<id>/info.json：元数据（永久）
  • counter_<id>/goals.json + goals.tsv：目标
  • counter_<id>/config.json：归因、转化目标
  • counter_<id>/direct_clients.json：Direct 登录名
  • counter_<id>/reports/*.csv：报告结果

分段和访问权限始终重新读取，不缓存：这些数据独立于报告变化，且访问列表包含用户登录名。搜索缓存：grep "text" cache/counters.tsv 或 rg "text" cache/。

扩展场景：

  • 热门搜索查询
  • 任意报告和 JSON 请求（drilldown、metrika_get 等）
  • dimensions/metrics 参考
  • 年同比时期对比
  • Direct 支出和 PnL
  • 用于 Direct 受众定向的 API 分段
  • 广告账户的权限检查和授予
  • API 限制（bytime、scope mixing、drilldown CSV）

API 限制：

  • Reporting API：约 200 请求 / 5 分钟（超过时等待约 5 分钟）
  • 脚本自动处理 429（Retry-After ≤ 60s 则重试，否则失败并给出消息）

适用场景： 适用于需要分析网站流量来源、UTM 标记、转化目标达成、搜索引擎流量、电商数据、Direct 广告支出和访问权限管理的场景。

限制： 需要 Yandex Metrika API 访问令牌和相应权限。具体价格和收费信息暂未提供。segments.sh 和 grants.sh 需要 Python 3.10+ 或 uv。