yandex-direct

Yandex Direct API v5

基本信息

基础 URL

环境	JSON 端点	SOAP 端点
生产环境	https://api.direct.yandex.com/json/v5/{service}	https://api.direct.yandex.com/v5/{service}
沙盒	https://api-sandbox.direct.yandex.com/json/v5/{service}	https://api-sandbox.direct.yandex.com/v5/{service}
报表	https://api.direct.yandex.com/json/v5/reports	相同模式
报表（沙盒）	https://api-sandbox.direct.yandex.com/json/v5/reports	相同模式

身份验证

所有请求都必须在 Authorization 标头中携带 OAuth 令牌。

必需的标头（每个请求）：

标头	值	必需
Authorization	Bearer YOUR_OAUTH_TOKEN	始终需要
Content-Type	application/json; charset=utf-8	始终需要
Accept-Language	ru 或 en	建议
Client-Login	client_login	仅限代理商账户

获取 OAuth 令牌：

1. 在 https://oauth.yandex.ru/client/new 注册应用，并授予 direct:api 权限
2. 获取令牌：https://oauth.yandex.ru/authorize?response_type=token&client_id=YOUR_CLIENT_ID
3. 令牌会显示在重定向 URL 中：#access_token=TOKEN&token_type=bearer&expires_in=31536000
4. 令牌有效期为 1 年

快速设置令牌：

bash scripts/get_token.sh --client-id YOUR_CLIENT_ID

请求格式（JSON）

除报表外，每个 API 请求都遵循以下 JSON 结构：

{
  "method": "get|add|update|delete|suspend|resume|archive|unarchive|...",
  "params": {
    "SelectionCriteria": { ... },
    "FieldNames": ["Id", "Name", ...],
    "Page": { "Limit": 10000, "Offset": 0 }
  }
}

主要模式：

• SelectionCriteria —— 筛选要返回的对象（Ids、CampaignIds、States、Statuses、Types 等）
• FieldNames —— 指定响应中包含哪些字段
• Page —— 分页：Limit（最大值为 10000）和 Offset
• add 方法使用对象数组（例如，"Campaigns": [...]）
• update 方法使用带有 Id 字段的对象数组
• delete 方法使用带有 Ids 数组的 SelectionCriteria

响应格式

{
  "result": {
    "Campaigns": [ ... ],
    "LimitedBy": 10000
  }
}

• 当对象数量超过返回数量时，会出现 LimitedBy（需要分页）

错误响应：

{
  "error": {
    "error_code": 53,
    "error_string": "Authorization error",
    "error_detail": "Token not found or expired"
  }
}

单位（API 点数）系统

每个响应都包含 Units HTTP 标头：Units: spent/remaining/daily_limit

示例：Units: 10/20828/64000 表示已用 10 点，剩余 20828 点，每日限额为 64000 点。

规则	详情
每日限额	每个广告主单独计算，依据广告系列活动情况确定
刷新	每 60 分钟发放点数（滚动 24 小时窗口）
每个周期	每小时获得每日限额的 1/24，加上前 23 小时未使用的点数
并发请求	每个广告主最多同时发出 5 个请求
错误费用	每个错误扣除 20 点（服务器错误除外）
每日最低限额	活跃账户约为 64,000 点
代理商	默认从广告主扣除点数；代理商可以选择使用自己的点数

常见错误代码

代码	含义	处理方式
53	授权错误	检查令牌是否有效
152	点数不足	等待点数刷新（每小时）
1000	并发请求数超限	减少并行请求
1001	超出操作限制	减少批次大小
1002	令牌无效	重新授权并获取新令牌
2000	未知错误	延迟后重试
8800	单次请求的对象数量超限	减少批次大小
9000	单位数不足	等待每日限额刷新

沙盒

• 与生产数据完全隔离
• 无 Web 界面，仅提供 API
• 与正式 API 的限制相同
• 每个请求的报表仅限一个广告系列
• 闲置 1 个月后删除数据
• 角色：广告主或代理商（含 3 个测试客户）
• 在配置中使用 YANDEX_DIRECT_SANDBOX=true，或将基础 URL 设为 api-sandbox.direct.yandex.com

配置

此技能使用 config/.env 存储凭据：

# Required
YANDEX_DIRECT_TOKEN=your_oauth_token

# Optional: sandbox mode
YANDEX_DIRECT_SANDBOX=true

# Optional: agency client login
YANDEX_DIRECT_CLIENT_LOGIN=client_login

脚本

重要： 始终使用 bash 前缀和技能目录中的绝对路径运行脚本。脚本使用了 bash 特有的功能，从 zsh 中加载时将无法运行。请勿直接 source scripts/common.sh，而应使用下方的包装脚本。

check_connection.sh

