コレクションリスト管理

コレクションリストは、「これらのコレクション、これらの基準でフィルターされた」を表現する管理された、キャッシュ可能なアーティファクトです。プロパティリストと並行しますが、技術的表面（ドメイン、アプリ）ではなくコンテンツプログラム（番組、シリーズ、ポッドキャスト）で動作します。

アーキテクチャ

SETUP TIME                          BID TIME                    REFRESH
─────────────                       ────────                    ───────
Buyer creates list ──► Governance    Seller uses cached ◄── Webhook notifies
  base_collections      agent          collection list        seller to
  + filters             resolves                              re-fetch
                        & caches

コレクションリストは セットアップ時リソース です。ガバナンスエージェントによって一度解決され、セラーによってキャッシュされ、ガバナンスエージェントへのランタイム呼び出しなしに配信決定で使われます。

タスク概要

Task	Purpose	Response time
`create_collection_list`	新しいコレクションリストを作成	秒
`get_collection_list`	解決されたコレクションを伴うリストをフェッチ	秒（キャッシュ済み）
`update_collection_list`	ベースコレクションまたはフィルターを変更	秒
`list_collection_lists`	アカウントのコレクションリストをリスト	秒
`delete_collection_list`	コレクションリストを削除	秒

ベースコレクションソース

コレクションリストは、3 つのパターンで選択されたコレクションのベースセットで始まります:

distribution_ids

プラットフォーム非依存の識別子でコレクションを選択します。クロスパブリッシャー除外の主要メカニズム — IMDb ID は、どの CTV プラットフォームが運ぶかにかかわらずプログラムを識別します。

{
  "selection_type": "distribution_ids",
  "identifiers": [
    { "type": "imdb_id", "value": "tt9999901" },
    { "type": "gracenote_id", "value": "SH000001" },
    { "type": "eidr_id", "value": "10.5240/XXXX-XXXX-XXXX-XXXX-XXXX-C" }
  ]
}

publisher_collections

パブリッシャーの adagents.json 内の特定のコレクションをコレクション ID で選択します。パブリッシャーの内部識別子が既知のときに使います。

{
  "selection_type": "publisher_collections",
  "publisher_domain": "titanstreaming.com",
  "collection_ids": ["danger_zone", "wild_nights"]
}

publisher_genres

ジャンル基準に一致するパブリッシャーのすべてのコレクションを選択します。特定のパブリッシャーからコンテンツカテゴリー全体を除外するときに使います。

{
  "selection_type": "publisher_genres",
  "publisher_domain": "streamhaus.com",
  "genres": ["news"],
  "genre_taxonomy": "iab_content_3.0"
}

base_collections が省略されると、リストはガバナンスエージェントのコレクションデータベース全体に対してフィルターを適用します。

フィルター

フィルターはベースコレクション選択の後、解決されたリストを狭めます:

Filter	Type	Logic	Description
`content_ratings_exclude`	ContentRating[]	OR	これらのレーティングのいずれかを持つコレクションを除外
`content_ratings_include`	ContentRating[]	OR	これらのレーティングを持つコレクションのみを含む
`genres_exclude`	string[]	OR	任意のジャンルでタグ付けされたコレクションを除外
`genres_include`	string[]	OR	任意のジャンルを持つコレクションのみを含む
`genre_taxonomy`	string	—	ジャンルフィルター値の分類
`kinds`	string[]	OR	コレクション種類にフィルター（series、publication、event_series、rotation）
`exclude_distribution_ids`	DistributionId[]	OR	これらの特定のコレクションを常に除外
`production_quality`	string[]	OR	制作品質階層でフィルター

Include 対 exclude: include フィルターは allowlist、exclude フィルターは blocklist です。両方が同じ次元に存在するとき、include が最初に適用され、次に exclude がさらに狭めます。例: genres_include: ["drama", "comedy"] と genres_exclude: ["crime"] を持つリストは、まずドラマとコメディのコレクションのみを含め、次に crime としてタグ付けされたものを削除します。["drama", "crime"] とタグ付けされたコレクションは除外されます — exclude フィルターが勝ちます。["sports"] とタグ付けされたコレクションは include フィルターによって除外されます（許可されたセットにない）。 コンテンツレーティングはメタデータフィルターであり、コンテンツ評価ではありません。 content_ratings_exclude: [{ system: "tv_parental", rating: "TV-MA" }] は TV-MA として 宣言された すべてのコレクションを除外します。個別のエピソードを評価しません — それはコンテンツ標準です。 ジャンル分類 はバイヤーとセラー間のジャンルマッチングを正規化します。サポートされる分類: iab_content_3.0、iab_content_2.2、gracenote、eidr、apple_genres、google_genres、roku、amazon_genres、custom。custom 値はパブリッシャー定義の分類のエスケープハッチです — バイヤーとセラーが帯域外で語彙を交渉します。

