yandex-metrica

yandex-metrica

Yandex Metrica API — 网页分析：计数器、报告、目标、日志导出。

配置

需要在 config/.env 中设置 YANDEX_METRICA_TOKEN。 令牌设置方法请参阅 config/README.md（OAuth，权限：metrika:read、metrika:write）。

快速开始

重要： 始终在技能目录中使用 bash 前缀和绝对路径运行脚本。脚本使用了 bash 特有功能，从 zsh 中获取脚本内容后将无法运行。不要直接 source scripts/common.sh，请使用下面的包装脚本。

# 1. Setup token
bash scripts/get_token.sh --client-id YOUR_CLIENT_ID

# 2. Check connection
bash scripts/check_connection.sh

# 3. List counters
bash scripts/counters.sh --action list

# 4. Get traffic stats
bash scripts/stats.sh --counter 12345678 --preset traffic

# 5. Export raw logs
bash scripts/logs.sh --action create --counter 12345678 --date1 2025-01-01 --date2 2025-01-31

API 概览

基础 URL：https://api-metrika.yandex.net

认证标头：Authorization: OAuth TOKEN

API	用途	基础路径
管理	计数器、目标、筛选条件、授权、细分	/management/v1/
报告	汇总统计、维度、指标	/stat/v1/
日志	原始访问/点击数据导出	/management/v1/counter/{id}/logrequests

脚本

check_connection.sh

验证 API 令牌并列出可用计数器。

bash scripts/check_connection.sh

counters.sh

管理计数器：列出、获取详情、获取包含目标/筛选条件的完整信息。

bash scripts/counters.sh --action list
bash scripts/counters.sh --action list --search "mysite.com"
bash scripts/counters.sh --action info --counter 12345678

stats.sh

使用预设或自定义指标/维度获取报告数据。

# Traffic overview
bash scripts/stats.sh --counter 12345678 --preset traffic

# Traffic sources breakdown
bash scripts/stats.sh --counter 12345678 --preset sources

# Top pages
bash scripts/stats.sh --counter 12345678 --preset content

# Custom report with filters
bash scripts/stats.sh --counter 12345678 \
  --metrics "ym:s:visits,ym:s:users,ym:s:bounceRate" \
  --dimensions "ym:s:lastTrafficSource" \
  --filters "ym:s:trafficSource=='organic'" \
  --date1 2025-01-01 --date2 2025-01-31

# Time-series report
bash scripts/stats.sh --counter 12345678 --type bytime \
  --metrics "ym:s:visits" --date1 2025-01-01 --date2 2025-01-31

# Export to CSV
bash scripts/stats.sh --counter 12345678 --preset sources --csv report.csv

参数	默认值	说明
--counter	环境变量	计数器 ID（必填）
--metrics	visits,pageviews,users	逗号分隔的指标
--dimensions	—	逗号分隔的维度
--date1	30 天前	开始日期 YYYY-MM-DD
--date2	今天	结束日期 YYYY-MM-DD
--filters	—	筛选表达式
--sort	—	排序字段（降序时加前缀 -）
--limit	100	最大行数
--preset	—	traffic、sources、geo、content、technology
--type	data	data、bytime、drilldown、comparison
--csv	—	导出到 CSV 文件

goals.sh

列出并获取计数器的目标。

bash scripts/goals.sh --action list --counter 12345678
bash scripts/goals.sh --action get --counter 12345678 --goal-id 999

logs.sh

通过 Logs API 导出原始数据。

# Check if export is possible
bash scripts/logs.sh --action evaluate --counter 12345678 \
  --date1 2025-01-01 --date2 2025-01-31

# Create log request
bash scripts/logs.sh --action create --counter 12345678 \
  --source visits --date1 2025-01-01 --date2 2025-01-31

# Check status
bash scripts/logs.sh --action status --counter 12345678 --request-id 777

# Download when ready
bash scripts/logs.sh --action download --counter 12345678 \
  --request-id 777 --output ./exports

# Clean up server-side
bash scripts/logs.sh --action clean --counter 12345678 --request-id 777

# List all log requests
bash scripts/logs.sh --action list --counter 12345678

关键指标速查

指标	说明
ym:s:visits	会话数
ym:s:users	独立访客数
ym:s:pageviews	页面浏览总数
ym:s:bounceRate	跳出率 %
ym:s:avgVisitDurationSeconds	平均会话时长
ym:s:newUsers	新访客数
ym:s:goal<ID>reaches	目标完成次数
ym:s:goal<ID>conversionRate	目标转化率
ym:s:ecommerceRevenue	电商收入

关键维度速查

维度	说明
ym:s:trafficSource	流量来源类型
ym:s:lastTrafficSource	最后一次流量来源
ym:s:<attr>UTMSource	UTM 来源
ym:s:<attr>UTMMedium	UTM 媒介
ym:s:startURL	着陆页
ym:s:regionCountry	国家
ym:s:regionCity	城市
ym:s:browser	浏览器
ym:s:deviceCategory	设备类型
ym:s:operatingSystem	操作系统

<attr> = 归因模型：last、first、lastsign 等。

筛选语法

ym:s:trafficSource=='organic'           # equals
ym:s:trafficSource!='organic'           # not equals
ym:s:trafficSource=.('organic','direct') # in list
ym:s:pageViews>5                        # greater than
ym:s:startURL=@'product'               # contains
ym:s:startURL=~'.*product.*'           # regex
ym:s:trafficSource=='organic' AND ym:s:isRobot=='No'  # combine

速率限制

限制	值
通用 API	每个 IP 每秒 30 个请求
Logs API	每个 IP 每秒 10 个请求
并行请求	每个用户 3 个
每日限制	每天 5,000 个请求
报告 API	每 5 分钟 200 个请求

详细参考

有关完整 API 文档（包括所有端点、字段列表、curl 示例和高级功能），请参阅： references/api-reference.md

涵盖内容：管理 API（计数器、目标、筛选条件、操作、授权、标签、细分、用户参数）、报告 API（data、bytime、drilldown、comparison、预设、完整指标/维度）、Logs API（访问/点击字段）。