> ## 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. # コレクションリスト管理 > AdCP のコレクションリストタスクは、明示的なプログラム参照を動的なジャンルとコンテンツレーティングフィルターと組み合わせて、コンテンツプログラムの包含・除外リストを作成、更新、取得、リスト、削除する。 # コレクションリスト管理 コレクションリストは、「これらのコレクション、これらの基準でフィルターされた」を表現する管理された、キャッシュ可能なアーティファクトです。[プロパティリスト](/docs/governance/property/tasks/property_lists) と並行しますが、技術的表面（ドメイン、アプリ）ではなくコンテンツプログラム（番組、シリーズ、ポッドキャスト）で動作します。 ## アーキテクチャ ``` 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 プラットフォームが運ぶかにかかわらずプログラムを識別します。 ```json theme={null} { "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 で選択します。パブリッシャーの内部識別子が既知のときに使います。 ```json theme={null} { "selection_type": "publisher_collections", "publisher_domain": "titanstreaming.com", "collection_ids": ["danger_zone", "wild_nights"] } ``` ### publisher\_genres ジャンル基準に一致するパブリッシャーのすべてのコレクションを選択します。特定のパブリッシャーからコンテンツカテゴリー全体を除外するときに使います。 ```json theme={null} { "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 として *宣言された* すべてのコレクションを除外します。個別のエピソードを評価しません — それは [コンテンツ標準](/docs/governance/content-standards/index) です。 **ジャンル分類** はバイヤーとセラー間のジャンルマッチングを正規化します。サポートされる分類: `iab_content_3.0`、`iab_content_2.2`、`gracenote`、`eidr`、`apple_genres`、`google_genres`、`roku`、`amazon_genres`、`custom`。`custom` 値はパブリッシャー定義の分類のエスケープハッチです — バイヤーとセラーが帯域外で語彙を交渉します。 ## create\_collection\_list ガバナンスエージェントに新しいコレクションリストを作成します。 **Request:** ```json theme={null} { "$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:** ```json theme={null} { "$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:** ```json theme={null} { "$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:** ```json theme={null} { "$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` はパッチではなく完全な置き換えです。 ```json theme={null} { "$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 アカウントのコレクションリストをリストします。解決されたコレクションではなくメタデータのみを返します。 ```json theme={null} { "$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 更新の受信を停止します。 ```json theme={null} { "$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 通知を送ります: ```json theme={null} { "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` 種類を通じてそれを処理します: ```json theme={null} { "$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](/docs/building/by-layer/L1/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)](/docs/building/by-layer/L1/security#webhook-url-validation-ssrf) ルールを適用してください — HTTPS のみ、検証された IP 範囲（`::ffff:0:0/96` を含む IPv4 と IPv6）、接続ピン留め（DNS 再解決だけでなく）、リダイレクトフォローなし、サイズとタイムアウト上限。 **Webhook 署名アルゴリズム。** webhook 署名は [標準 webhook 署名ルール](/docs/building/by-layer/L1/security#webhook-security) に従わなければなりません（MUST）。デフォルトで、RFC 9421 [webhook コールバックプロファイル](/docs/building/by-layer/L1/security#webhook-callbacks) が適用されます: ガバナンスエージェントは、自身の 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](/docs/building/by-layer/L1/security#legacy-hmac-sha256-fallback-deprecated-removed-in-40) ルールに従い、そのパスの任意のボディ `signature` フィールドは便宜コピーです — 受信者はヘッダーに対して検証しなければならず（MUST）、ボディ値を信頼してはなりません（MUST NOT）。 **Distribution-ID 入力。** ガバナンスエージェントは永続化前に識別子形式を検証すべきで（SHOULD）（IMDb: `^tt\d+$`、EIDR: `10.5240/...`、Gracenote: ベンダープレフィックス）、リスト肥大化 DoS を防ぐためリスト変更にアカウントごとのレート制限を強制すべきです（SHOULD）。未解決の識別子を黙って落とすのではなく `coverage_gaps` に表示します。 ## セラーとコレクションリストを共有する パターンは [プロパティリストの共有](/docs/governance/property/index#sharing-property-lists-with-sellers) に一致します: 1. ガバナンスエージェントにコレクションリストを作成 2. 作成レスポンスから `auth_token` を保存 3. ターゲティングオーバーレイで `collection_list` または `collection_list_exclude` を渡す 4. セラーが auth トークンを使って解決されたリストをフェッチしキャッシュ 5. リストが変わると webhook がセラーに通知