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 の変更点（操作前に確認してください）

日付	変更点	エージェントへの影響
2023-11 → 2024	統合型パフォーマンスキャンペーン（UNIFIED_CAMPAIGN、ЕПК）がテキスト・画像広告、動的広告、スマートバナー広告に取って代わりました	UnifiedCampaignFieldNames を読み込みます。検索広告と YAN は1つのキャンペーンに含まれるため、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％が繰り越されます	1日あたりの予算ではなく、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>。統合キャンペーン構造体 （UnifiedCampaign、UnifiedAdGroup、ShoppingAd、ListingAd）をadd／updateで使用する場合は、/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：1 リクエストあたりのCampaignIdsは 10 以下、AdGroupIdsは 1000 以下です。
• すべてのgetで返されるオブジェクトは 10 000 個以下です。Page.OffsetにLimitedByを指定して続行します。
• negativekeywordsharedsets.get：Idsは 30 以下です。すべてのセットを取得するにはSelectionCriteriaを省略します。sitelinks.getも同様です。
• ads.get：TextAdFieldNamesで指定するのはAdExtensionIdsではなく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が「キャンペーンが見つかりません」と表示する → すべてのキャンペーンがアーカイブ済みの可能性があります。--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：フレーズ、および／または AutotargetingSettings（カテゴリ、ブランドオプション）を指定した ---autotargeting。
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. パフォーマンス — 非推奨の Productivity ではなく、scripts/yd-report.sh criteria（Criterion、CriterionType）を使用します。

/direct report

1. scripts/yd-report.sh <preset>：account、campaign、adgroup、ad、criteria、search_query、placement、custom。
2. 優先目標（campaigns.get → PriorityGoals）を指定して、必ず --goals を渡します。指定しない場合、マイクロ目標を含むすべての Metrika 目標のコンバージョンが合算されます。
3. Unified キャンペーンでは、検索と YAN を分けるために --by-network を追加します。
4. 日付：--from/--to（デフォルト：昨日までの30日間）または --period LAST_7_DAYS。オフラインレポートは自動的にポーリングされます（retryIn ヘッダー）。

/direct optimize

1. 目標を指定して30日分のレポートを取得します：criteria、search_query、placement、campaign --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 ₽未満の場合。CPC キャンペーンの未消化予算は、06.07.2026以降、最大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。

サブエージェント

• agents/audit-yandex.md — キャンペーンを並列分析するための監査サブエージェント