direct

Yandex Direct — PPC 审计与管理（API v5 / v501）

作者： Nick Serebrov & Kobe 🐍 版本： 2.0.1 — 截至 2026 年 10 月的最新信息

全流程 Yandex Direct 管理：账户审计、广告系列 CRUD、关键词管理、报告、优化和预算分析。

快速参考

命令	功能
/direct audit	全面审计账户（所有广告系列），评分 0-100
/direct campaigns	列出广告系列及其类型、策略、每周预算和统计数据
/direct create	创建包含广告组、关键词和组合广告的统一效果广告系列
/direct keywords	关键词和自动定位（列出、添加、出价、类别、暂停）
/direct report	按优先级 Metrika 目标查看效果统计数据（CTR、CPC、CPA、支出）
/direct optimize	优化建议（暂停表现不佳的项目、调整出价和限额）
/direct budget	每周预算支出分析和预测
/direct negative	根据搜索查询添加否定关键词（广告系列、广告组、共享集）

Direct 中的变化（操作前请了解）

日期	变化	对 Agent 的影响
2023-11 → 2024	统一效果广告系列（UNIFIED_CAMPAIGN，ЕПК）取代文字图片、动态和智能横幅广告系列	读取 UnifiedCampaignFieldNames；搜索和 YAN 位于同一个广告系列中——按 AdNetworkType 拆分统计数据
2024-07-01	YAN 中已禁用手动出价	手动策略（HIGHEST_POSITION）仅适用于搜索
2025-06，2025-09	新增策略：AVERAGE_CPA_MULTIPLE_GOALS、PAY_FOR_CONVERSION_MULTIPLE_GOALS、MAX_PROFIT	请参阅 references/bidding-strategies.md
2025-11-13	已移除 bidmodifiers.toggle	使用 set（100 = 关闭）或 delete
2026-03-20	组合广告（RESPONSIVE_AD）：最多 7 个标题、3 段文本、5 张图片、6 个视频	请求 ResponsiveAdFieldNames，否则 API 会将其作为 TextAd 返回，且仅包含第一个标题、文本和图片
2026-06-30 / 07-14	ЕПК 中的文字图片广告仅可编辑；现有广告已转换为组合广告	使用 TextAd 调用 ads.add 会创建 RESPONSIVE_AD；Title2 会合并到标题中（≤ 56 个字符），否则会丢失
2026-06-22 / 07-06	手动出价广告系列和共享账户现已支持每周预算；最多可结转 30% 的未支出预算	分析 WeeklySpendLimit，而不是每日预算
2026-03-01	面向消费者信息的俄语语言规则	标记广告中没有俄语对应词的外来词（references/compliance.md）

API 配置

凭据：~/.secrets/yandex-direct.json（chmod 600）

{ "client_id": "...", "client_secret": "...", "oauth_token": "...", "client_login": "optional-for-agency" }

• 端点：https://api.direct.yandex.com/json/v5/<service>；add/update 中的 Unified-campaign 结构 （UnifiedCampaign、UnifiedAdGroup、ShoppingAd、ListingAd）应使用 /json/v501/ — scripts/yd-api.sh 会自动路由。
• 身份验证：Authorization: Bearer {oauth_token}；代理商或代表访问：Client-Login: {client_login}。
• 沙盒：YD_SANDBOX=1。环境变量覆盖项：YD_TOKEN、YD_CLIENT_LOGIN、YD_API_VERSION、YD_SECRETS。
• API 请求和响应中的金额单位为微单位（× 1 000 000）。报告使用卢布 （returnMoneyInMicros: false）。

可能导致简单请求失败的 API 限制：