create_collection_list

ガバナンスエージェントに新しいコレクションリストを作成します。 Request:

{
  "$schema": "https://adcontextprotocol.org/schemas/v3/collection/create-collection-list-request.json",
  "idempotency_key": "c5d6e7f8-a9b0-4123-c456-123456789012",
  "name": "Nova Motors CTV Do Not Air — 2026",
  "description": "Programs excluded from Nova Motors CTV advertising",
  "base_collections": [
    {
      "selection_type": "distribution_ids",
      "identifiers": [
        { "type": "imdb_id", "value": "tt9999901" },
        { "type": "imdb_id", "value": "tt9999902" }
      ]
    },
    {
      "selection_type": "publisher_genres",
      "publisher_domain": "streamhaus.com",
      "genres": ["news", "crime"],
      "genre_taxonomy": "iab_content_3.0"
    }
  ],
  "filters": {
    "content_ratings_exclude": [
      { "system": "tv_parental", "rating": "TV-MA" },
      { "system": "bbfc", "rating": "18" }
    ],
    "genres_exclude": ["news"],
    "genre_taxonomy": "iab_content_3.0",
    "kinds": ["series"]
  },
  "brand": { "domain": "novamotors.com" }
}

Response:

{
  "$schema": "https://adcontextprotocol.org/schemas/v3/collection/create-collection-list-response.json",
  "status": "completed",
  "list": {
    "list_id": "cl_novamotors_dna_2026",
    "name": "Nova Motors CTV Do Not Air — 2026",
    "collection_count": 247,
    "created_at": "2026-04-07T12:00:00Z",
    "updated_at": "2026-04-07T12:00:00Z"
  },
  "auth_token": "tok_example_store_this_securely"
}

auth_token は作成時にのみ返されます。それを保存してください — それはセラーにこのリストをフェッチする認可を与えます。

get_collection_list

解決されたコレクションを伴うコレクションリストを取得します。セラーはリストをフェッチしキャッシュするためこれを呼びます。 Request:

{
  "$schema": "https://adcontextprotocol.org/schemas/v3/collection/get-collection-list-request.json",
  "list_id": "cl_novamotors_dna_2026",
  "resolve": true,
  "pagination": {
    "max_results": 1000
  }
}

Response:

{
  "$schema": "https://adcontextprotocol.org/schemas/v3/collection/get-collection-list-response.json",
  "status": "completed",
  "list": {
    "list_id": "cl_novamotors_dna_2026",
    "name": "Nova Motors CTV Do Not Air — 2026",
    "collection_count": 247
  },
  "collections": [
    {
      "collection_rid": "019abc12-3d4e-7f5a-ab6c-7d8e9f0a1b2c",
      "name": "Danger Zone",
      "distribution_ids": [
        { "type": "imdb_id", "value": "tt9999901" }
      ],
      "content_rating": { "system": "tv_parental", "rating": "TV-MA" },
      "genre": ["comedy", "animation"],
      "genre_taxonomy": "iab_content_3.0",
      "kind": "series"
    }
  ],
  "pagination": { "has_more": false },
  "resolved_at": "2026-04-07T14:00:00Z",
  "cache_valid_until": "2026-04-14T14:00:00Z",
  "coverage_gaps": {
    "genre": [
      { "type": "imdb_id", "value": "tt9999905" }
    ]
  }
}

カバレッジギャップ は、フィルターされた次元のメタデータが欠けているにもかかわらずリストに含まれたコレクションをレポートします。この例では、tt9999905 は含まれましたがジャンルメタデータがありません — ガバナンスエージェントはそれがジャンルフィルターに一致することを確認できませんでした。 キャッシング: セラーは解決されたコレクションをキャッシュし cache_valid_until の後に再フェッチすべきです。デフォルトキャッシュ期間は 168 時間（1 週間）です。コレクションメタデータはプロパティメタデータより頻繁に変わらないからです。

update_collection_list

既存のコレクションリストを変更します。base_collections と filters はパッチではなく完全な置き換えです。

