確認日: 2026-08-06
この記事を読む前に
ここで扱うBulk APIは、Ads ManagerのCSV一括アップロードとは別のAdvertiser API機能です。アカウントごとの有効化、APIキー、利用可能な操作、ジョブ結果を確認しながら、まず停止状態で安全に検証するための記事です。
結論
Advertiser APIのBulk APIは、campaign、ad group、adなどの作成・更新操作を一つの非同期ジョブにまとめるための仕組みです。公式Developer Docsでは、1ジョブあたり最大1,000操作、ジョブ作成後のポーリング、操作ごとの結果確認という流れが示されています。
ただし、Bulk APIは限定プレビューです。すべての広告アカウントで使えるとは限らず、エンドポイントが404になる場合は、実装ミスと決めつけず、アカウントチームへ利用可否を確認します。
CSV一括アップロードとの違い
| 比較軸 | Ads Managerの一括アップロード | Advertiser API Bulk API |
|---|---|---|
| 入力 | 管理画面のファイル・テンプレート | APIリクエスト内の操作配列 |
| 実行 | 画面からアップロード | 非同期ジョブを作成して実行 |
| 結果確認 | 画面のエラー・反映状態 | ジョブ状態と操作ごとの結果 |
| 認証 | Ads Managerの操作権限 | 広告アカウントに紐づくAPIキー |
| 注意点 | 列名・ID・親子関係 | 利用可否・冪等性・部分失敗 |
古いCSVテンプレートの列や件数上限を、そのままBulk APIの仕様として扱わないでください。両者を使う場合は、どの経路で変更したかを変更台帳に残します。
実行前の確認
APIキーと広告アカウント
Advertiser APIのAPIキーは広告アカウントに紐づきます。最初に認証を確認し、GETで広告アカウントを取得できる状態を作ります。複数アカウントを扱う場合は、キー、アカウントID、担当者を一つの台帳に記録します。
利用可能な操作
Bulk APIのドキュメントに記載された操作でも、個別アカウントの権限やプレビュー範囲によって実行できない場合があります。検証前に、対象操作、対象リソース、作成か更新かを分けて書き出します。
停止状態で作成する
広告を作成する場合は、まずpausedで作成し、campaign、ad group、adの親子関係、予算、ターゲティング、計測設定をAds Managerで確認します。ジョブが成功したことと、広告を配信してよいことは別の判断です。
非同期ジョブの流れ
- 変更操作を1ジョブにまとめる
- 同一リクエストを誤って再送しないため、冪等性キーを設計する
- Bulk mutation jobを作成する
- 返されたジョブIDで状態をポーリングする
- ジョブ全体の状態と、各操作の成功・失敗を保存する
- 成功したリソースをAds Managerで再確認する
最大1,000操作という上限は、1,000件を無検証で流してよいという意味ではありません。初回は1〜数件のpaused操作で構造を確認し、その後に小さな単位で増やします。
部分失敗を前提にした結果管理
Bulk APIでは、一つのジョブの中で一部操作が失敗する可能性があります。結果を「HTTPが成功した」だけで判定せず、次の台帳を残します。
| 項目 | 記録する内容 |
|---|---|
| job ID | 作成日時と対象アカウント |
| idempotency key | 再送防止のための値 |
| operation index | 操作配列内の位置 |
| resource ID | 作成・更新対象のID |
| status | 成功、失敗、保留 |
| error | エラーコードと本文 |
| next action | 再試行、手動確認、サポート照会 |
validation-onlyの結果は、実際の書き込み成功を保証しません。検証通過後も、権限、アカウント状態、同時変更、利用可能な機能範囲を確認します。
404や再送で迷った時
- Bulk APIのエンドポイントが404: アカウントがプレビュー対象か、利用経路が有効かを確認する
- 認証エラー: APIキーと広告アカウントの組み合わせを確認する
- 一部操作だけ失敗: 失敗操作だけを切り出し、原因を直して再実行する
- タイムアウト: 同じ操作を即時再送せず、ジョブ状態と冪等性キーを確認する
- 作成後に意図と違う状態: Ads Managerの実リソースと変更台帳を照合する
公開前チェックリスト
- [ ] CSV一括アップロードとBulk APIを区別した
- [ ] APIキーと広告アカウントを確認した
- [ ] プレビュー・権限・利用可能な操作を確認した
- [ ] 初回はpausedで作成する設計にした
- [ ] 1ジョブの操作数を数えた
- [ ] 冪等性キーを保存する
- [ ] ジョブIDと操作ごとの結果を保存する
- [ ] validation-onlyを本番成功と解釈していない
- [ ] 部分失敗時の再試行単位を決めた
- [ ] Ads Managerで実リソースを確認する担当を決めた