• adgroups.get、keywords.get、ads.get、bidmodifiers.get：每个请求的 CampaignIds ≤ 10，AdGroupIds ≤ 1000。
• 每次 get 最多返回 10 000 个对象；继续请求时将 Page.Offset 设为 LimitedBy。
• negativekeywordsharedsets.get：Ids ≤ 30；省略 SelectionCriteria 即可获取所有集合。sitelinks.get 同理。
• ads.get：TextAdFieldNames 使用 AdExtensions，而非 AdExtensionIds（后者是筛选条件／add 字段）。
• 报告：Goals ≤ 10；AttributionModels 仅支持 AUTO、LSCCD、FCCD、LC；队列中最多有 5 份离线报告。
• keywords.get：Productivity 始终为 null；AutotargetingCategories 已弃用 — 请使用 AutotargetingSettings（AutotargetingSettingsCategoriesFieldNames、AutotargetingSettingsBrandOptionsFieldNames）。

故障排除：

• 每个请求都返回空的 HTTP 204，即使令牌错误也如此 → Yandex 端已关闭 Direct API （例如 2026 年 10 月数据中心事件后的特殊模式：只有网页版界面和移动应用可用，参见 https://yandex.ru/support/direct/ru/special-mode）。这不是令牌、IP 或脚本问题 — 请等待，同时使用网页版界面进行只读检查。
• yd-audit.sh 提示 «no campaigns found» → 所有广告系列可能都已归档；使用 --include-archived 重新运行 （如果脚本能够获取归档数量，会将其打印出来）。
• 广告系列网格将策略标记为 «Оптимизация кликов» / «Оптимизация конверсий»；API 类型位于 BiddingStrategyType（参见 references/bidding-strategies.md）。

变更安全规则

每次写入调用（add、update、delete、suspend、resume、archive、moderate、出价、set） 都只能在用户批准确切变更后执行：展示请求 JSON（或清晰易读的变更差异），并等待用户明确同意。审计、报告和优化均为只读操作。

编排逻辑

/direct audit

1. 运行 scripts/yd-audit.sh <dir> — 收集所有对象（每 10 个广告系列分批，并分页），并使用广告系列的优先目标生成近 30 天的 4 份报告（可通过 --goals 覆盖）。
2. 阅读 <dir>/summary.json：错误、广告系列和广告类型、使用的目标。
3. 将该目录交给 agents/audit-yandex.md（或执行其中的步骤）：根据 references/yandex-audit.md 进行 55 项检查，并根据 references/scoring-system.md 评分。
4. 用俄语报告：评级（A–F）、发现的问题、快速成效、按优先级排序的行动计划。

/direct campaigns

1. campaigns.get：FieldNames 包含 Id、Name、Type、State、Status、StatusClarification、Statistics； UnifiedCampaignFieldNames 和 TextCampaignFieldNames 包含 BiddingStrategy、PriorityGoals、CounterIds。
2. 表格：类型、状态、搜索／网络策略、每周限额（WeeklySpendLimit / 1 000 000）、目标。
3. 消耗和转化数据 — 来自 scripts/yd-report.sh campaign --by-network --goals <priority goals>。

/direct create

1. 收集：名称、地域、每周预算、策略和目标、落地页 URL、关键词、3–7 个标题、2–3 段文案、图片。
2. adimages.add（base64，Type: AUTO）→ 图片哈希；参见 references/image-specs.md。
3. 使用 UnifiedCampaign（v501）调用 campaigns.add：BiddingStrategy.Search/Network、CounterIds、 PriorityGoals、Settings（ADD_METRICA_TAG、ENABLE_SITE_MONITORING）、包含 UTM 的 TrackingParams。
4. 使用 UnifiedAdGroup（v501）调用 adgroups.add：RegionIds、否定关键词。
5. keywords.add：关键词短语和／或 ---autotargeting，并设置 AutotargetingSettings（类别、品牌选项）。
6. sitelinks.add（每组最多 8 个）和 adextensions.add（CALLOUT）。
7. 使用 ResponsiveAd 调用 ads.add：Titles、Texts、Href、AdImageHashes、SitelinkSetId、AdExtensionIds， 如果有 Yandex Business 资料，则添加 BusinessId。不要为此使用 TextImageAd——它是纯图片横幅。
8. ads.moderate——仅在用户审核草稿后调用。

/direct keywords

1. 按 AdGroupIds 或不超过 10 个 CampaignIds 调用 keywords.get；包含 ServingStatus 和自动定向设置。
2. 操作：添加、暂停、恢复、删除、出价（手动策略下使用 keywordbids.set）、自动定向类别。
3. 效果分析——使用 scripts/yd-report.sh criteria（Criterion、CriterionType），而非已弃用的 Productivity。

