> ## Documentation Index
> Fetch the complete documentation index at: https://adcp-docs-ja.pier1.co.jp/llms.txt
> Use this file to discover all available pages before exploring further.
# Migrating from v2 to v3
> AdCP インテグレーションを v2.x から v3.0 に移行する完全ガイド。破壊的変更、工数見積もり、各領域の詳細ページ付き。
# v2 から v3 への移行
このページは、AdCP 2.x から 3.0 にアップグレードする際のすべての破壊的変更を、工数見積もりと詳細な移行ページへのリンクとともにカバーします。新機能については [What's new in v3](/docs/reference/whats-new-in-v3) を、リリース候補の差分については [プレリリースアップグレードノート](/docs/reference/migration/prerelease-upgrades) を、3.0 をサポートする SDK バージョンについては [Schemas and SDKs](/docs/building/schemas-and-sdks#adcp-3-0-support) を参照。
**3.0 から 3.1 にアップグレードしますか？** [3.0 から 3.1 への移行ガイド](/docs/reference/migration/3-0-to-3-1) を使ってください。このページは破壊的な v2.x から 3.0 へのアップグレード用です。
**v2 は 3.0 GA 時点でサポートされず、2026 年 8 月 1 日（UTC）に完全に非推奨になります。** 完全なタイムライン、AAO レジストリポリシー、および v2 が相互運用可能な本番に安全でない理由については [v2 サンセットページ](/docs/reference/v2-sunset) を参照。
**v2 から始めますか？** この完全な移行を進める前にストーリーボードテストに合格するための 8 つの最小要件については [v3 レディネスチェックリスト](/docs/reference/migration/v3-readiness) を参照。
**rc.3 からアップグレードしますか？** [rc.3 → 3.0 プレリリースアップグレードノート](/docs/reference/migration/prerelease-upgrades) が追加の破壊的変更をカバーします: 機能モデルの簡素化、`update_media_buy` での `account` 必須化、`preview_creative` スキーマのフラット化、シグナルでの `signal_id` 必須化、ガバナンスライフサイクルの変更、`pending_activation` ステータスの分割。
## 移行チェックリスト
各行は破壊的変更です。**工数**は典型的な作業を示します。
* **Rename** — フィールド名が変わったが、セマンティクスは同じ。検索置換。
* **Restructure** — 形状が変わった（例: string → object、single → array）。コード変更が必要。
* **Remove** — v2 に存在したが v3 で削除。検索削除。
* **New requirement** — v2 に存在しなかった。新しい実装が必要。
| Area | Change | Effort | Details |
| --------------------- | ------------------------------------------------------------------------------ | --------------- | ------------------------------------------------------------------------------- |
| Channels | `native` 削除 | Restructure | [Channels migration](/docs/reference/migration/channels) |
| Channels | `video` が `olv`、`linear_tv`、`cinema` に分割 | Restructure | [Channels migration](/docs/reference/migration/channels) |
| Channels | 10 の新チャネル追加（`sponsored_intelligence` を含む） | Rename | [Channels migration](/docs/reference/migration/channels) |
| Pricing | `fixed_rate` → `fixed_price` | Rename | [Pricing migration](/docs/reference/migration/pricing) |
| Pricing | `price_guidance.floor` → `floor_price` | Rename | [Pricing migration](/docs/reference/migration/pricing) |
| Pricing | 価格ガイダンスの再構成 | Restructure | [Pricing migration](/docs/reference/migration/pricing) |
| Creatives | `creative_ids` → 重み付き `creative_assignments` | Restructure | [Creatives migration](/docs/reference/migration/creatives) |
| Creatives | `assets` 配列によるアセット探索 | New requirement | [Creatives migration](/docs/reference/migration/creatives) |
| Catalogs | `promoted_offerings` → `sync_catalogs` | Restructure | [Catalogs migration](/docs/reference/migration/catalogs) |
| Geo targeting | フラット配列 → システム指定が必須 | Restructure | [Geo targeting migration](/docs/reference/migration/geo-targeting) |
| Optimization | `optimization_goal`（単一） → `optimization_goals`（配列、判別共用体） | Restructure | [Optimization goals migration](/docs/reference/migration/optimization-goals) |
| Brand identity | `brand_manifest` → `brand` ref（`{ domain, brand_id }`） | Restructure | [Brand identity migration](/docs/reference/migration/brand-identity) |
| Capability discovery | `adcp-extension.json` → `get_adcp_capabilities` | Restructure | [Capability discovery](/docs/protocol/get_adcp_capabilities) |
| Signals | 配信のフラット化、価格の再構成 | Restructure | [Signals migration](/docs/reference/migration/signals) |
| Audiences | `external_id` が必須のトップレベルフィールドに昇格 | Restructure | [Audiences migration](/docs/reference/migration/audiences) |
| Attribution | 整数の日数 → `Duration` オブジェクト | Restructure | [Attribution migration](/docs/reference/migration/attribution) |
| Products | すべての `get_products` リクエストで `buying_mode` 必須 | New requirement | [get\_products reference](/docs/media-buy/task-reference/get_products) |
| Media buy status | `pending_activation` → `pending_start` | Rename | [Media buys](/docs/media-buy/media-buys) |
| Media buy status | `pending_creatives` 追加（クリエイティブがまだ割り当てられていない） | New requirement | [Media buys](/docs/media-buy/media-buys) |
| Task status | レガシー `task_status` と `response_status` フィールドは v3 の `status` と併存させてはならない — 両方削除 | Remove | [Task lifecycle](/docs/building/by-layer/L3/task-lifecycle) |
| Capabilities | `get_adcp_capabilities` の `compliance_testing` 機能ブロック | Additive | [Capability discovery](/docs/protocol/get_adcp_capabilities#compliance_testing) |
| Idempotency | すべての変更リクエストで `idempotency_key` 必須（UUID v4） | New requirement | [Security § Idempotency](/docs/building/by-layer/L1/security) |
| Request signing | RFC 9421 Ed25519 署名プロファイル（3.0 では任意、AdCP Verified では必須） | Additive | [Security § Request signing](/docs/building/by-layer/L1/security) |
| Webhook signing | RFC 9421 プロファイルに統一、セラーにベースライン必須。HMAC フォールバックは非推奨（4.0 で削除） | New requirement | [Webhooks](/docs/building/by-layer/L3/webhooks) |
| Webhook idempotency | すべての webhook ペイロードで `idempotency_key` 必須 | New requirement | [Webhooks § Reliability](/docs/building/by-layer/L3/webhooks) |
| Governance | `governance_context` はガバナンスエージェント JWKS 経由で検証される署名付き JWS | Restructure | [Governance](/docs/governance/campaign) |
| IO approval | `MediaBuy.pending_approval` 削除 — 承認はタスク層のオブジェクト | Restructure | [Media buy lifecycle](/docs/media-buy/media-buys) |
| Regulatory invariants | GDPR 第22条 / EU AI Act 附属書 III がスキーマ `if/then` で強制 | New requirement | [Governance § Annex III obligations](/docs/governance/annex-iii-obligations) |
`get_products` の `buying_mode` はストーリーボードテストでチェックされます。`brief` がベースラインモードです。機能で `wholesale` または `refine` を宣言するセラーは、それらのモードセマンティクスを処理しなければなりません。詳細は [v3 レディネスチェックリスト](/docs/reference/migration/v3-readiness) を参照。
## v3 の新機能 — 必須対オプション
これらの機能は v3 で新しいものです。いずれも v2 に存在しなかったため移行するものはありません — しかしどれがインテグレーションに影響するかを知っておくべきです。
| Capability | Required? | Who needs it |
| ----------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------ |
| Accounts プロトコル（`sync_accounts`、`list_accounts`） | すべてのバイヤーに必須 — `require_operator_auth: false`（バイヤー宣言アカウント）のとき `sync_accounts`、`true` でセラーが account-id 名前空間を公開するとき `list_accounts` | すべてのバイヤー — アカウントが必要かどうかではなく、セラーのアカウントモデルがどのタスクを呼ぶかを決める |
| Brand Protocol（`brand.json`） | 推奨 | すべてのバイヤー — クリエイティブ生成のためのブランドアイデンティティを提供 |
| Governance（コンテンツ標準、プロパティリスト） | オプション | ブランド適合性の強制を必要とするバイヤー |
| Sponsored Intelligence | オプション | 会話型ハンドオフをサポートする AI プラットフォームと連携するバイヤー |
| Registry API | オプション | プログラム的なエージェント/ブランド探索を望むバイヤー |
| Campaign Governance | オプション | コンプライアンスや承認ワークフローを持つ組織 |
## v2 と v3 を並行稼働させる
デュアルサポートは一時的な移行ツールであり、長期的な姿勢ではありません。2026 年 8 月 1 日以降、v3 のみが必須の構成です — [v2 サンセットページ](/docs/reference/v2-sunset) を参照。
移行中、セラーは v2 と v3 の両方のトラフィックを受け入れることができ、バイヤーは各セラーに正しいバージョンでルーティングできます。
1. **セラーの機能を確認** — 各セラーで `get_adcp_capabilities` を呼び出します。成功したレスポンスはセラーが v3 をサポートすることを意味します。バイヤーは `adcp_major_version` でバージョンを宣言し、セラーは `major_versions` で受け入れるバージョンをアドバタイズします。完全なフローについては [バージョンネゴシエーション](/docs/reference/versioning#version-negotiation) を参照。`get_adcp_capabilities` に応答しないセラーは v2 のみです。
2. **セラーごとに分岐** — v3 対応のセラーを v3 インテグレーション経由で、v2 のみのセラーを既存の v2 コード経由でルーティングします。
3. **段階的に移行** — リネーム変更（価格フィールド、チャネル更新）から始め、次に構造変更（クリエイティブ割り当て、最適化目標）に取り組み、次に必要に応じて新機能（アカウント、ガバナンス）を採用します。
## 破壊的移行（v2 → v3.0）
`native` 削除、`video` 分割、10 の新チャネル
フィールドのリネームと価格ガイダンスの再構成
重み付きクリエイティブ割り当てとアセット探索
`promoted_offerings` から一級の `sync_catalogs` へ
グローバルジオサポートのためのシステム指定
単一目標から判別共用体を持つ配列へ
`brand_manifest` から `brand.json` 経由の `brand` ref へ
配信のフラット化と価格の再構成
`external_id` の必須フィールドへの昇格
整数の日数から構造化 `Duration` オブジェクトへ
## 3.1 バッジ準備ガイド
互換性を壊さずに 3.0 に留まれます。3.1 バッジを取得するには、この短い準備チェックリストを完了します。
バイヤー、セラー、エージェント、SDK、コンプライアンスワークフローのための追加的な準備
ビルド機能の探索と価格をフォーマットからトランスフォーマーに移動
成功レスポンスでボディレベルの購入ステータスをエンベロープのタスクステータスから分離