> ## Documentation Index > Fetch the complete documentation index at: https://docs.adrop.io/llms.txt > Use this file to discover all available pages before exploring further. # コンテキストターゲティングAPI > APIキーを使って、サーバーからコンテキストターゲティング、ターゲティングオプション、コンテキストIDを管理する方法をご案内します。 コンテキストターゲティングAPIを使うと、コンテキストターゲティングをサーバーから管理できます。CMSのセクション、掲示板、タグをターゲティングオプションとコンテキストIDに対応付けておけば、コンソールで手作業で編集しなくても、コンテンツの変化に合わせて自動で更新できます。 APIは、コンソールのコンテキストターゲティングと同じデータを扱います。APIで作成したターゲティングはコンソールに表示され、コンソールで作成したターゲティングもAPIで取得できます。 *** ## 事前準備 * `context-targeting:read`と`context-targeting:write`の両方のスコープを持つAPIキーが必要です。プロジェクトのオーナーがコンソールの **\[設定]** > **\[連携]** でキーを作成し、両方のスコープを選択します。キーの作成方法は[連携 & APIキー](/ja/integrations/overview)を参照してください。 * 既存のキーのスコープは変更できません。今のキーに両方のスコープがない場合は新しいキーを作成し、不要になった古いキーは廃棄してください。 書き込みが中心の場合でも、両方のスコープを付与してください。各エンドポイントが確認するスコープは1つだけで、`context-targeting:write`には`context-targeting:read`が含まれません。書き込みスコープしかないキーはすべての`GET`リクエストで`403`を受け取るため、IDの確認、現在のコンテキストIDの取得、変更が読み込まれたかの確認ができません。 APIはサーバーからのみ呼び出してください。APIキーをアプリやウェブページに含めないでください。 *** ## 基本情報 | 項目 | 値 | | - | - | | Base URL | `https://lake.adrop.io` | | 認証 | `x-api-key`ヘッダーにAPIキーを指定します。プロジェクトはキーで決まるため、パスにプロジェクトIDは含まれません。 | | Content-Type | `application/json` | | リクエストボディの最大サイズ | 8 MB。これより大きいリクエストには`413`が返されます。 | | ID形式 | サーバーが発行する26文字のULID（例：`01JAB3XK5Q8V7M2N4P6R9T0W1Y`）。有効なULIDでないIDには`400`が返されます。 | | 書き込みの処理 | APIは、プロジェクトごとに書き込みを1件ずつ処理します。別の書き込みの処理中に送った書き込みは`409 CONTEXT_TARGETING_WRITE_IN_PROGRESS`で失敗することがあるため、書き込みは並列ではなく1件ずつ順番に送ってください。読み取りには影響しません。[同時書き込み](/ja/integrations/context-targeting/errors#同時書き込み)を参照してください。 | リクエストに関する上限の一覧は、[上限](/ja/integrations/context-targeting/errors#上限)を参照してください。 *** ## 用語 APIのパスやフィールドには、コンソールと異なる名前が使われているものがあります。本ドキュメントではコンソールの名称を使います。 | API | コンソールでの名称 | 説明 | | - | - | - | | `targeting` | ターゲティング | 「News Sections」などのコンテキストターゲティング。APIで扱えるのはコンテキストターゲティングのみです。 | | `category` | ターゲティングオプション（オプション） | 「Sports」など、ターゲティングに含まれるオプション。 | | `contexts` | コンテキストID | `sport`など、オプションに登録されたID。アプリやウェブサイトは、これを広告リクエストの`contextId`として送信します。 | | `type: "collection"` | オプショングループ | 下位オプションをまとめるオプション。自身のコンテキストIDと下位オプションのコンテキストIDの両方に一致します。通常のオプションは`type: "atomic"`です。 | | `children`、`parent` | 下位オプション | オプショングループに含まれるオプション。オプショングループの`children`には下位オプションが並び、下位オプションの`parent`はそのオプショングループです。 | | `exposeChildren` | 下位オプションを広告主に表示 | 広告主がオプショングループの下位オプションを個別に選択できるかどうか。広告配信には影響しません。 | *** ## エンドポイント パスはBase URLからの相対パスです。各エンドポイントには、表に記載したスコープが必要です。 | メソッド | パス | スコープ | 説明 | | - | - | - | - | | `GET` | `/context-targeting` | `context-targeting:read` | [ターゲティング一覧の取得](/ja/integrations/context-targeting/targetings#ターゲティング一覧の取得) | | `GET` | `/context-targeting/{targetingId}` | `context-targeting:read` | [ターゲティングの取得](/ja/integrations/context-targeting/targetings#ターゲティングの取得)（オプションを含む） | | `POST` | `/context-targeting` | `context-targeting:write` | [ターゲティングの作成](/ja/integrations/context-targeting/targetings#ターゲティングの作成)（オプションも同時に作成可能） | | `PATCH` | `/context-targeting/{targetingId}` | `context-targeting:write` | [ターゲティング名の変更](/ja/integrations/context-targeting/targetings#ターゲティング名の変更) | | `DELETE` | `/context-targeting/{targetingId}` | `context-targeting:write` | [ターゲティングの削除](/ja/integrations/context-targeting/targetings#ターゲティングの削除)（すべてのオプションも削除） | | `POST` | `/context-targeting/bulk/create` | `context-targeting:write` | [ターゲティングの一括作成](/ja/integrations/context-targeting/targetings#ターゲティングの一括作成)（1リクエストあたり最大100件） | | `POST` | `/context-targeting/bulk/update` | `context-targeting:write` | [ターゲティング名の一括変更](/ja/integrations/context-targeting/targetings#ターゲティング名の一括変更)（1リクエストあたり最大100件） | | `POST` | `/context-targeting/bulk/delete` | `context-targeting:write` | [ターゲティングの一括削除](/ja/integrations/context-targeting/targetings#ターゲティングの一括削除)（1リクエストあたり最大100件） | | `GET` | `/context-targeting/{targetingId}/categories` | `context-targeting:read` | ターゲティングの[オプション一覧の取得](/ja/integrations/context-targeting/options#オプション一覧の取得)（ページ単位） | | `GET` | `/context-targeting/category/{categoryId}` | `context-targeting:read` | [オプションの取得](/ja/integrations/context-targeting/options#オプションの取得)（コンテキストIDを含む） | | `POST` | `/context-targeting/{targetingId}/category` | `context-targeting:write` | ターゲティングへの[オプションの追加](/ja/integrations/context-targeting/options#オプションの追加) | | `PATCH` | `/context-targeting/category/{categoryId}` | `context-targeting:write` | [オプションの更新](/ja/integrations/context-targeting/options#オプションの更新)（名前の変更、コンテキストIDの変更、移動、`exposeChildren`の設定） | | `DELETE` | `/context-targeting/category/{categoryId}` | `context-targeting:write` | [オプションの削除](/ja/integrations/context-targeting/options#オプションの削除) | | `POST` | `/context-targeting/category/bulk/create` | `context-targeting:write` | [オプションの一括追加](/ja/integrations/context-targeting/options#オプションの一括追加)（1リクエストあたり最大5,000件） | | `POST` | `/context-targeting/category/bulk/update` | `context-targeting:write` | [オプションの一括更新](/ja/integrations/context-targeting/options#オプションの一括更新)（1リクエストあたり最大5,000件） | | `POST` | `/context-targeting/category/bulk/delete` | `context-targeting:write` | [オプションの一括削除](/ja/integrations/context-targeting/options#オプションの一括削除)（1リクエストあたり最大5,000件） | 一括操作のエンドポイントは、項目ごとに結果を返します。[一括操作のレスポンス](/ja/integrations/context-targeting/errors#一括操作のレスポンス)を参照してください。 *** ## クイックスタート この例では、「News Sections」ターゲティングを作成し、1つのオプションのコンテキストIDを変更して、その変更が読み込まれたかを確認します。 ターゲティングとそのオプションを1回のリクエストで作成します。 ```bash theme={null} curl -X POST https://lake.adrop.io/context-targeting \ -H "x-api-key: YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "name": "News Sections", "categories": [ { "name": "Sports", "contexts": ["sport", "baseball", "soccer"] }, { "name": "Tech", "contexts": ["tech", "ai", "mobile"] } ] }' ``` レスポンスは`201`で、作成されたターゲティングが返されます。ターゲティングと各オプションの`_id`を保存してください。後でターゲティングを変更するときに必要です。 ```json theme={null} { "_id": "01JAB3XK5Q8V7M2N4P6R9T0W1Y", "name": "News Sections", "categories": [ { "_id": "01JAB3XK5RA1B2C3D4E5F6G7H8", "name": "Sports", "type": "atomic", "contextCount": 3, "createdAt": "2026-10-13T01:23:45.000Z", "updatedAt": "2026-10-13T01:23:45.000Z" }, { "_id": "01JAB3XK5RA1B2C3D4E5F6G7H9", "name": "Tech", "type": "atomic", "contextCount": 3, "createdAt": "2026-10-13T01:23:45.000Z", "updatedAt": "2026-10-13T01:23:45.000Z" } ], "categoryCount": 2, "createdAt": "2026-10-13T01:23:45.000Z", "updatedAt": "2026-10-13T01:23:45.000Z" } ``` 作成は冪等ではありません。作成リクエストがタイムアウトした場合は、再送する前に[再試行と重複リクエスト](/ja/integrations/context-targeting/errors#再試行と重複リクエスト)を参照してください。 セクションが変わったら、オプションのコンテキストIDを更新します。`add`と`remove`は、指定したIDだけを変更します。 ```bash theme={null} curl -X PATCH https://lake.adrop.io/context-targeting/category/01JAB3XK5RA1B2C3D4E5F6G7H8 \ -H "x-api-key: YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "contexts": { "add": ["basketball", "golf"], "remove": ["soccer"] } }' ``` レスポンスは`200`で、更新後のオプションが返されます。 ```json theme={null} { "_id": "01JAB3XK5RA1B2C3D4E5F6G7H8", "name": "Sports", "type": "atomic", "contextCount": 4, "createdAt": "2026-10-13T01:23:45.000Z", "updatedAt": "2026-10-13T01:30:00.000Z" } ``` オプションのコンテキストIDをまとめて置き換える方法は、[コンテキストIDの更新方法](/ja/integrations/context-targeting/options#コンテキストidの更新方法)を参照してください。 ターゲティングを取得し、その`syncedAt`を更新が成功した時刻と比べます。 ```bash theme={null} curl "https://lake.adrop.io/context-targeting/01JAB3XK5Q8V7M2N4P6R9T0W1Y?includeCategories=false" \ -H "x-api-key: YOUR_API_KEY" \ -H "Content-Type: application/json" ``` ```json theme={null} { "_id": "01JAB3XK5Q8V7M2N4P6R9T0W1Y", "name": "News Sections", "categoryCount": 2, "syncedAt": 1791855005000, "createdAt": "2026-10-13T01:23:45.000Z", "updatedAt": "2026-10-13T01:30:06.000Z" } ``` 前のステップの更新は2026-10-13T01:30:00.000Z（`1791855000000`）に成功しています。`syncedAt`はそれより後なので変更は読み込まれており、その後数分以内に広告配信に反映されます。`syncedAt`がない場合やそれより前の場合は、少し待ってからターゲティングをもう一度取得してください。[変更が反映されるタイミング](#変更が反映されるタイミング)を参照してください。 ユーザーが閲覧しているページのコンテキストIDを、広告リクエストの`contextId`として送信します。変更が反映された後は、`contextId`に`basketball`を指定した広告リクエストが「Sports」オプションに一致します。 広告リクエストでのコンテキストIDの仕組みは、[コンテキストターゲティングの作成](/ja/targeting/context)を参照してください。 *** ## 変更が反映されるタイミング 書き込みが成功すると、変更はすぐに保存されます。その後、Adropがプロジェクトのコンテキストターゲティングを広告配信に読み込み、通常は数分以内に変更が広告配信に反映されます。 変更が読み込まれたかどうかは、ターゲティングの`syncedAt`フィールド（エポックミリ秒）で確認します。 * `syncedAt`は、そのターゲティングの直近の読み込みが始まった時刻です。`syncedAt`以前に成功した変更は読み込み済みで、その後数分以内に広告配信に反映されます。 * 新しく作成したターゲティングには`syncedAt`が含まれません。コンテキストIDの変更（`add`、`remove`、`set`）、オプションの追加、オプションの移動や切り離しを行った後も含まれません。通常は次の読み込みが完了すると、再び含まれるようになります。 * 変更したときにすでに実行中だった読み込みによって、`syncedAt`がその読み込みの開始時刻、つまり変更より前の時刻になることがあります。その読み込みには変更が含まれていない可能性がありますが、その後の読み込みには含まれます。 * 名前の変更や削除では、`syncedAt`は消えません。 そのため、`syncedAt`があるかどうかで判断しないでください。リクエストが成功した時刻を記録しておき、変更を含むターゲティングを取得します（例：[ターゲティングの取得](/ja/integrations/context-targeting/targetings#ターゲティングの取得)で`includeCategories=false`を指定）。`syncedAt`がその時刻と同じかそれより後であれば、変更は読み込まれています。`syncedAt`はAdropのサーバー時刻に基づくため、自社サーバーの時刻とずれがある可能性がある場合は、余裕を持って判断してください。 変更が反映されるまで、広告リクエストは変更前のコンテキストIDと照合されます。新しいコンテキストIDは、アプリやウェブサイトが広告リクエストで送信し始める前に追加してください。 *** ## 関連ドキュメント ターゲティングの一覧取得、作成、名前の変更、削除 オプションを追加し、コンテキストIDを最新の状態に保つ方法 オプションを下位オプションとしてオプショングループにまとめる方法 エラーコード、上限、再試行の方法 APIキーの作成と管理 コンテキストターゲティングとコンテキストIDの仕組み ターゲティングを広告商品に接続して広告主に販売する方法 This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.