/direct report

1. scripts/yd-report.sh <preset>：账户、广告系列、广告组、广告、条件、搜索查询、展示位置、自定义。
2. 始终使用优先目标传入 --goals（来自 campaigns.get → PriorityGoals）：不传入时，会汇总所有 Metrika 目标的转化次数， 包括微转化目标。
3. 对于 Unified 广告系列，添加 --by-network，以区分搜索和 YAN。
4. 日期：--from/--to（默认：截至昨天的 30 天）或 --period LAST_7_DAYS。离线报告会自动轮询 （retryIn 标头）。

/direct optimize

1. 生成 30 天内带目标的报告：条件、搜索查询、展示位置、广告系列 --by-network。
2. 查找：花费超过目标 CPA 的 2 倍且没有转化的条件和查询；需要排除的 YAN 展示位置； 同一广告系列中网络与搜索的 CPA 差距；状态为 RARELY_SERVED 的广告组；被拒登的广告元素。
3. 先与账户自身的中位数比较，再参考 references/benchmarks.md。
4. 按影响排序建议；3× 停止规则：标记 CPA > 目标的 3 倍的项目。
5. 学习期间不要更改策略、策略的花费上限类型或付款模式（references/bidding-strategies.md）。

/direct budget

1. 每周限额取自 BiddingStrategy.*.WeeklySpendLimit（投放周期广告使用 CustomPeriodBudget）。
2. 按日统计花费——yd-report.sh campaign --daily --from <Monday>；计算消耗速率和每周预测。
3. 标记：周末前达到限额；花费低于限额的 70%；按转化付费的预算低于 CPA 的 10 倍； 每周预算低于 300 ₽。自 06.07.2026 起，CPC 广告系列未花费的预算可结转（最多 30%）。

/direct negative

1. 广告系列和广告组的否定关键词（NegativeKeywords）及共享集合（negativekeywordsharedsets.get，获取所有集合）。
2. yd-report.sh search_query --goals … → 找出有花费但没有转化的不相关查询。
3. 提出否定关键词（广告系列级或共享集合）；获批后，通过 campaigns.update / negativekeywordsharedsets.update 应用。

质量门槛

• 只有在明确批准具体变更后，才能执行写入操作。
• 只基于优先目标分析转化；绝不使用所有目标的汇总值。
• 3× 停止规则：标记 CPA > 目标 3 倍、应暂停的关键词／广告组／展示位置。
• 策略学习：目标为每周至少 10 次转化；前 2–3 周不要更改策略、花费上限类型或付款模式；暂停超过 7 天会重新开始学习。
• 预算：每周预算 ≥ 300 ₽；按转化付费的预算 ≥ CPA 的 10 倍。
• 审核：优化前检查广告及每个组合元素的 Status/StatusClarification。
• 跟踪：启用 ADD_METRICA_TAG，通过 TrackingParams（广告系列或广告组）或 Href 添加 UTM。

参考文件

按需加载，不要在启动时加载：

• references/yandex-audit.md — 55 项审核检查（YD01-YD55）及数据来源
• references/scoring-system.md — 加权评分（0-100，A-F 等级）
• references/benchmarks.md — 如何比较指标；俄罗斯市场的粗略参考值
• references/bidding-strategies.md — ЕПК 策略 ↔ API、每周预算、学习、出价修正系数
• references/compliance.md — Yandex 审核规则、广告标记、俄语规则
• references/image-specs.md — 组合广告的图片和视频

脚本

• scripts/yd-api.sh — 通用 API 调用封装器（v5/v501 路由、Client-Login、项目级错误检测）
• scripts/yd-report.sh — 报告封装器（预设、目标、归因、离线轮询）
• scripts/yd-audit.sh — 自动收集审核数据（所有对象 + 4 份报告）

要求：bash、curl、jq。

子 Agent

• agents/audit-yandex.md — 用于并行分析广告系列的审核子 Agent