验证 API 令牌并列出可用的广告系列。

bash scripts/check_connection.sh

campaigns.sh

管理广告系列：列出、获取详情、查看统计数据、暂停／恢复／归档。

# List all campaigns
bash scripts/campaigns.sh --action list

# List only active campaigns
bash scripts/campaigns.sh --action list --states ON

# Get full campaign details
bash scripts/campaigns.sh --action get --ids 12345678

# Get campaign funds/spend info
bash scripts/campaigns.sh --action stats --ids 12345678

# Suspend a campaign
bash scripts/campaigns.sh --action suspend --ids 12345678

# Resume a campaign
bash scripts/campaigns.sh --action resume --ids 12345678

参数	说明
--action, -a	list、get、stats、suspend、resume、archive、unarchive
--ids, -i	以逗号分隔的广告系列 ID
--states, -s	筛选：ON、OFF、SUSPENDED、ENDED、ARCHIVED
--limit, -l	最大结果数（默认值：100）

ads.sh

管理广告：列出、获取详情、暂停／恢复／审核／归档。

# List ads by campaign
bash scripts/ads.sh --action list --campaign-ids 12345678

# List ads by ad group
bash scripts/ads.sh --action list --adgroup-ids 987654

# Get specific ad details
bash scripts/ads.sh --action get --ad-ids 111222333

# Suspend an ad
bash scripts/ads.sh --action suspend --ad-ids 111222333

参数	说明
--action, -a	list、get、suspend、resume、moderate、archive
--campaign-ids	按广告系列 ID 筛选
--adgroup-ids	按广告组 ID 筛选
--ad-ids	指定广告 ID
--limit, -l	最大结果数（默认值：1000）

keywords.sh

管理关键词和自动定向。

# List keywords by campaign
bash scripts/keywords.sh --action list --campaign-ids 12345678

# List keywords by ad group
bash scripts/keywords.sh --action list --adgroup-ids 987654

# Suspend keywords
bash scripts/keywords.sh --action suspend --ids 111,222,333

reports.sh

获取统计报告（广告系列、广告组、广告、关键词级别）。

# Campaign performance (last 30 days)
bash scripts/reports.sh

# Campaign performance for custom date range
bash scripts/reports.sh --date-range CUSTOM_DATE --date-from 2026-01-01 --date-to 2026-01-31

# Ad-level performance
bash scripts/reports.sh --type AD_PERFORMANCE_REPORT \
  --fields "AdId,AdGroupId,Impressions,Clicks,Ctr,AvgCpc,Cost"

# Keyword/criteria performance with filter
bash scripts/reports.sh --type CRITERIA_PERFORMANCE_REPORT \
  --fields "CriteriaType,Criteria,Impressions,Clicks,Ctr,AvgCpc,Cost" \
  --filter '{"Field":"CampaignId","Operator":"EQUALS","Values":["12345678"]}'

# Demographics (age/gender)
bash scripts/reports.sh --type CAMPAIGN_PERFORMANCE_REPORT \
  --fields "Age,Gender,Impressions,Clicks,Ctr,Cost"

# Search queries report
bash scripts/reports.sh --type SEARCH_QUERY_PERFORMANCE_REPORT \
  --fields "Query,Impressions,Clicks,Ctr,Cost"

# Save report to file
bash scripts/reports.sh --output report.tsv

# Predefined date ranges
bash scripts/reports.sh --date-range YESTERDAY
bash scripts/reports.sh --date-range LAST_7_DAYS
bash scripts/reports.sh --date-range THIS_MONTH

参数	默认值	说明
--type, -t	CAMPAIGN_PERFORMANCE_REPORT	报告类型（见下文）
--date-range, -r	LAST_30_DAYS	日期范围预设
--date-from	—	CUSTOM_DATE 的开始日期
--date-to	—	CUSTOM_DATE 的结束日期
--fields, -f	CampaignName,Impressions,Clicks,Ctr,AvgCpc,Cost	字段
--filter	—	筛选条件 JSON
--output, -o	stdout	保存到文件
--name, -n	自动生成	报告名称

报告类型：ACCOUNT_PERFORMANCE_REPORT、CAMPAIGN_PERFORMANCE_REPORT、ADGROUP_PERFORMANCE_REPORT、AD_PERFORMANCE_REPORT、CRITERIA_PERFORMANCE_REPORT、SEARCH_QUERY_PERFORMANCE_REPORT、CUSTOM_REPORT

日期范围：TODAY、YESTERDAY、LAST_3_DAYS、LAST_7_DAYS、LAST_14_DAYS、LAST_30_DAYS、LAST_90_DAYS、THIS_MONTH、LAST_MONTH、ALL_TIME、CUSTOM_DATE

dictionaries.sh

