> For the complete documentation index, see [llms.txt](https://help.citrusad.com/retail-media-interface/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://help.citrusad.com/retail-media-interface/partner/ja/bulk-operation-api/bulk-operation-overview.md). # 一括操作の概要 ## 一括キャンペーン 一括操作APIは、AdOps、マネージドサービス、サプライヤーなどのユーザーが、単一のAPI呼び出しで**キャンペーン**、**ウォレット**、**チーム**に対して大規模な更新および作成操作を実行できるように設計されています。この非同期APIアプローチにより、ワークフローが合理化され、手作業が削減され、運用の効率が向上します。 これらのAPIは、オンボーディング、季節ごとの立ち上げ、主要なキャンペーン調整など、個別のAPI呼び出しを行うと時間がかかりエラーが発生しやすくなる高ボリュームのシナリオで特に価値を発揮します。 ### 主なメリット * 効率性: 1つのリクエストで複数の操作を許可することにより、API呼び出しの回数を減らし、不必要な手動ステップを排除します。 * パフォーマンス: 一括APIはHTTPラウンドトリップのオーバーヘッドを最小限に抑えます。多数の個別のリクエスト（例: 100回の個別の呼び出し）を送信する代わりに、1回の一括リクエストでネットワーク負荷を軽減し、レート制限に達する可能性を低くします。 * 冪等性: 一括リクエスト内の各操作の冪等性を保証し、再試行時（UIアクションによってトリガーされるものなど）の意図しない副作用を防ぎます。 * きめ細やかなセキュリティと認可モデル: 一括ペイロード内の各操作とエンティティタイプに対して適切なアクセス制御を適用し、すべての操作の安全な処理を保証します。 * 監査とログ記録: 一括リクエスト内のすべての操作に対して適切なログ記録と監査証跡を維持し、トレーサビリティを確保します。 * プレビュー機能: 一部の実装では変更を適用する前にプレビューすることをサポートしており、エラーを早期に発見するのに役立ちます。 * トランザクションの整合性: 一括APIを使用すると、クライアントはグループ化された一連のアクションを単一のAPI呼び出しにバンドルできます。これにより、以下を保証できます: * 一括リクエスト内の各エンティティが個別に検証されます。 * どのエンティティがなぜ失敗したかを特定するために、詳細なエラーメッセージが返されます。 * 1つのエンティティが失敗しても、操作全体はブロックされません。 ### 一括キャンペーンAPIの使用方法 #### 1. 一括リクエストの送信 一度に複数のキャンペーンを作成、編集、または承認するためのリクエストを送信します。 * 作成の場合: `/v3/campaigns/bulk/create` * 編集の場合: `/v3/campaigns/bulk/update` * 承認の場合: `/v3/campaigns/bulk/approve` リクエストを送信すると、システムから一括IDと `submitted`のようなステータスが返されます。実際の処理はバックグラウンドで行われます。 **例（キャンペーンの一括更新）:** ```http PATCH /v3/campaigns/bulk/update { "campaigns": [ { "campaign": { "id": "campaign_123", "name": "Updated Summer Sale Campaign", "startTime": "2025-08-01T00:00:00Z", "endTime": "2025-08-31T23:59:59Z", "campaignState": "CAMPAIGN_STATE_ACTIVE", "strategy": { "auction": { "maxBid": "6.5" } } }, "mask": "name,startTime,endTime,campaignState,strategy.auction.maxBid", "campaignType": "CAMPAIGN_TYPE_BANNER" }, { "campaign": { "id": "campaign_456", "name": "Holiday Promotion", "campaignState": "CAMPAIGN_STATE_PAUSED", "strategy": { "auction": { "maxBid": "5.0" } } }, "mask": "name,campaignState,strategy.auction.maxBid", "campaignType": "CAMPAIGN_TYPE_BANNER" } ] } ``` レスポンス: ```json { "bulkId": "c40f4f98-9b6b-11ee-b9d1-0242ac120002", "status": "BULK_OPERATION_SUBMITTED", "message": "Bulk campaign update request received and is being processed." } ``` #### 2. ステータスの確認 一括IDを使用して、以下で進捗状況を確認します: `/v3/campaigns/bulk/status/{bulkId}` 以下が表示されます: * どのキャンペーンが成功または失敗したか。各詳細が含まれます。 * Error messages (if any). **Example:** ```http GET /v3/campaigns/bulk/status/c40f4f98-9b6b-11ee-b9d1-0242ac120002 ``` {% hint style="info" %} 注記: * APIは非同期です。ジョブを送信し、結果をポーリングします。 * 一括リクエスト内の各エンティティは個別に検証され、エラーは項目ごとに報告されます。 * 一括APIはキャンペーン、ウォレット、チームで利用可能であり、各リソースで同様のパターンが使用されます。 {% endhint %} ### 一括操作アクセス権限マトリクス | 操作 | メソッド | 作成可能な権限 | ステータスを閲覧可能な権限 | | ------------------------------------------------------------------------------------------------------------------------ | ----- | -------------------------------------------- | ------------------------------------------- | | キャンペーン | | | | | [キャンペーンを一括作成する](/retail-media-interface/partner/ja/bulk-operation-api/bulkcampaignoperations/bulkcreatecampaign.md) | POST | Admin、Primary Retailer、Supplier、General User | Admin、Primary Retailer、Creator（Supplierを含む） | | [キャンペーンを一括更新する](/retail-media-interface/partner/ja/bulk-operation-api/bulkcampaignoperations/bulkupdatecampaign-1.md) | PATCH | Admin、Primary Retailer、Supplier、General User | Admin、Primary Retailer、Creator（Supplierを含む） | | [キャンペーンの承認状態を更新する](/retail-media-interface/partner/ja/bulk-operation-api/bulkcampaignoperations/bulkcampaignapproval.md) | POST | Admin、Primary Retailer | Admin、Primary Retailer | | [一括操作ステータスを取得する](/retail-media-interface/partner/ja/bulk-operation-api/bulkcampaignoperations/bulkcampaignstatus-1.md) | GET | — | Admin、Primary Retailer、Creator（Supplierを含む） | | ウォレット | | | | | [ウォレットを一括作成する](/retail-media-interface/partner/ja/bulk-operation-api/bulkwalletoperations/bulkcreatewallet.md) | POST | Admin、Primary Retailer、Supplier、General User | Admin、Primary Retailer、Creator（Supplierを含む） | | [ウォレットを一括更新する](/retail-media-interface/partner/ja/bulk-operation-api/bulkwalletoperations/bulkupdatewallet.md) | PATCH | Admin、Primary Retailer、Supplier、General User | Admin、Primary Retailer、Creator（Supplierを含む） | | [一括ウォレット操作ステータスを取得する](/retail-media-interface/partner/ja/bulk-operation-api/bulkwalletoperations/bulkwalletstatus.md) | GET | — | Admin、Primary Retailer、Creator（Supplierを含む） | | チーム | | | | | [チームを一括作成する](/retail-media-interface/partner/ja/bulk-operation-api/bulkwalletoperations-1/bulkcreateteam.md) | POST | Admin、Primary Retailer、Supplier、General User | Admin、Primary Retailer、Creator（Supplierを含む） | | [チームを一括更新する](/retail-media-interface/partner/ja/bulk-operation-api/bulkwalletoperations-1/bulkupdateteam.md) | PATCH | Admin、Primary Retailer、Supplier、General User | Admin、Primary Retailer、Creator（Supplierを含む） | | [一括チーム操作ステータスを取得する](/retail-media-interface/partner/ja/bulk-operation-api/bulkwalletoperations-1/bulkteamstatus.md) | GET | — | Admin、Primary Retailer、Creator（Supplierを含む） | {% hint style="info" %} チームの一括作成および更新: サプライヤーがレコードを一括更新しようとすると、APIは1リクエストあたり最大50レコードまで許可します。リクエストに50を超えるレコードが含まれている場合、APIは制限を超えたことを示すエラーメッセージを返します。 {% endhint %} --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://help.citrusad.com/retail-media-interface/partner/ja/bulk-operation-api/bulk-operation-overview.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.