yandex-direct

Yandex Direct API v5

基本情報

ベース URL

環境	JSON エンドポイント	SOAP エンドポイント
Production	https://api.direct.yandex.com/json/v5/{service}	https://api.direct.yandex.com/v5/{service}
Sandbox	https://api-sandbox.direct.yandex.com/json/v5/{service}	https://api-sandbox.direct.yandex.com/v5/{service}
Reports	https://api.direct.yandex.com/json/v5/reports	同じ形式
Reports (sandbox)	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）

Reports を除き、すべての 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 ポイントが残っており、1 日の上限が 64000 ポイントであることを意味します。

ルール	詳細
1 日の上限	広告主ごとに個別に設定され、キャンペーンのアクティビティに基づきます
リフレッシュ	60 分ごとにポイントが付与されます（直近 24 時間のスライディングウィンドウ）
期間あたり	1 時間ごとに 1 日の上限の 1/24 が付与され、前の 23 時間の未使用分が加算されます
同時リクエスト	広告主ごとに最大 5 件のリクエストを同時に実行できます
エラーコスト	エラーごとに 20 ポイント（サーバーエラーを除く）
1 日の最小上限	アクティブなアカウントでは約 64,000 ポイント
代理店	デフォルトでは広告主のポイントが差し引かれます。代理店は自社のポイントを使うよう選択できます

一般的なエラーコード

コード	意味	対応
53	認証エラー	トークンの有効性を確認します
152	ポイント不足	ポイントのリフレッシュを待ちます（1 時間ごと）
1000	同時リクエスト上限	並列リクエスト数を減らします
1001	操作上限超過	バッチサイズを小さくします
1002	無効なトークン	再認証して新しいトークンを取得します
2000	不明なエラー	時間をおいて再試行します
8800	リクエストごとのオブジェクト上限	バッチサイズを小さくします
9000	ユニット不足	1 日の上限がリフレッシュされるまで待ちます

Sandbox

• 本番環境のデータから完全に分離されています
• Web インターフェースはなく、API のみです
• ライブ API と同じ制限が適用されます
• レポートはリクエストごとに 1 キャンペーンに制限されます
• 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 を直接 source しないでください。以下のラッパースクリプトを使用してください。

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	auto-generated	レポート名

レポートの種類：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 からの source は不可）：

#!/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 (custom)	統計とレポート
Dictionaries	/dictionaries	get	参照データ（地域、通貨など）
Clients	/clients	get, update	広告主アカウント管理
AgencyClients	/agencyclients	add, update, get	代理店クライアント管理
Changes	/changes	check, checkCampaigns, checkDictionaries	変更の追跡
Feeds	/feeds	add, update, delete, get	商品フィード管理
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 を使用してください（1 リクエストあたり最大 10000 件）
• API ポイントを節約するため、実際に必要な FieldNames のみをリクエストしてください
• すべてのデータを再ダウンロードする前に、Changes サービスを使用して変更を検出してください
• レポートでは、processingMode: auto を使用し、200（準備完了）と 201/202（処理中）の両方の HTTP ステータスコードに対応してください
• レポートヘッダーに returnMoneyInMicros: false を設定し、人が読み取れる形式の金額を取得してください
• 代理店アカウントでは、必ず Client-Login ヘッダーを含めてください
• 広告主ごとの同時リクエストは最大 5 件です。リクエストをキューに入れるか、スロットリングしてください
• 開発とテストにはサンドボックス（api-sandbox.direct.yandex.com）を使用してください
• トークンは config/.env に安全に保管してください（このファイルは Gitignore 対象です）
• 標準の API リクエスト／レスポンスにおける金額は、マイクロ単位（1,000,000 倍）です
• レポートの金額には、人が読み取れる形式で取得するために returnMoneyInMicros: false ヘッダーを使用するか、1,000,000 で割ってください