获取参考数据（地区、货币等）。

bash scripts/dictionaries.sh --dict GeoRegions
bash scripts/dictionaries.sh --dict Currencies

高级用法：common.sh 函数

对于上述脚本未涵盖的自定义 API 调用，请使用 common.sh 函数。必须在 bash 脚本内运行（不能从 zsh 中加载）：

#!/bin/bash
source /path/to/scripts/common.sh
load_config
response=$(direct_request "campaigns" '{"method":"get","params":{...}}')

所有 API v5 服务

服务	端点后缀	方法	用途
Campaigns	/campaigns	add, update, delete, get, suspend, resume, archive, unarchive	广告系列管理
AdGroups	/adgroups	add, update, delete, get	广告组管理
Ads	/ads	add, update, delete, get, moderate, suspend, resume, archive, unarchive	广告管理
Keywords	/keywords	add, update, delete, get, suspend, resume	关键词／自动定向管理
BidModifiers	/bidmodifiers	add, set, delete, get	出价调整管理
KeywordBids	/keywordbids	set, setAuto, get	关键词出价管理
AudienceTargets	/audiencetargets	add, delete, suspend, resume, get, setBids	受众定向管理
RetargetingLists	/retargetinglists	add, update, delete, get	再营销列表管理
Sitelinks	/sitelinks	add, delete, get	网站链接组管理
AdExtensions	/adextensions	add, delete, get	宣传语扩展管理
VCards	/vcards	add, delete, get	虚拟名片管理
AdImages	/adimages	add, delete, get	图片管理
AdVideos	/advideos	add, get	视频管理
Creatives	/creatives	add, get	创意管理
Reports	/reports	POST（自定义）	统计与报告
Dictionaries	/dictionaries	get	参考数据（地区、货币等）
Clients	/clients	get, update	广告主账户管理
AgencyClients	/agencyclients	add, update, get	代理商客户管理
Changes	/changes	check, checkCampaigns, checkDictionaries	变更跟踪
Feeds	/feeds	add, update, delete, get	商品 Feed 管理
DynamicTextAdTargets	/dynamictextadtargets	add, delete, get, resume, setBids, suspend	动态广告定向
SmartAdTargets	/smartadtargets	add, update, delete, get, resume, setBids, suspend	智能横幅定向
TurboPages	/turbopages	get	Turbo 页面参数
Businesses	/businesses	get	商家资料数据
Strategies	/strategies	add, update, get, archive, unarchive	投资组合策略管理
NegativeKeywordSharedSets	/negativekeywordsharedsets	add, update, delete, get	共享否定关键词组
KeywordsResearch	/keywordsresearch	hasSearchVolume, deduplicate	关键词预处理
Leads	/leads	get	Turbo 页面表单提交
Bids	/bids	set, setAuto, get	出价管理（旧版）

详细参考

请阅读与所需领域对应的参考文件：

• 广告系列管理（Campaigns、AdGroups、Ads、Keywords、BidModifiers、KeywordBids）——references/campaigns.md
• 定向（AudienceTargets、RetargetingLists、DynamicTextAdTargets、SmartAdTargets）——references/targeting.md
• 扩展（Sitelinks、AdExtensions、VCards、AdImages、AdVideos、Creatives）——references/extensions.md
• 报告（Report 服务、报告类型、字段名称、日期范围、筛选条件、标头）——references/reports.md
• 其他服务（Dictionaries、Changes、Clients、AgencyClients、Feeds、Strategies、NegativeKeywordSharedSets、TurboPages、Businesses、Leads、KeywordsResearch）——references/other-services.md
• 常见用例（常见任务的 bash 脚本示例）——references/use-cases.md

指南

• 批量操作前始终验证令牌是否有效：bash scripts/check_connection.sh
• 使用 Page.Limit 和 Page.Offset 对大型结果集进行分页（每次请求最多 10000 条）
• 仅请求实际需要的 FieldNames，以节省 API 点数
• 使用 Changes 服务检测修改，避免重新下载所有数据
• 对于报告，使用 processingMode: auto，并处理 HTTP 状态码 200（已就绪）和 201/202（待处理）
• 在报告标头中设置 returnMoneyInMicros: false，以获取易读的货币金额
• 对于代理商账户，始终包含 Client-Login 标头
• 每个广告主最多同时发送 5 个请求——请将请求排队或进行限流
• 开发和测试时使用沙箱（api-sandbox.direct.yandex.com）
• 将令牌安全地存储在 config/.env 中（该文件已被 gitignore 忽略）
• 对于标准 API 请求/响应中的货币金额：金额单位为微单位（乘以 1,000,000）
• 对于报告中的货币金额：使用 returnMoneyInMicros: false 标头获取易读的金额，或除以 1,000,000