> ## 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. # sync_catalogs > sync_catalogs タスク — 商品フィード、店舗所在地、垂直カタログ（ホテル、フライト、車両、不動産）をカタログ駆動型キャンペーン向けに AdCP セラーアカウントに同期します。 セラーアカウント上のカタログフィードを管理します。商品フィード、在庫データ、店舗所在地、オファリング、および業界垂直カタログ（ホテル、フライト、求人、車両、不動産、教育、目的地）を同期します。URL ベースのフィードのスケジュール再取得、インラインアイテムデータ、既存カタログのディスカバリーをサポートします。 **用語について。** `sync_catalogs` は、セラーが広告のレンダリングやターゲティングに使う、バイヤー提供のデータフィードを管理します。これは、`get_products buying_mode: "wholesale"` が公開するセラー側のホールセール商品フィードや、`get_signals discovery_mode: "wholesale"` が公開するホールセールシグナルフィードとは別物です。Webhook はそれらセラー側フィードの変更をプッシュするレイヤーです。 **レスポンス時間**: 即時〜数日（小規模カタログは `completed`、プラットフォームレビューが必要な大規模フィードは `submitted` を返す） **リクエストスキーマ**: [`/schemas/v3/media-buy/sync-catalogs-request.json`](https://adcontextprotocol.org/schemas/v3/media-buy/sync-catalogs-request.json) **レスポンススキーマ**: [`/schemas/v3/media-buy/sync-catalogs-response.json`](https://adcontextprotocol.org/schemas/v3/media-buy/sync-catalogs-response.json) ## 呼び出し関係 **バイヤー**がセラーアカウントにカタログフィードをプッシュするために、**セラー**に対して `sync_catalogs` を呼び出す。セラーはアイテムを検証し、コンテンツポリシーチェックを実行し、アイテムごとの承認ステータスを返します。 ```mermaid theme={null} sequenceDiagram participant B as Buyer participant S as Seller B->>S: sync_catalogs (product feed, stores, inventory) S->>B: Per-catalog results with item review status Note over B,S: Buyer can now reference synced catalogs in creatives ``` このタスクは[アカウント状態セットアップシーケンス](/docs/building/by-layer/L2/account-state)において、フォーマットディスカバリーとクリエイティブ提出の間に位置します： 1. `list_creative_formats` — 各フォーマットの `assets` 配列にある `catalog` アセットタイプを確認し、同期すべきフィードを把握します 2. **`sync_catalogs`** — 必要なフィードをアカウントにプッシュします 3. `sync_creatives` — `catalog_id` で同期済みカタログを参照するクリエイティブを提出します 4. `create_media_buy` — キャンペーンを開始します ## クイックスタート 商品フィードを同期します： ```json theme={null} { "account": { "account_id": "acct_acmecorp" }, "catalogs": [ { "catalog_id": "product-feed", "name": "Acme Product Catalog", "type": "product", "url": "https://feeds.acmecorp.com/products.xml", "feed_format": "google_merchant_center", "update_frequency": "daily" } ] } ``` ## リクエストパラメータ | パラメータ | 型 | 必須 | 説明 | | -------------------------- | -------------------------------------------------------------------------------- | ---- | ----------------------------------------------------------------------------------------------------------------------------------- | | `account` | [account-ref](/docs/building/by-layer/L2/accounts-and-agents#account-references) | 条件付き | アカウント参照。`{ "account_id": "..." }` または、セラーが暗黙的な解決をサポートしている場合は `{ "brand": {...}, "operator": "..." }` を渡します。エージェントが複数のアカウントを持つ場合は必須。 | | `catalogs` | Catalog\[] | No | 同期するカタログフィード（最大 50 件）。ディスカバリーモードでは省略します。 | | `catalog_ids` | string\[] | No | 同期スコープを特定のカタログ ID に限定します。アカウント上の他のカタログは影響を受けない。 | | `delete_missing` | boolean | No | true の場合、この同期に含まれないバイヤー管理カタログを削除します。セラー管理カタログには影響しません。`catalogs` の存在が必要。デフォルト: false。 | | `dry_run` | boolean | No | 変更を適用せずにプレビューします。デフォルト: false。 | | `validation_mode` | string | No | `"strict"`（デフォルト）はエラーが発生した場合に同期全体を失敗させる。`"lenient"` は有効なカタログを処理してエラーを報告します。 | | `push_notification_config` | object | No | 非同期完了通知のための Webhook 設定。 | ### Catalog オブジェクト `catalogs` 配列内の各カタログは [Catalog](/docs/creative/catalogs#the-catalog-object) オブジェクトです。主要フィールド： | フィールド | 型 | 必須 | 説明 | | ------------------- | ------------ | --- | ------------------------------------------------------------------------------------------------------------------------------------------------- | | `catalog_id` | string | Yes | バイヤーの識別子。アップサートのために既存カタログとの照合に使用します。 | | `type` | CatalogType | Yes | カタログタイプ: `product`, `offering`, `inventory`, `store`, `promotion`, `hotel`, `flight`, `job`, `vehicle`, `real_estate`, `education`, `destination` | | `url` | uri | No | 外部フィード URL。`items` と相互排他的。 | | `feed_format` | string | No | フィードフォーマット: `google_merchant_center`, `facebook_catalog`, `shopify`, `linkedin_jobs`, `custom` | | `update_frequency` | string | No | 再取得スケジュール: `realtime`, `hourly`, `daily`, `weekly` | | `items` | object\[] | No | インラインカタログデータ。`url` と相互排他的。 | | `conversion_events` | EventType\[] | No | このカタログ内のアイテムのコンバージョンを表すイベントタイプ | ## レスポンス **成功レスポンス** — カタログごとの結果： | フィールド | 型 | 説明 | | --------------------------- | --------- | ------------------------------------------------------ | | `catalogs` | object\[] | 処理された各カタログの結果 | | `catalogs[].catalog_id` | string | リクエストのカタログ ID | | `catalogs[].action` | string | `created`, `updated`, `unchanged`, `failed`, `deleted` | | `catalogs[].platform_id` | string | プラットフォームが割り当てた ID | | `catalogs[].item_count` | integer | 同期後の総アイテム数 | | `catalogs[].items_approved` | integer | プラットフォームが承認したアイテム数 | | `catalogs[].items_pending` | integer | レビュー待ちのアイテム数 | | `catalogs[].items_rejected` | integer | 却下されたアイテム数 | | `catalogs[].item_issues` | object\[] | アイテムごとの却下理由 | | `catalogs[].next_fetch_at` | datetime | 次回スケジュールされたフィード取得日時（URL ベースのカタログ） | **エラーレスポンス** — 操作が完全に失敗した場合： | フィールド | 型 | 説明 | | -------- | -------- | ------------------------ | | `errors` | Error\[] | 操作レベルのエラー（認証失敗、サービス利用不可） | レスポンスは判別ユニオンを使用する — `catalogs` または `errors` のいずれかが返され、両方が同時に返されることはない。 ### アイテムレベルレビューのレスポンス例 ```json theme={null} { "catalogs": [ { "catalog_id": "product-feed", "action": "created", "platform_id": "plat_cat_001", "item_count": 1250, "items_approved": 1180, "items_pending": 45, "items_rejected": 25, "item_issues": [ { "item_id": "SKU-789", "status": "rejected", "reasons": ["Missing required field: image_url"] } ], "next_fetch_at": "2025-03-01T06:00:00Z" } ] } ``` ## アイテムレビューのライフサイクル カタログアイテムはシンプルなレビューサイクルをたどります: アイテムは同期時に `pending` に入り、プラットフォームが非同期にレビューします。アイテムは `approved`、（理由付きの）`rejected`、または `warning` 付きの `approved`（配信されるが修正可能な問題あり）のいずれかになります。 却下は最終的なものではありません——ソースカタログで問題を修正して再同期します。アイテムを再同期すると、再レビューのために `pending` にリセットされます。レスポンスの `item_issues` 配列がアイテムごとの却下理由を示します。 ## ディスカバリーモード `catalogs` を省略することで、アカウント上のすべてのカタログを変更なしで一覧表示できます： ```json theme={null} { "account": { "account_id": "acct_acmecorp" } } ``` セラーが他のソースからブランドデータをすでに持っている場合があるため、これは重要である — 小売業者はコマースプラットフォームからブランドの商品カタログをすでに持っているかもしれない。ディスカバリーにより、バイヤーはすべてを再アップロードするのではなく、既存の状態を活用できます。 ## 非同期承認ワークフロー 大規模なフィードやコンテンツポリシーレビューが必要なフィードは、`task_id` とともに `status: "submitted"` を返します。セラーは非同期でアイテムをレビューし、完了したら Webhook でバイヤーに通知します。 非同期レスポンスの状態： * **`working`** — プラットフォームがフィードを処理中（URL の取得、アイテムの検証） * **`input-required`** — プラットフォームがバイヤーのアクションを必要としている（バリデーションエラーの修正、不足フィールドの提供） * **`submitted`** — レビュー完了、最終的なカタログごとの結果が利用可能 状態遷移の Webhook 通知を受け取るには、リクエストに `push_notification_config` を設定します。 ## 一般的なシナリオ ### リテールメディア（product + inventory + store） ```json theme={null} { "account": { "account_id": "acct_acmecorp" }, "catalogs": [ { "catalog_id": "product-feed", "type": "product", "url": "https://feeds.acmecorp.com/products.xml", "feed_format": "google_merchant_center", "update_frequency": "daily" }, { "catalog_id": "inventory-feed", "type": "inventory", "url": "https://feeds.acmecorp.com/inventory.json", "feed_format": "custom", "update_frequency": "hourly" }, { "catalog_id": "store-locations", "type": "store", "url": "https://feeds.acmecorp.com/stores.json", "feed_format": "custom", "update_frequency": "weekly" } ] } ``` ### 採用（インライン求人オファリング） ```json theme={null} { "account": { "account_id": "acct_restaurants" }, "catalogs": [ { "catalog_id": "chef-vacancies", "type": "offering", "items": [ { "offering_id": "chef-amsterdam-42", "name": "Head Chef - Amsterdam", "landing_url": "https://jobs.acme-restaurants.com/chef-amsterdam-42", "geo_targets": { "countries": ["NL"], "regions": ["NL-NH"] } } ] } ] } ``` ### ドライランバリデーション ```json theme={null} { "account": { "account_id": "acct_acmecorp" }, "dry_run": true, "catalogs": [ { "catalog_id": "product-feed", "type": "product", "url": "https://feeds.acmecorp.com/products.xml", "feed_format": "google_merchant_center" } ] } ``` ## エラーハンドリング | エラー | 説明 | 解決策 | | ------------------------ | ---------------------------------------------------------------------------------------- | ---------------------------------------------------------------- | | `REFERENCE_NOT_FOUND` | 参照された `catalog_id` が存在しないかアクセスできない（`catalog_ids` フィルター使用時。`error.field` = `catalog_ids`） | 以前の同期またはディスカバリー呼び出しからカタログ ID を確認する | | `FEED_FETCH_FAILED` | プラットフォームがフィード URL を取得できなかった | URL のアクセス可能性、認証、フィードフォーマットを確認する | | `INVALID_FEED_FORMAT` | フィードが宣言された `feed_format` と一致しない | フィードの内容がフォーマットと一致しているか確認する（google\_merchant\_center の場合は XML など） | | `ITEM_VALIDATION_FAILED` | アイテムがスキーマバリデーションに失敗した | アイテムごとの却下理由を `item_issues` で確認する | | `CATALOG_LIMIT_EXCEEDED` | アカウントが最大カタログ数に達した | 未使用のカタログを削除するか、セラーに連絡する | ## ベストプラクティス 1. **フォーマット要件を最初に確認する** — 同期前に `list_creative_formats` を呼び出し、各フォーマットの `assets` 配列にある `catalog` アセットタイプを確認します。これにより、同期すべきカタログタイプと各アイテムに必要なフィールドがわかる。 2. **ディスカバリーモードを使用する** — 同期前に `catalogs` なしで呼び出し、セラーがすでに持っているものを確認します。セラーが他のソースからブランドデータを持っている可能性があります。 3. **`update_frequency` を設定する** — URL ベースのフィードでは、プラットフォームが再取得頻度を把握できるよう、常に `update_frequency` を設定します。フィードが古くなると、在庫切れ商品の広告が表示されることになります。 4. **`conversion_events` を宣言する** — どのイベントタイプがカタログアイテムのコンバージョンを表すかを宣言して、カタログをコンバージョントラッキングシステムに接続します。 5. **大規模フィードには `dry_run` を使用する** — 特に数千のアイテムを含む初回同期では、コミット前にバリデーションを行います。 6. **アイテムレベルの失敗を処理する** — `lenient` モードでは、一部のアイテムが失敗しても有効なアイテムは処理されます。却下されたアイテムを修正するには、レスポンスの `item_issues` を確認します。 ## 次のステップ * [Catalogs](/docs/creative/catalogs) — カタログタイプ、ソーシング、フォーマット要件に関する完全なドキュメント * [アカウント状態](/docs/building/by-layer/L2/account-state) — アカウントセットアップシーケンスにおけるカタログの位置づけ * [sync\_creatives](/docs/creative/task-reference/sync_creatives) — 同期済みカタログを参照するクリエイティブの提出 * [list\_creative\_formats](/docs/creative/task-reference/list_creative_formats) — フォーマットのカタログ要件のディスカバリー