{
  "$schema": "https://adcontextprotocol.org/schemas/v3/collection/update-collection-list-request.json",
  "idempotency_key": "d6e7f8a9-b0c1-4234-d567-234567890123",
  "list_id": "cl_novamotors_dna_2026",
  "base_collections": [
    {
      "selection_type": "distribution_ids",
      "identifiers": [
        { "type": "imdb_id", "value": "tt9999901" },
        { "type": "imdb_id", "value": "tt9999902" },
        { "type": "imdb_id", "value": "tt9999903" }
      ]
    }
  ],
  "filters": {
    "content_ratings_exclude": [
      { "system": "tv_parental", "rating": "TV-MA" }
    ]
  },
  "webhook_url": "https://governance.pinnacleagency.com/webhooks/collection-lists"
}

list_collection_lists

アカウントのコレクションリストをリストします。解決されたコレクションではなくメタデータのみを返します。

{
  "$schema": "https://adcontextprotocol.org/schemas/v3/collection/list-collection-lists-request.json",
  "account": { "brand": { "domain": "novamotors.com" }, "operator": "pinnacleagency.com" },
  "pagination": { "max_results": 50 }
}

delete_collection_list

コレクションリストを削除します。キャッシュされたコピーを持つセラーは webhook 更新の受信を停止します。

{
  "$schema": "https://adcontextprotocol.org/schemas/v3/collection/delete-collection-list-request.json",
  "idempotency_key": "e7f8a9b0-c1d2-4345-e678-345678901234",
  "list_id": "cl_novamotors_dna_2026"
}

Webhook

コレクションリストの解決されたコレクションが変わるとき（新しいプログラムが一致、レーティング更新、プログラム削除）、ガバナンスエージェントは webhook 通知を送ります:

{
  "idempotency_key": "clch_01HW9DEPJ5MN8Q2R4T6V8X0Z2B",
  "event": "collection_list_changed",
  "list_id": "cl_novamotors_dna_2026",
  "list_name": "Nova Motors CTV Do Not Air — 2026",
  "change_summary": {
    "collections_added": 3,
    "collections_removed": 1,
    "total_collections": 249
  },
  "resolved_at": "2026-04-08T10:00:00Z",
  "cache_valid_until": "2026-04-15T10:00:00Z",
  "signature": "..."
}

Webhook はサマリーのみを含みます — 受信者は更新されたエントリーのため get_collection_list を呼ばなければなりません。受信者は処理前に signature を検証しなければならず（MUST）、同じ変更イベントのリトライ配信が無視されるよう idempotency_key で重複排除しなければなりません（MUST）。

ライブスポーツ

ライブスポーツは最大の CTV ブランドセーフティ懸念の 1 つです。コレクションリストは event_series 種類を通じてそれを処理します:

{
  "$schema": "https://adcontextprotocol.org/schemas/v3/collection/create-collection-list-request.json",
  "idempotency_key": "f8a9b0c1-d2e3-4456-f789-456789012345",
  "name": "Acme Outdoor — Excluded Sports Events",
  "base_collections": [
    {
      "selection_type": "distribution_ids",
      "identifiers": [
        { "type": "gracenote_id", "value": "SP000001" },
        { "type": "gracenote_id", "value": "SP000002" }
      ]
    }
  ],
  "filters": {
    "kinds": ["event_series"],
    "genres_exclude": ["combat_sports"],
    "genre_taxonomy": "gracenote"
  },
  "brand": { "domain": "acmeoutdoor.com" }
}

これは特定のスポーツプログラムを Gracenote ID（スポーツには SP プレフィックス）で除外し、すべての格闘技イベントシリーズを構造的に除外します。event_series 種類フィルターは、リストがスポーツについてのドキュメンタリーシリーズではなくライブイベントプログラミングをターゲットすることを保証します。

Security considerations

コレクションリストは配信決定をゲートするため、auth_token と webhook コールバックは明示的なライフサイクルルールを必要とします。Security の一般的な制御が適用されます。コレクションリスト固有のルール: auth_token のスコープ、失効、ログ衛生。 各トークンは正確に 1 つの list_id を認可します。トークンをリスト間で再利用しないでください。ガバナンスエージェントはリストを受け取るセラーごとに明確なトークンを発行しなければなりません（MUST） — 共有トークンは関係ごとに失効できず、単一の侵害への唯一の応答をリスト全体のローテーションにします。トークンはログ、キャッシュキー、メトリックラベルに書き込まれてはならず（MUST NOT）、get_collection_list からのエラーレスポンスは提示されたトークンをエコーしてはなりません（MUST NOT）。 delete_collection_list とセラーごとの失効は異なります:

