- Manual Mode:
packages配列で明示的にラインアイテムを指定 - Proposal Mode:
proposal_idとtotal_budgetを指定し、get_productsのプロポーザルを実行
completed、120 秒未満の working、数時間〜数日の submitted)
Request Schema: /schemas/v3/media-buy/create-media-buy-request.json
Response Schema: /schemas/v3/media-buy/create-media-buy-response.json
クイックスタート
2 つのパッケージでシンプルなメディアバイを作成:リクエストパラメーター
* Either
packages OR (proposal_id + total_budget) must be provided.
プロポーザルを実行する場合、返されたプロポーザルの proposal_status によって create_media_buy が有効かどうかが決まります。committed のプロポーザルは expires_at 前に実行でき、draft のプロポーザルは事前に action: "finalize" を指定した get_products の refine 呼び出しが必要です。Finalize は確定条件へのセラーのコミットであり、バイヤーの受諾ではありません。この create_media_buy 呼び出しが受諾/実行のステップです。
TotalBudget オブジェクト
Package オブジェクト
レスポンス
成功レスポンス
confirmed_at はセラーのコミット時刻であり、配信ステータスのタイムスタンプではありません。購入が後で一時停止、再開、配信開始、完了、またはパフォーマンス報告しても更新しないでください。コミット済みの同期作成は即座にこれを刻印します。バイヤーに media_buy_id を返さない場合は submitted レスポンス分岐を使います。セラーは代わりに、暫定購入について media_buy_id、packages、confirmed_at: null を伴う同期成功を返してもよい(MAY)。そのような購入は get_media_buys で取得可能でなければならず(MUST)、コミット時に confirmed_at を正確に一度だけ設定して遷移しなければなりません(MUST)。confirmed_at: null の暫定購入は active であってはならず(MUST NOT)、packages[].committed_metrics を含んではなりません(MUST NOT)。
確定パッケージのレポート契約
レスポンス内の各パッケージはcommitted_metrics を運びうる(MAY)——このパッケージについてセラーが配信レポートで埋めることに合意した拘束的なレポート契約です。このフィールドは、標準メトリクス(閉じた available-metric.json 列挙由来)とベンダー定義メトリクス(BrandRef に紐付く)の両方を運ぶ統一配列で、各エントリは明示的な scope 判別子でタグ付けされ、committed_at でタイムスタンプされます:
confirmed_at が null の場合、セラーは packages[].committed_metrics を省略しなければなりません(MUST)。confirmed_at を設定する最初のレスポンスは初期の committed-metrics セットを含んでもよく(MAY)、各エントリの committed_at は confirmed_at と等しくなければなりません(MUST)。
-
Day-1 のエントリは
committed_at = confirmed_atを共有します。セラーは、プロダクトのreporting_capabilitiesから配信する準備があるものに基づいて、create_media_buyレスポンスで day-1 セットを刻印します。 -
フライト中の追加は
update_media_buyを通じて追記されます——それぞれ独自のcommitted_atタイムスタンプを持つ追記専用です。これにより、セラーは購入をキャンセルして再発行することなく、「Adelaide のアテンションは30日目以降から契約の一部です」と正直に言えます。 -
既存のエントリは不変です。 セラーは、既存エントリを変更または削除しようとする
update_media_buyリクエストをvalidation_error(推奨コード:IMMUTABLE_FIELD)で拒否しなければなりません(MUST)。新しいエントリは追記できます。 -
標準メトリクスの qualifier。 一部のメトリクスは複数の非互換な計測パスを持ち、曖昧さの解消が必要です:
viewability_standard—metric_idがviewable_impressions、viewable_rate、measurable_impressionsのいずれかで、セラーが特定のビューアビリティ標準にコミットする場合(MRC と GroupM は実質的に異なる閾値——viewability-standard列挙を参照)、エントリはqualifier.viewability_standardを持たなければなりません(MUST)。missing_metricsでも対称: MRC ビューアビリティを期待するバイヤーは、GroupM のみの配信レポートを MRC コミットの欠如としてフラグします。completion_source—metric_idがcompletion_rateで、セラーが特定のソース(プレーヤー/広告サーバー自身の完了イベント vs.performance_standard.vendorに紐付く第三者計測ベンダー)にコミットする場合、エントリはqualifier.completion_source(seller_attestedまたはvendor_attested)を持たなければなりません(MUST)。二つのパスは、特に SSAI 環境で実質的に異なるレートを生みうる。missing_metricsでも対称。attribution_methodology—metric_idが成果メトリクス(conversions、conversion_value、roas、cost_per_acquisition、incremental_sales_lift、brand_lift、foot_traffic、conversion_lift、brand_search_lift、units_sold、new_to_brand_rate、new_to_brand_units、leads)で、セラーが特定のアトリビューション手法にコミットする場合、エントリはqualifier.attribution_methodology(リテールメディアのクローズドループにはdeterministic_purchase、その他のパスにはprobabilistic、panel_based、modeled)を持つべきです(SHOULD)。異なる手法の下の二つの成果行は交換不可。missing_metricsでも対称。attribution_window—metric_idが成果メトリクスで、セラーが特定のルックバックウィンドウにコミットする場合、エントリは構造化された期間としてqualifier.attribution_window({ interval: 14, unit: "days" })を持つべきです(SHOULD)。異なるウィンドウの二つの成果行は、バイヤーが誤って期間をまたいで集計しないよう、別々の行として報告されます。
additionalProperties: false)。新しいキーは後続のマイナーで明示的に出荷されます。 -
照合:
get_media_buy_deliveryのmissing_metricsは、committed_metricsをcommitted_at < reporting_period.endのエントリにフィルタし、レポートで埋められていないものをフラグします。フライト中にコミットされたメトリクスは、そのコミットタイムスタンプ以降のみ監査されます。qualifier は逐語的に一致します——コミット済みの{viewable_rate, mrc}は、viewability.standard: groupmを運ぶ配信されたviewable_rateでは満たされません。 -
v1 では任意。 パッケージごとのスナップショットインフラを持たないセラーは段階的に採用できます。欠如は適合ですが、既知の監査ギャップを伴います: スナップショットがなければ、
missing_metricsはレポート時のプロダクトのライブavailable_metricsに対して照合され、作成時にコミットされた内容を反映しないことがあります。committed_metricsを省略するセラーはこのリスクを受け入れます。バイヤーは欠如を「クリーンな配信」ではなく「監査グレードの契約なし」として扱うべきです(SHOULD)。次のメジャーで必須になる見込み。
エラーレスポンス
Submitted レスポンス
購入を同期的に確定できない場合に返されます——例: IO 署名を待つ保証付き購入、ガバナンスレビューのキュー入り、バッチ処理など。完了アーティファクト(tasks/get またはプッシュ通知 Webhook で配信)が media_buy_id と packages を運びます。
プロポーザル固有の受諾 Webhook はありません。人間の承認、IO 署名、または非同期処理を要するプロポーザル実行は、この同じ submitted タスクエンベロープと標準のタスク/Webhook 完了パスを使います。
Note: レスポンスはこれら三つの形状で相互排他です。まず
status でディスパッチします: "submitted" → 非同期エンベロープ、それ以外は成功フィールドにアクセスする前に errors を確認します。
Submitted と同期 Success をいつ返すか(規範的)
submitted と同期成功の選択は呼び出しごとで、プロダクトごとの属性と各特定の作成に対するセラーのポリシーに駆動されます——一律のセラーごとのルールではありません。営業保証のセラーは、同じセッション内で一部の create_media_buy 呼び出しに同期成功を、他に submitted を正当に返しうる。適合的な SDK skill は、入力に関わらずすべての create_media_buy について submitted を返すようエージェントに指示してはなりません(MUST NOT)。一律に submitted を返すセラーは、sales-guaranteed コンプライアンスストーリーボードの非 IO 承認パスで失敗します。
セラーは次の場合に submitted を返さなければなりません(MUST):
- リクエストが
delivery_type: "guaranteed"のプロダクトを一つ以上参照し、かつセラーがrequires_io_approval機能を宣言する場合——人間の承認ハンドシェイクはレスポンス内で完了できません。完了アーティファクトは IO 署名の完了後にtasks/getまたは Webhook で配信されます。 - リクエストが同期的に完了できないセラー側のガバナンスレビューをトリガーする場合(例: 規制業種向けの手動ブランドセーフティレビュー)。
- リクエストが、セラーがレスポンスタイムアウト内に消化できないバッチ処理キューに入る場合。
- 参照されるすべてのプロダクトが
delivery_type: "non_guaranteed"の場合。購入はインラインで作成・確認され、media_buy_idとpackagesが即座に発行されます。これはセラーの専門領域に関わらず適用されます——非保証プロダクトを提供する営業保証のセラーは同期成功を返します。 - リクエストが保証プロダクトを参照し、セラーが
requires_io_approvalを宣言しない場合(まれ。通常はセラーが承認を事前クリアしているリテール SKU や見積レートの保証フロー)。 - 購入が、バイヤーに即座に観測可能な既知の非終端状態(
pending_creatives/pending_start/active/paused)に入る場合。
create_buy_submitted シナリオは requires_io_approval を持つ保証プロダクトをシードし、四つの共有シナリオ(measurement_terms_rejected、pending_creatives_to_start、inventory_list_targeting、invalid_transitions)は非保証プロダクトをシードして同期の media_buy_id 返却を期待します。同期期待のシナリオで submitted を返すセラーはコンプライアンスに失敗します——フィクスチャパターンは sales-guaranteed 専門領域 を参照(オープンブリーフの get_products 呼び出しが同期作成パスに解決されるよう、非保証プロダクトが最初にリストされます)。
このルールは、#3822 で追跡される skill ↔ storyboard の矛盾を解決します: 「すべての create_media_buy にタスクエンベロープを返す」ようエージェントに指示する SDK skill は非適合です。正しい skill は、プロダクトごとの delivery_type とセラーの requires_io_approval 機能でディスパッチするようエージェントに指示します。
主なシナリオ
ターゲティング付きキャンペーン
地理制限やフリークエンシーキャップを追加:コンバージョン最適化付きキャンペーン
コンバージョン最適化配信のために per_ad_spend ターゲットを設定します。プロダクトがconversion_tracking.supported_targets でサポートを宣言しており、sync_event_sources 経由でイベントソースが設定済みである必要があります:
カタログ連動パッケージ
カタログ連動パッケージは、カタログ全体のアイテムに対して単一の予算枠を割り当てます。アイテムごとにパッケージを個別作成する代わりに、プラットフォームがパフォーマンスに基づいてカタログ全アイテムへの配信を最適化します。これは Google Performance Max や Meta Dynamic Product Ads などのカタログベースのキャンペーンタイプに相当する AdCP の機能です。 パッケージにカタログ連動を設定するにはcatalogs フィールドを含めます。各カタログはそれぞれ異なるタイプ(例:プロダクトカタログ 1 件、ストアカタログ 1 件)を持つ必要があります。参照するカタログは sync_catalogs 経由で事前に同期されている必要があります。
同期済みジョブカタログを使ったジョブキャンペーン:
test=false
test=false
by_catalog_item ブレークダウンを返す get_media_buy_delivery を使用します。カタログ連動パッケージのクリエイティブバリアントは、広告としてレンダリングされた個別のカタログアイテムを表します。
明示的なシグナルターゲティング付きパッケージ:
バイヤーがセラー提供のシグナルを特定のパッケージに適用したい場合は targeting_overlay.signal_targeting_groups を使います。選択したプロダクトは signal_targeting_allowed: true を設定し、シグナルを適格にしなければなりません——インラインの signal_targeting_options(存在する場合)、インラインオプションを省略するホールセールプロダクトには get_signals、そして signal_targeting_rules を通じて。常にグループ化された式の形状を使います: トップレベルの operator: "all" と、include グループには operator: "any"、除外グループには operator: "none" を使う子グループ。単純な include のみのターゲティングには一つの any グループを送ります。バイナリシグナルでは、include と除外の両グループで value: true を送ります。除外は value: false ではなく親の none グループで表現します。シグナルは signal_ref で参照します: プロダクトローカルのシグナルオプションには scope: "product"、データプロバイダーが公開する adagents.json の signals[] で定義されたシグナルには data_provider_domain を伴う scope: "data_provider"、ソースネイティブなシグナルには signal_source_url を伴う scope: "signal_source"。これは、sync_audiences を通じて登録されたファーストパーティオーディエンスのみを参照する audience_include / audience_exclude とは別物です。signal_agent_segment_id は、選択したプロダクトオプションまたは get_signals の結果が、セラーが要求する別個の実行ハンドルとしてそれを公開した場合にのみ送ります。
クリエイティブがビルド時の signal_condition(build_creative の signal_conditions ファンアウト由来、#5240)を運ぶ場合、シグナルターゲティングが非互換なパッケージへの割り当て——例: 晴れのクリエイティブを雨ターゲットのパッケージへ——は SIGNAL_TARGETING_INCOMPATIBLE で拒否されます。互換性は、ここで使われる同じ共有 signal_ref アイデンティティで照合されます。規範的なトラフィッキング互換性契約はシグナル仕様を参照してください。
test=false
test=false
クリエイティブをインライン指定したキャンペーン
キャンペーン作成と同時にクリエイティブをアップロードします:レポート用 Webhook を設定したキャンペーン
自動レポート通知を受け取ります。プロポーザルの実行
get_products のプロポーザルを、パッケージを手作業で組まずに実行します。
- パブリッシャーが
total_budgetを使って配分割合を実額に変換 - 配分に基づきパッケージが自動生成
- それ以外のフィールド(brand、start_time、end_time など)は Manual モードと同じ
相関のための Context
context フィールドは、セラーがレスポンスと Webhook でそのまま返す不透明なオブジェクトです。別個のルックアップテーブルを維持することなく、セラーが割り当てた ID を自分の内部システムにマッピングするために使います。
Context は二つのレベルで機能します:
- メディアバイレベル —
create_media_buyレスポンスでエコーされる - パッケージレベル — 各パッケージのレスポンス、Webhook、読み取り面でエコーされ、
package_idを内部ラインアイテムにマッピングするのに有用。明示的なパッケージリクエストでは、セラーはproduct_idもエコーしなければなりません(MUST)。
product_id をエコーしないかもしれない古いセラーのためのレガシーセーフなフォールバックとして、context.buyer_ref のようなパッケージ context を含めます。
内部のキャンペーン ID・ラインアイテム ID へのマッピング:
test=false
test=false
エラーハンドリング
よくあるエラーと解決策:
Example error response:
Key Concepts
フォーマット指定
各パッケージは、使用するフォーマットをformat_ids[](レガシーの名前付きフォーマットパス——構造化された {agent_url, id} 参照)、format_option_refs[](3.1 以降のフォーマットオプションパス——プロダクトの format_options[] への参照)、または直接の正準セレクター(format_kind と任意の params)で指定すべきです(SHOULD)。すべてのフォーマットセレクターを省略すると、プロダクトがサポートするすべてのフォーマットがデフォルトになります。指定することで、システムは次を行えます:
- アドサーバーにプレースホルダークリエイティブを公開する
- 必要なクリエイティブアセットを正確にピン留めする
- プロダクトが要求フォーマットをサポートするか検証する
- 不足しているアセットを追跡する
format_option_refs[] が存在すればそれが勝ち、なければ format_ids[] が存在すればそれが勝ち、なければ直接の format_kind/params が使われ、それもなければパッケージはすべてのプロダクトフォーマットにデフォルトします。バイヤーのコードベースが Product.format_options[] を読み、プロダクトが選択可能な format_option_id 値を公開する場合は format_option_refs[] を使います。レガシーフォーマットのみのセラーやライブラリと統合する場合は format_ids[] を使います。直接の format_kind は、バイヤーがプロダクトローカルの参照なしで対象プロダクト宣言を満たすのに十分な正準パラメータを持つ場合にのみ使います。format_option_refs[] と format_ids[] の二重出力は許可され、混在したセラー集団を対象とするバイヤー SDK には推奨されます——上記の format_ids 行を参照。
3.1 以降のフォーマットオプションの例(パブリッシャースコープの Product.format_options[] エントリに対してバイヤーが作成する場合):
test=false
ブランド参照
brand フィールドはポリシー準拠とビジネス目的のために広告主を識別します。
価格と通貨
各パッケージはpricing_option_id を指定し、以下を決定します:
- 通貨(USD、EUR など)
- 価格モデル(CPM、CPCV、CPP など)
- レートと固定/オークションの区別
ターゲティングオーバーレイ
使用は最小限に — ターゲティングの大部分はブリーフに含め、プロダクト選択で処理されるべきです。 オーバーレイは以下に限定して使用します:- 地理的制限(RCT テスト、規制対応)
- フリークエンシーキャップ
- AXE セグメントの包含/除外(レガシー——新規統合は TMP を使用)
フォーマットワークフロー
フォーマット指定が重要な理由
メディアバイ作成時にフォーマットを指定すると次が可能になります:- プレースホルダー作成 - パブリッシャーが正しい仕様でアドサーバーにプレースホルダーを用意
- 検証 - 要求フォーマットをプロダクトがサポートするかシステムが検証
- 期待値の明確化 - 双方が必要なものを正確に把握
- 進捗トラッキング - 不足アセットと必須アセットを可視化
- 技術セットアップ - クリエイティブ到着前にアドサーバーを設定
完全なワークフロー
フォーマット検証
パブリッシャーが必ず検証する事項:- すべてのフォーマットがプロダクトでサポートされています
- フォーマット仕様が
list_creative_formatsの出力と一致 - 期限内にクリエイティブ要件を満たせる
フライト日程バリデーション
新規メディアバイでは、トップレベルのstart_time は "asap" か、過去でない日時のいずれかでなければなりません(MUST)。過去の具体的な start_time は INVALID_REQUEST エラーを返さなければなりません(MUST)。
パッケージに start_time または end_time を指定した場合、セラーは以下を検証すべきだ:
- 両日程がメディアバイの日付範囲内に収まっています
start_timeがend_timeより前です
INVALID_REQUEST エラーを返すべきだ:
非同期オペレーション
このタスクは即時完了する場合も、複雑さや承認要件によっては日数を要する場合もあります。レスポンスのstatus フィールドで結果と次のアクションを確認してください。
Note: 完全なステータス一覧は Task Lifecycle を参照。
- MCP
- A2A
即時成功 (completed)
タスクが同期的に完了しました。非同期処理は不要です。Request:test=false
status はエンベロープのタスクステータス(TaskStatus)です——同期成功では completed。ボディレベルの media_buy_status は購入のライフサイクル状態(pending_creatives、pending_start、active、paused)を運びます。3.0 形式のレスポンスはこの二つの列挙を同じルートキーで衝突させていました。3.1 ではこれらは別々のフィールドです。セラーは、3.0 バイヤーとの後方互換のため 3.1 非推奨期間中に非推奨のトップレベル status: MediaBuyStatus を出し続けてもよい(MAY)が、3.1 バイヤーは media_buy_status を優先しなければなりません(MUST)。下記の メディアバイステータスフィールド(3.1 移行) を参照。長時間処理 (submitted)
タスクが手動承認キューに入っています。更新を受け取るため Webhook を設定します。Request with webhook:test=false
Error (failed)
Response:使用上の注意
- 総予算は各パッケージの個別の
budget値に基づいて配分されます - クリエイティブアセットはキャンペーン有効化のためにデッドライン前にアップロードしなければなりません
- インプレッション時のターゲティング(オーディエンス、フリークエンシー、適合性)は TMP が処理します
working、submittedなどの保留状態は正常であり、エラーではありません- オーケストレーターは保留状態を通常のワークフローの一部として処理しなければなりません
- インラインクリエイティブ:
creatives配列はパッケージのクリエイティブをインラインで作成または提供します。セラーがcreative.has_creative_library: trueを宣言する場合、インラインクリエイティブはライブラリに入ります。既存のライブラリクリエイティブを更新するにはsync_creativesを、割り当てるにはcreative_assignmentsを使用。セラーがクリエイティブライブラリなしでinline_creative_management: trueを宣言する場合、create_media_buyとupdate_media_buyでpackages[].creativesを使い、sync_creativesは呼びません。 - インラインクリエイティブのライフサイクル: ライブラリ対応のインラインクリエイティブは、
sync_creativesのアップロードと同じライフサイクルでライブラリに入ります。インライン専用のセラーはクリエイティブをパッケージスコープに保ち、後のcreative_idによる再利用を宣言しないことがあります。クリエイティブレビューは購入の結果とは独立しています。セラーは、購入がアクティベートされなかったというだけでレビューをスキップしてはなりません(MUST NOT)。未割り当てのライブラリクリエイティブの保持は 3.0 ではセラー定義です。パッケージ上のインラインクリエイティブを参照。
Content Standards
メディアバイがコンテンツ標準を含む場合(get_products レスポンスの governance.content_standards フィールド、またはメディアバイリクエスト経由)、バイヤーは配信中のブランド適合性の強制を要求しています。
コンテンツ標準は、検証エージェント(例: IAS、DoubleVerify)で
create_content_standards を呼び出すことで作成されます。標準は、セラーのローカル評価モデルが検証エージェントの解釈と整合するよう、本番で使う前に各セラーとキャリブレーションされなければなりません(MUST)。完全なセットアップワークフロー(create → calibrate → activate → validate)はコンテンツ標準の概要を参照してください。ポリシー準拠
ブランドとプロダクトは作成時に検証されます。ポリシー違反はエラーを返します:- ブランド/プロダクトが選択したパッケージと整合しています
- クリエイティブが宣言したブランド/プロダクトと一致しています
- キャンペーンがすべての広告ポリシーに準拠しています
次のステップ
メディアバイ作成後:- クリエイティブの提供: ライブラリ対応のセラーには
sync_creativesを、インライン専用のセラーにはupdate_media_buyのpackages[].creativesを使用 - ステータスの監視:
get_media_buy_deliveryを使用 - 最適化:
provide_performance_feedbackを使用 - 更新:
update_media_buyでキャンペーンを変更
メディアバイステータスフィールド(3.1 移行)
3.1 は、3.0 が同じルートキーで衝突させていた二つの列挙を分割します——すべてのレスポンスの先頭にあるエンベロープのstatus(TaskStatus)と、購入のライフサイクル状態を並べて運ぶボディの media_buy_status(MediaBuyStatus、3.1 の新機能)。レガシーのトップレベル status: MediaBuyStatus 形式は 3.1 で deprecated: true となり、3.2 で削除されます(#4906)。get_media_buys、get_media_buy_delivery、core/media-buy.json のネストされた status は 4.0 で続きます(#4905)。
3.1 バイヤーは、存在する場合 media_buy_status を優先しなければなりません(MUST)。3.1 コンプライアンスストーリーボードは path: "media_buy_status" をアサートします——レガシーの status のみを出す 3.1 セラーはスキーマ上有効ですが認定に失敗します。ストーリーボードが拘束的な適合性チェックです。
完全な移行: 移行 › media_buy_status。
関連ドキュメント
- Media Buy Lifecycle - キャンペーンの完全なワークフロー
- get_products - インベントリの発見
- Targeting - ターゲティング戦略
- Pricing Models - 通貨と価格設定