通常の削除または関係終了: トークンは後続の get_collection_list 呼び出しを即座に失敗させなければなりません（MUST）が、キャッシュされた解決を持つセラーは cache_valid_until までキャッシュから提供し続けてもよい（MAY）。自然な関係終了は侵害ではありません。
侵害駆動の失効: ガバナンスエージェントはキャッシュ無効化をシグナルしなければなりません（MUST）。セラーがまだ完了するアクセスを持つ次のポーリングで削減された cache_valid_until（now 以下）を返すか、キャッシュされたコピーが破棄されるよう change_summary がリストバージョンが無効化されたことを伝える collection_list_changed webhook を発行します。予定された TTL まで侵害されたコンテンツをセラーキャッシュに残すことは許容されません。

Webhook URL 検証。 update_collection_list の webhook_url は、他の任意のバイヤー提供コールバック URL と SSRF 等価です。正準の Webhook URL validation (SSRF) ルールを適用してください — HTTPS のみ、検証された IP 範囲（::ffff:0:0/96 を含む IPv4 と IPv6）、接続ピン留め（DNS 再解決だけでなく）、リダイレクトフォローなし、サイズとタイムアウト上限。 Webhook 署名アルゴリズム。 webhook 署名は標準 webhook 署名ルールに従わなければなりません（MUST）。デフォルトで、RFC 9421 webhook コールバックプロファイルが適用されます: ガバナンスエージェントは、自身の brand.json の agents[] エントリーの jwks_uri で公開された adcp_use: "request-signing" 鍵で署名します。非推奨の webhook-signing 鍵は互換性ウィンドウ中受理されたままです。サブスクライブするセラーは、tag="adcp/webhook-signing/v1" でカバードコンポーネント @method、@target-uri、@authority、content-type、content-digest を検証します。非推奨の HMAC-SHA256 フォールバックは、サブスクライブするセラーが webhook 登録で authentication.credentials を投入するときのみ適用されます。そのパスは Legacy HMAC-SHA256 fallback ルールに従い、そのパスの任意のボディ signature フィールドは便宜コピーです — 受信者はヘッダーに対して検証しなければならず（MUST）、ボディ値を信頼してはなりません（MUST NOT）。 Distribution-ID 入力。 ガバナンスエージェントは永続化前に識別子形式を検証すべきで（SHOULD）（IMDb: ^tt\d+$、EIDR: 10.5240/...、Gracenote: ベンダープレフィックス）、リスト肥大化 DoS を防ぐためリスト変更にアカウントごとのレート制限を強制すべきです（SHOULD）。未解決の識別子を黙って落とすのではなく coverage_gaps に表示します。

セラーとコレクションリストを共有する

パターンはプロパティリストの共有に一致します:

ガバナンスエージェントにコレクションリストを作成
作成レスポンスから auth_token を保存
ターゲティングオーバーレイで collection_list または collection_list_exclude を渡す
セラーが auth トークンを使って解決されたリストをフェッチしキャッシュ
リストが変わると webhook がセラーに通知

はじめに

AdCP で構築する

プロトコル

FAQ

トラストとセキュリティ

リファレンス

AAO

認定

コレクションリスト管理

コレクションリスト管理

アーキテクチャ

タスク概要

ベースコレクションソース

distribution_ids

publisher_collections

publisher_genres

フィルター

create_collection_list

get_collection_list

update_collection_list

list_collection_lists

delete_collection_list

Webhook

ライブスポーツ

Security considerations

セラーとコレクションリストを共有する

​コレクションリスト管理

​アーキテクチャ

​タスク概要

​ベースコレクションソース

​distribution_ids

​publisher_collections

​publisher_genres

​フィルター

​create_collection_list

​get_collection_list

​update_collection_list

​list_collection_lists

​delete_collection_list

​Webhook

​ライブスポーツ

​Security considerations

​セラーとコレクションリストを共有する

コレクションリスト管理

アーキテクチャ

タスク概要

ベースコレクションソース

distribution_ids

publisher_collections

publisher_genres

フィルター

create_collection_list

get_collection_list

update_collection_list

list_collection_lists

delete_collection_list

Webhook

ライブスポーツ

Security considerations

セラーとコレクションリストを共有する