> ## 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でターゲティングオプションの一覧取得、追加、更新、削除を行い、コンテキストIDを最新の状態に保つ方法をご案内します。

ターゲティングオプション（オプション）は、コンテキストターゲティングの中でコンテキストIDをまとめて名前を付けたものです（例：`sport`、`baseball`、`soccer`を含む「Sports」）。APIのパスとフィールドでは、オプションを`category`、そのコンテキストIDを`contexts`と表します。

オプションのタイプは次の2つです。

* `atomic`：コンテキストIDのリストです。
* `collection`：自身のコンテキストIDと下位オプションのコンテキストIDに一致するオプションです。[オプショングループ](/ja/integrations/context-targeting/option-groups#オプショングループとは)を参照してください。

このページのパスは`https://lake.adrop.io`からの相対パスです。認証とリクエスト形式については、[基本情報](/ja/integrations/context-targeting/overview#基本情報)を参照してください。

***

## オプションオブジェクト

このページのエンドポイントは、オプションを次の形で返します。このオブジェクトにはコンテキストIDそのものではなく、コンテキストIDの数が入ります。コンテキストIDを読み取るには、[オプションの取得](#オプションの取得)を使用します。

| フィールド | タイプ | 説明 |
| - | - | - |
| `_id` | string | オプションID。サーバーが発行する26文字のULID |
| `name` | string | オプション名 |
| `type` | string | `atomic`または`collection` |
| `contextCount` | number | オプションが一致するコンテキストIDの数。オプショングループの場合は、自身のコンテキストIDと下位オプションのコンテキストIDを合わせ、重複を除いた数 |
| `ownContextCount` | number | オプショングループのみ。オプショングループ自身のコンテキストIDの数 |
| `exposeChildren` | boolean | オプショングループのみ。下位オプションを広告主に表示するかどうか。一度も設定していない場合は`false` |
| `children` | string\[] | オプショングループのみ。オプショングループ内の順序で並べた、先頭50個の下位オプションのID |
| `childCount` | number | オプショングループのみ。下位オプションの総数。`children`の要素数より大きい場合は、[オプション一覧の取得](#オプション一覧の取得)の`parent`パラメータで残りを取得します |
| `parent` | string | 下位オプションのみ。オプションが属するオプショングループのID |
| `createdAt` | string | オプションの作成日時（ISO 8601、UTC） |
| `updatedAt` | string | オプションの最終更新日時（ISO 8601、UTC） |

オプションに該当しないフィールドは省略されます。

<CodeGroup>
  ```json 通常のオプション theme={null}
  {
    "_id": "01JAB3XK5RA1B2C3D4E5F6G7H8",
    "name": "Sports",
    "type": "atomic",
    "contextCount": 3,
    "createdAt": "2026-10-13T01:23:45.000Z",
    "updatedAt": "2026-10-13T01:23:45.000Z"
  }
  ```

  ```json オプショングループ theme={null}
  {
    "_id": "01JAB3XK5SB1C2D3E4F5G6H7J8",
    "name": "Sports",
    "type": "collection",
    "contextCount": 3,
    "ownContextCount": 1,
    "exposeChildren": false,
    "children": ["01JAB3XK5TC1D2E3F4G5H6J7K8", "01JAB3XK5TC1D2E3F4G5H6J7K9"],
    "childCount": 2,
    "createdAt": "2026-10-13T01:23:45.000Z",
    "updatedAt": "2026-10-13T01:23:45.000Z"
  }
  ```

  ```json 下位オプション theme={null}
  {
    "_id": "01JAB3XK5TC1D2E3F4G5H6J7K8",
    "name": "Baseball",
    "type": "atomic",
    "contextCount": 1,
    "parent": "01JAB3XK5SB1C2D3E4F5G6H7J8",
    "createdAt": "2026-10-13T01:23:45.000Z",
    "updatedAt": "2026-10-13T01:23:45.000Z"
  }
  ```
</CodeGroup>

***

## オプション一覧の取得

ターゲティングのオプションを、`_id`の昇順（おおむね作成順）でページごとに返します。オプショングループと下位オプションも含まれます。各項目は[オプションオブジェクト](#オプションオブジェクト)です。

### リクエスト

```http theme={null}
GET /context-targeting/{targetingId}/categories
```

`context-targeting:read`スコープが必要です。

### パスパラメータ

| パラメータ | タイプ | 必須 | 説明 |
| - | - | :-: | - |
| `targetingId` | string | O | ターゲティングID |

### クエリパラメータ

| パラメータ | タイプ | 必須 | 説明 |
| - | - | :-: | - |
| `next` | string | - | 次のページのカーソル。前のレスポンスの`next`の値を渡します。最初のページでは省略します |
| `limit` | number | - | 1ページあたりの最大オプション数（1〜1,000）。デフォルトは1,000 |
| `parent` | string | - | オプショングループID。そのオプショングループの下位オプションだけを返します |

### リクエスト例

```bash theme={null}
curl "https://lake.adrop.io/context-targeting/01JAB3XK5Q8V7M2N4P6R9T0W1Y/categories?limit=1" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json"
```

### レスポンス例

```json theme={null}
{
  "items": [
    {
      "_id": "01JAB3XK5RA1B2C3D4E5F6G7H8",
      "name": "Sports",
      "type": "atomic",
      "contextCount": 3,
      "createdAt": "2026-10-13T01:23:45.000Z",
      "updatedAt": "2026-10-13T01:23:45.000Z"
    }
  ],
  "next": "01JAB3XK5RA1B2C3D4E5F6G7H8"
}
```

次のページを取得するには、`next=01JAB3XK5RA1B2C3D4E5F6G7H8`を付けて同じリクエストを送信します。

* 最後のページには`next`がありません。`next`がなくなるまでたどると、すべてのオプションを重複も漏れもなく1回ずつ取得できます。
* 後続のページがある場合でも、1ページの項目数が`limit`より少ないことがあります。取得を終えるのは、`next`がなくなったときだけにしてください。
* 名前で検索する機能はありません。取得した項目は、`name`、`parent`、`children`を使って手元で絞り込んでください。

**エラー**

| ステータス | `errorCode` | 発生条件 |
| - | - | - |
| 404 | `TARGETING_NOT_FOUND` | ターゲティングが存在しない、別のプロジェクトのものである、またはコンテキストターゲティングではない |
| 404 | `TARGETING_CATEGORY_NOT_FOUND` | `parent`がこのターゲティングのオプションではない |
| 400 | `TARGETING_CATEGORY_NOT_SUPPORTED` | `parent`がオプショングループではない |

***

## オプションの取得

オプションを、そのコンテキストIDの1ページ分とあわせて返します。

### リクエスト

```http theme={null}
GET /context-targeting/category/{categoryId}
```

`context-targeting:read`スコープが必要です。

### パスパラメータ

| パラメータ | タイプ | 必須 | 説明 |
| - | - | :-: | - |
| `categoryId` | string | O | オプションID |

### クエリパラメータ

| パラメータ | タイプ | 必須 | 説明 |
| - | - | :-: | - |
| `offset` | number | - | 返す最初のコンテキストIDの位置（0〜50,000）。デフォルトは0 |
| `limit` | number | - | 返すコンテキストIDの最大数（1〜10,000）。デフォルトは10,000 |

### リクエスト例

```bash theme={null}
curl "https://lake.adrop.io/context-targeting/category/01JAB3XK5RA1B2C3D4E5F6G7H8?offset=0&limit=10000" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json"
```

### レスポンス例

```json theme={null}
{
  "_id": "01JAB3XK5RA1B2C3D4E5F6G7H8",
  "name": "Sports",
  "type": "atomic",
  "contextCount": 3,
  "createdAt": "2026-10-13T01:23:45.000Z",
  "updatedAt": "2026-10-13T01:23:45.000Z",
  "targeting": "01JAB3XK5Q8V7M2N4P6R9T0W1Y",
  "contexts": ["sport", "baseball", "soccer"],
  "offset": 0,
  "limit": 10000
}
```

レスポンスは、[オプションオブジェクト](#オプションオブジェクト)に次のフィールドを加えたものです。

| フィールド | タイプ | 説明 |
| - | - | - |
| `targeting` | string | オプションが属するターゲティングのID |
| `contexts` | string\[] | このページのコンテキストID |
| `offset` | number | このページの`offset` |
| `limit` | number | このページの`limit` |

* オプションのすべてのコンテキストIDを読み取るには、`offset`が`contextCount`に達するまで`offset`を`limit`ずつ増やします。
* オプショングループの場合、`contexts`にはオプショングループ自身のコンテキストIDだけが入るため、`ownContextCount`に達するまでページごとに読み取ります。下位オプションのコンテキストIDを読み取るには、その下位オプションを取得します。

**エラー**

| ステータス | `errorCode` | 発生条件 |
| - | - | - |
| 404 | `TARGETING_CATEGORY_NOT_FOUND` | オプションが存在しない、別のプロジェクトのものである、またはコンテキストターゲティングのオプションではない |

***

## オプションの追加

既存のターゲティングにオプションを追加します。通常のオプション、オプショングループ、既存のオプショングループの下位オプションのいずれかを追加できます。

### リクエスト

```http theme={null}
POST /context-targeting/{targetingId}/category
```

`context-targeting:write`スコープが必要です。レスポンスは`201`で、追加した[オプションオブジェクト](#オプションオブジェクト)を返します。

### パスパラメータ

| パラメータ | タイプ | 必須 | 説明 |
| - | - | :-: | - |
| `targetingId` | string | O | オプションを追加するターゲティングのID |

### リクエストボディ

| フィールド | タイプ | 必須 | 説明 |
| - | - | :-: | - |
| `name` | string | O | オプション名。オプショングループと下位オプションも含め、ターゲティング内で一意である必要があります。[名前のルール](/ja/integrations/context-targeting/errors#名前のルール)を参照してください |
| `contexts` | string\[] | - | コンテキストID。オプショングループの場合は、オプショングループ自身のコンテキストID。[コンテキストIDのルール](#コンテキストidのルール)を参照してください |
| `type` | string | - | `atomic`または`collection`。省略した場合、`children`があれば（`[]`を含む）オプショングループに、なければ通常のオプションになります |
| `children` | object\[] | - | オプショングループのみ。オプショングループと一緒に作成する下位オプション。各項目は`name`（必須）と`contexts`を持ちます。下位オプションは常に通常のオプションです |
| `exposeChildren` | boolean | - | オプショングループのみ。下位オプションを広告主に表示します。デフォルトは`false`。[下位オプションを広告主に表示](/ja/integrations/context-targeting/option-groups#下位オプションを広告主に表示)を参照してください |
| `parent` | string | - | 同じターゲティング内の最上位オプショングループのID。新しいオプションを、そのオプショングループの下位オプションとして追加します |

IDはすべてサーバーが発行します。`_id`など、ここに記載されていないフィールドを含むボディは`400`で失敗します。

次の組み合わせは`400 TARGETING_CATEGORY_NOT_SUPPORTED`で失敗し、何も作成されません。

* 下位オプションも自身のコンテキストIDもないオプショングループ
* `children`を指定した`type: "atomic"`
* 通常のオプションに指定した`exposeChildren`
* `parent`と、`type: "collection"`、`children`、`exposeChildren`のいずれかとの組み合わせ。オプショングループに追加するオプションは常に通常のオプションです
* 最上位オプショングループではないオプションを指定した`parent`

1回のリクエストで作成できるオプションは、オプショングループとその下位オプションを数えて最大5,000個で、含められるコンテキストIDは合計10,000個までです。1回のリクエストで多数のオプションを追加するには、[オプションの一括追加](#オプションの一括追加)を使用します。

### リクエスト例

```bash theme={null}
curl -X POST https://lake.adrop.io/context-targeting/01JAB3XK5Q8V7M2N4P6R9T0W1Y/category \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Tech",
    "contexts": ["tech", "ai", "mobile"]
  }'
```

### レスポンス例

```json theme={null}
{
  "_id": "01JAB3XK5RA1B2C3D4E5F6G7H9",
  "name": "Tech",
  "type": "atomic",
  "contextCount": 3,
  "createdAt": "2026-10-13T01:23:45.000Z",
  "updatedAt": "2026-10-13T01:23:45.000Z"
}
```

<Note>
  新しい最上位オプションは、そのターゲティングを使用する広告商品と、その広告商品のキャンペーンにも追加されることがあります。[広告商品とキャンペーンへの影響](#広告商品とキャンペーンへの影響)を参照してください。
</Note>

**エラー**

| ステータス | `errorCode` | 発生条件 |
| - | - | - |
| 404 | `TARGETING_NOT_FOUND` | ターゲティングが存在しない、別のプロジェクトのものである、またはコンテキストターゲティングではない |
| 404 | `TARGETING_CATEGORY_NOT_FOUND` | `parent`がこのターゲティングのオプションではない |
| 400 | `TARGETING_CATEGORY_NOT_SUPPORTED` | 上記の組み合わせのいずれか |
| 400 | `TARGETING_CONTEXT_LIMIT_EXCEEDED` | オプションまたはプロジェクトのコンテキストIDが上限を超える。[コンテキストIDのルール](#コンテキストidのルール)を参照してください |
| 400 | `TARGETING_CATEGORY_LIMIT_EXCEEDED` | ターゲティングのオプションが、下位オプションを含めて100,000個を超える |
| 400 | `TARGETING_COLLECTION_CONTEXT_DUPLICATED` | オプショングループ自身のコンテキストIDのいずれかが、すでにプロジェクト内の別のオプショングループ自身のコンテキストIDになっている。[制約事項](/ja/integrations/context-targeting/option-groups#制約事項)を参照してください |
| 400 | `AD_PRODUCT_TARGETING_POLICY_LIMIT_EXCEEDED` | 広告商品の必須オプションが500個を超える。[広告商品とキャンペーンへの影響](#広告商品とキャンペーンへの影響)を参照してください |
| 409 | `TARGETING_CATEGORY_NAME_DUPLICATE` | 名前がターゲティング内ですでに使われている、またはリクエスト内で重複している。`detail.existingIds`には、その名前を持つ既存オプションのIDが入ります。リクエスト内で名前が重複している場合は、代わりに`detail.duplicateOfIndex`が返されます |

すべてのエラーコードとエラー形式については、[エラーコード](/ja/integrations/context-targeting/errors#エラーコード)を参照してください。

***

## オプションの更新

オプションの名前やコンテキストIDを変更したり、オプションをオプショングループに入れたり、オプショングループから出したり、別のオプショングループに移したり、オプショングループが下位オプションを広告主に表示するかどうかを変更したりします。

### リクエスト

```http theme={null}
PATCH /context-targeting/category/{categoryId}
```

`context-targeting:write`スコープが必要です。レスポンスは`200`で、更新後の[オプションオブジェクト](#オプションオブジェクト)を返します。

### パスパラメータ

| パラメータ | タイプ | 必須 | 説明 |
| - | - | :-: | - |
| `categoryId` | string | O | オプションID |

### リクエストボディ

すべてのフィールドは省略できます。変更するフィールドだけを送信してください。省略したフィールドはそのまま残ります。

| フィールド | タイプ | 説明 |
| - | - | - |
| `name` | string | 新しい名前。[名前のルール](/ja/integrations/context-targeting/errors#名前のルール)を参照してください |
| `contexts` | object | コンテキストIDの変更内容。`add`と`remove`の一方または両方を使うか、`set`を単独で使います |
| `contexts.add` | string\[] | 追加するコンテキストID。オプションにすでにあるIDは無視されます |
| `contexts.remove` | string\[] | 削除するコンテキストID。オプションにないIDは無視されます |
| `contexts.set` | string\[] | オプションのすべてのコンテキストIDを、このリストで置き換えます |
| `parent` | stringまたはnull | 通常のオプションのみ。オプショングループIDを指定すると、オプションをそのオプショングループの下に移動します。`null`を指定すると、オプションをオプショングループから切り離して最上位に移します。[オプションの移動と切り離し](/ja/integrations/context-targeting/option-groups#オプションの移動と切り離し)を参照してください |
| `exposeChildren` | boolean | オプショングループのみ。下位オプションを広告主に表示します |

ボディには次のルールが適用されます。

* `contexts`には`add`、`remove`、`set`のいずれかを含める必要があり、`set`は`add`や`remove`と組み合わせられません。これに反するリクエストは`400`で失敗します。
* `parent`は`contexts`と組み合わせられません。オプションの移動・切り離しとコンテキストIDの変更は、別々のリクエストで行ってください。`parent`は`name`とは組み合わせられます。移動に失敗した場合は、名前も変わりません。
* `null`を受け付けるのは`parent`だけです。`name`、`contexts`、`exposeChildren`、`add`、`remove`、`set`に`null`を指定すると`400`で失敗します。変更しないフィールドは省略してください。
* オプショングループは移動できません。オプショングループに`parent`を指定した場合も、通常のオプションに`exposeChildren`を指定した場合も、`400 TARGETING_CATEGORY_NOT_SUPPORTED`で失敗します。
* オプショングループの場合、`contexts`はオプショングループ自身のコンテキストIDを変更します。下位オプションのないオプショングループから自身のコンテキストIDをすべて削除すると、`400 TARGETING_CATEGORY_NOT_SUPPORTED`で失敗します。
* `name`、`contexts`、`exposeChildren`はまとめて書き込まれます。コンテキストIDの変更に失敗した場合は、名前と`exposeChildren`も変わりません。`add`と`remove`を両方送信すると`add`が先に適用されるため、`remove`が失敗しても、追加したコンテキストIDは残ります。

下位オプションも、ほかの通常のオプションと同じ方法で名前とコンテキストIDを変更できます。`add`/`remove`と`set`の使い分けについては、[コンテキストIDの更新方法](#コンテキストidの更新方法)を参照してください。

### リクエスト例

```bash theme={null}
curl -X PATCH https://lake.adrop.io/context-targeting/category/01JAB3XK5RA1B2C3D4E5F6G7H9 \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "contexts": {
      "add": ["science"],
      "remove": ["mobile"]
    }
  }'
```

### レスポンス例

```json theme={null}
{
  "_id": "01JAB3XK5RA1B2C3D4E5F6G7H9",
  "name": "Tech",
  "type": "atomic",
  "contextCount": 3,
  "createdAt": "2026-10-13T01:23:45.000Z",
  "updatedAt": "2026-10-13T02:10:00.000Z"
}
```

**エラー**

| ステータス | `errorCode` | 発生条件 |
| - | - | - |
| 404 | `TARGETING_CATEGORY_NOT_FOUND` | このプロジェクトのコンテキストターゲティングにオプションが存在しない、または`parent`が同じターゲティングのオプションではない |
| 400 | `TARGETING_CATEGORY_NOT_SUPPORTED` | 上記のケースのいずれか、`parent`が最上位オプショングループではない、または移動によって、下位オプションも自身のコンテキストIDもないオプショングループが残る |
| 400 | `TARGETING_CATEGORY_LOCKED` | 最上位オプションをオプショングループの下に移動しようとしたが、広告商品がそのオプションを必須に設定している、または終了していないキャンペーンがそのオプションを含めているか除外している |
| 400 | `TARGETING_CONTEXT_LIMIT_EXCEEDED` | オプションまたはプロジェクトのコンテキストIDが上限を超える |
| 400 | `TARGETING_COLLECTION_CONTEXT_DUPLICATED` | オプショングループに追加するコンテキストIDが、すでにプロジェクト内の別のオプショングループ自身のコンテキストIDになっている |
| 400 | `AD_PRODUCT_TARGETING_POLICY_LIMIT_EXCEEDED` | オプションを切り離すと、広告商品の必須オプションが500個を超える |
| 409 | `TARGETING_CATEGORY_NAME_DUPLICATE` | 新しい名前がターゲティング内ですでに使われている。`detail.existingIds`には、その名前を持つオプションのIDが入ります |

***

## オプションの削除

オプションとそのコンテキストIDを削除します。

* オプショングループを削除すると、その下位オプションは最上位に移り、広告商品とキャンペーンにおけるオプショングループの設定を引き継ぎます。オプショングループ自身のコンテキストIDがあった場合、それらは一致しなくなります。[オプショングループの削除](/ja/integrations/context-targeting/option-groups#オプショングループの削除)を参照してください。
* 自身のコンテキストIDがないオプショングループの最後の下位オプションは削除できません。代わりにオプショングループを削除してください。

<Warning>
  キャンペーンで使用中のオプションでも、削除はブロックされません。オプションを削除する前に、[広告商品とキャンペーンへの影響](#広告商品とキャンペーンへの影響)を確認してください。
</Warning>

### リクエスト

```http theme={null}
DELETE /context-targeting/category/{categoryId}
```

`context-targeting:write`スコープが必要です。レスポンスは`200`で、削除したオプションのIDを返します。

### パスパラメータ

| パラメータ | タイプ | 必須 | 説明 |
| - | - | :-: | - |
| `categoryId` | string | O | オプションID |

### リクエスト例

```bash theme={null}
curl -X DELETE https://lake.adrop.io/context-targeting/category/01JAB3XK5RA1B2C3D4E5F6G7H9 \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json"
```

### レスポンス例

```json theme={null}
{
  "_id": "01JAB3XK5RA1B2C3D4E5F6G7H9"
}
```

**エラー**

| ステータス | `errorCode` | 発生条件 |
| - | - | - |
| 404 | `TARGETING_CATEGORY_NOT_FOUND` | このプロジェクトのコンテキストターゲティングにオプションが存在しない。削除リクエストを再送した場合は、最初のリクエストですでに削除されています |
| 400 | `TARGETING_CATEGORY_NOT_SUPPORTED` | 自身のコンテキストIDがないオプショングループの最後の下位オプションである |
| 400 | `AD_PRODUCT_TARGETING_POLICY_LIMIT_EXCEEDED` | オプショングループを削除すると、広告商品の必須オプションが500個を超える |

***

## 一括操作

一括操作のエンドポイントでは、1回のリクエストで最大5,000個のオプションを追加、更新、削除できます。`context-targeting:write`スコープが必要です。

* リクエスト全体が失敗しない限り、各一括エンドポイントは`200`を返し、項目ごとの結果をリクエストの順序で返します。各結果の`success`を確認してください。失敗した項目には`error`が入ります。[一括操作のレスポンス](/ja/integrations/context-targeting/errors#一括操作のレスポンス)を参照してください。
* ボディが不正なリクエストは、不正な項目が1つだけでも、リクエスト全体が`400`で失敗します。たとえば、[コンテキストIDのルール](#コンテキストidのルール)に違反するコンテキストID、`add`と組み合わせた`set`、受け付けられないフィールドなどです。
* プロジェクトに対するAPIの書き込みは1件ずつ処理されます。一括リクエストは並列に送らず、1件ずつ順番に送信してください。[同時書き込み](/ja/integrations/context-targeting/errors#同時書き込み)を参照してください。

各リクエストは次の上限内に収める必要があります。

| 上限 | 追加 | 更新 | 削除 |
| - | - | - | - |
| リクエストあたりの項目数 | 1〜5,000 | 1〜5,000 | 1〜5,000 |
| リクエストあたりに作成するオプション数（下位オプションを含む） | 5,000 | – | – |
| リクエストあたりのコンテキストID数（全項目の合計） | 10,000 | 10,000 | – |
| リクエストあたりのオプショングループ関連項目数 | 150 | 150 | 150 |

オプショングループ関連項目は次のとおりです。

* **追加**：オプショングループを作成する項目（`type: "collection"`または`children`）と、`parent`を指定した項目
* **更新**：`parent`を指定した項目（`null`を含む）
* **削除**：オプショングループと下位オプションのID

上限を超えたリクエストは全体が`400`で失敗し、何も適用されません。削除リクエストに含まれるオプショングループと下位オプションが150個を超える場合、エラーは`TARGETING_CATEGORY_TREE_ITEMS_LIMIT_EXCEEDED`になり、`detail.limit`に上限が、`detail.count`にリクエスト内のオプショングループと下位オプションの数が入ります。数万個のオプションのような大量のデータをアップロードするには、最大5,000項目のリクエストを1件ずつ順番に送信してください。

### オプションの一括追加

既存のターゲティングにオプションを追加します。項目ごとに別のターゲティングに追加できます。

#### リクエスト

```http theme={null}
POST /context-targeting/category/bulk/create
```

#### リクエストボディ

| フィールド | タイプ | 必須 | 説明 |
| - | - | :-: | - |
| `items` | object\[] | O | 追加するオプション。各項目には、[オプションの追加](#オプションの追加)のリクエストボディのフィールドを指定します |
| `items[].targeting` | string | O | オプションを追加するターゲティングのID |

成功した項目の`data`には、追加した[オプションオブジェクト](#オプションオブジェクト)が入ります。

#### リクエスト例

```bash theme={null}
curl -X POST https://lake.adrop.io/context-targeting/category/bulk/create \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "items": [
      { "targeting": "01JAB3XK5Q8V7M2N4P6R9T0W1Y", "name": "Entertainment", "contexts": ["entertainment", "movie"] },
      { "targeting": "01JAB3XK5Q8V7M2N4P6R9T0W1Y", "name": "Business", "contexts": ["business", "economy"] },
      { "targeting": "01JAB3XK5Q8V7M2N4P6R9T0W1Y", "name": "Sports", "contexts": ["sport"] }
    ]
  }'
```

#### レスポンス例

ターゲティングに「Sports」という名前のオプションがすでにあるため、3番目の項目だけが失敗します。

```json theme={null}
{
  "results": [
    {
      "index": 0,
      "success": true,
      "data": {
        "_id": "01JAB3XK5VD1E2F3G4H5J6K7M8",
        "name": "Entertainment",
        "type": "atomic",
        "contextCount": 2,
        "createdAt": "2026-10-13T02:20:00.000Z",
        "updatedAt": "2026-10-13T02:20:00.000Z"
      }
    },
    {
      "index": 1,
      "success": true,
      "data": {
        "_id": "01JAB3XK5VD1E2F3G4H5J6K7M9",
        "name": "Business",
        "type": "atomic",
        "contextCount": 2,
        "createdAt": "2026-10-13T02:20:00.000Z",
        "updatedAt": "2026-10-13T02:20:00.000Z"
      }
    },
    {
      "index": 2,
      "success": false,
      "error": {
        "statusCode": 409,
        "errorCode": "TARGETING_CATEGORY_NAME_DUPLICATE",
        "detail": {
          "existingIds": ["01JAB3XK5RA1B2C3D4E5F6G7H8"]
        }
      }
    }
  ],
  "succeeded": 2,
  "failed": 1
}
```

### オプションの一括更新

オプションを更新します。項目ごとに別のオプションを変更できます。

#### リクエスト

```http theme={null}
POST /context-targeting/category/bulk/update
```

#### リクエストボディ

| フィールド | タイプ | 必須 | 説明 |
| - | - | :-: | - |
| `items` | object\[] | O | 更新内容。各項目には、[オプションの更新](#オプションの更新)のリクエストボディのフィールドを指定します |
| `items[]._id` | string | O | 更新するオプションのID |

* 1つのリクエストで、各`_id`は1回しか指定できません。`_id`が重複するとリクエスト全体が`400`で失敗するため、1つのオプションへの変更はすべて1つの項目にまとめてください。
* 各項目は個別に適用され、同時に実行されることがあります。それでも、結果はリクエストの順序で返されます。
* 前の項目で使われなくなった名前は、同じリクエスト内の後の項目で使用できます。

成功した項目の`data`には、更新後の[オプションオブジェクト](#オプションオブジェクト)が入ります。

#### リクエスト例

```bash theme={null}
curl -X POST https://lake.adrop.io/context-targeting/category/bulk/update \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "items": [
      { "_id": "01JAB3XK5RA1B2C3D4E5F6G7H8", "contexts": { "add": ["basketball"] } },
      { "_id": "01JAB3XK5RA1B2C3D4E5F6G7H9", "name": "Technology" }
    ]
  }'
```

#### レスポンス例

```json theme={null}
{
  "results": [
    {
      "index": 0,
      "success": true,
      "data": {
        "_id": "01JAB3XK5RA1B2C3D4E5F6G7H8",
        "name": "Sports",
        "type": "atomic",
        "contextCount": 4,
        "createdAt": "2026-10-13T01:23:45.000Z",
        "updatedAt": "2026-10-13T02:10:00.000Z"
      }
    },
    {
      "index": 1,
      "success": true,
      "data": {
        "_id": "01JAB3XK5RA1B2C3D4E5F6G7H9",
        "name": "Technology",
        "type": "atomic",
        "contextCount": 3,
        "createdAt": "2026-10-13T01:23:45.000Z",
        "updatedAt": "2026-10-13T02:10:00.000Z"
      }
    }
  ],
  "succeeded": 2,
  "failed": 0
}
```

### オプションの一括削除

オプションを削除します。各IDには、[オプションの削除](#オプションの削除)と同じルールが適用されます。

<Warning>
  オプショングループとその下位オプションを同じリクエストで削除しないでください。オプショングループと下位オプションは、リクエストの順序で処理されます。オプショングループが先にある場合、下位オプションは最上位に移ってから、最上位オプションとして削除されます。下位オプションが先にあり、オプショングループ自身のコンテキストIDがない場合は、最後の下位オプションの削除が失敗し、そのオプションは残ります。
</Warning>

#### リクエスト

```http theme={null}
POST /context-targeting/category/bulk/delete
```

#### リクエストボディ

| フィールド | タイプ | 必須 | 説明 |
| - | - | :-: | - |
| `ids` | string\[] | O | 削除するオプションのID |

成功した項目の`data`には、削除したオプションのIDが入ります。

#### リクエスト例

```bash theme={null}
curl -X POST https://lake.adrop.io/context-targeting/category/bulk/delete \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "ids": ["01JAB3XK5RA1B2C3D4E5F6G7H8", "01JAB3XK5RA1B2C3D4E5F6G7H9"]
  }'
```

#### レスポンス例

```json theme={null}
{
  "results": [
    { "index": 0, "success": true, "data": { "_id": "01JAB3XK5RA1B2C3D4E5F6G7H8" } },
    { "index": 1, "success": true, "data": { "_id": "01JAB3XK5RA1B2C3D4E5F6G7H9" } }
  ],
  "succeeded": 2,
  "failed": 0
}
```

***

## コンテキストIDのルール

次のルールは、`contexts`、`children`、`add`、`remove`、`set`で送信するすべてのコンテキストIDに適用されます。

| ルール | 説明 |
| - | - |
| 空白 | 前後の空白は取り除かれるため、`" sport "`と`sport`は同じコンテキストIDです。コンテキストIDの途中にあるスペースはそのまま残ります |
| 長さ | 前後の空白を取り除いた後、UTF-8で1〜256バイト。空の値や空白だけの値は使用できません |
| カンマ | 使用できません |
| 文字 | それ以外の文字は使用できますが、テキストは正しい形式（well-formed）のUnicodeである必要があります。対になっていないサロゲートは使用できません |
| 大文字と小文字 | 区別されます。`Sport`と`sport`は別のコンテキストIDです。ページが広告リクエストで送信する値とまったく同じ値で登録してください |
| 重複 | 1回だけ保存されます。リクエスト内の重複はまとめられ、オプションにすでにあるコンテキストIDを追加しても何も変わりません |

リクエスト内のコンテキストIDが1つでもこれらのルールに違反すると、リクエスト全体が`400`で失敗します。

同じコンテキストIDを複数のオプションに登録できます。そのコンテキストIDを含むリクエストは、それらすべてのオプションに一致します。例外はオプショングループ自身のコンテキストIDで、プロジェクト内の別のオプショングループ自身のコンテキストIDと同じにすることはできません。[制約事項](/ja/integrations/context-targeting/option-groups#制約事項)を参照してください。

コンテキストIDには、数とサイズの上限もあります。

| 上限 | 値 |
| - | - |
| オプションあたりのコンテキストID数 | 50,000。オプショングループの場合は、自身のコンテキストIDを数えます |
| オプションあたりの合計サイズ | 8 MB（コンテキストIDをUTF-8で表したサイズの合計） |
| プロジェクトあたりのコンテキストID数 | 200,000（プロジェクト内のすべてのコンテキストターゲティングの全オプションの合計）。2つのオプションにある同じコンテキストIDは2個と数えます |
| リクエストあたりのコンテキストID数 | 10,000（すべての項目と`add`、`remove`、`set`の合計） |

オプションまたはプロジェクトが上限を超える変更は、`400 TARGETING_CONTEXT_LIMIT_EXCEEDED`で失敗します。これらの上限は、変更によってオプションまたはプロジェクトが大きくなる場合にのみチェックされるため、コンテキストIDを削除するだけの変更がブロックされることはありません。コンテキストIDが10,000個を超えるリクエストは、全体が`400`で失敗します。すべての上限については、[上限](/ja/integrations/context-targeting/errors#上限)を参照してください。

***

## コンテキストIDの更新方法

コンテキストIDは、[オプションの更新](#オプションの更新)または[オプションの一括更新](#オプションの一括更新)で、`add`/`remove`または`set`を使って変更します。

| 方法 | 動作 | 適した場面 |
| - | - | - |
| `add` / `remove` | 指定したコンテキストIDだけを変更します | セクションの追加や削除など、変更をその都度把握できる場合 |
| `set` | オプションのすべてのコンテキストIDを、指定したリストで置き換えます | オプションの完全なリストがあり、そのコンテキストIDが10,000個以下の場合 |

`add`、`remove`、`set`は、同じリクエストをもう一度送信しても結果が変わらないため、タイムアウトした後に再送できます。[再試行と重複リクエスト](/ja/integrations/context-targeting/errors#再試行と重複リクエスト)を参照してください。

**コンテキストIDが10,000個を超える場合**

1回のリクエストに含められるコンテキストIDは最大10,000個のため、それより長いリストを`set`で一度に置き換えることはできません。代わりに、次の手順でオプションを同期します。

1. [オプションの取得](#オプションの取得)で`offset`と`limit`を使ってページごとに読み取り、オプションの現在のコンテキストIDを取得します。
2. 取得したコンテキストIDを、手元のリストと比較します。
3. 差分だけを、1回のリクエストあたり最大10,000個のコンテキストIDに収めて、`add`と`remove`で1件ずつ順番に送信します。

完全なリストを複数の`set`リクエストに分割しないでください。`set`は毎回すべてのコンテキストIDを置き換えるため、後の`set`によって、前のリクエストで送ったコンテキストIDが消えます。`set`を1回送ってから`add`リクエストを続ける場合でも、リクエストとリクエストの間はオプションにリストの一部しかない状態になり、広告配信がその途中のリストを読み込む可能性があります。

変更は少し遅れて広告配信に反映されます。変更が読み込まれたかどうかを確認する方法は、[変更が反映されるタイミング](/ja/integrations/context-targeting/overview#変更が反映されるタイミング)を参照してください。

***

## 広告商品とキャンペーンへの影響

広告商品とキャンペーンはオプションを選択して使うため、オプションを変更するとキャンペーンの配信先が変わることがあります。コンテキストIDを追加または削除すると、そのオプションを含める、または除外するキャンペーンが配信されるページが変わります。

**新しい最上位オプション**

最上位オプションを追加すると、通常のオプションかオプショングループかにかかわらず、そのターゲティングの設定を持つ広告商品にもそのオプションが追加されます。

* 広告商品がターゲティングの現在の最上位オプションをすべて **必須含む** に設定している場合、新しいオプションも **必須含む** に設定され、その広告商品の終了していないキャンペーンにも含まれます。この動作は **必須除外** でも同じです。
* それ以外の場合、新しいオプションは、広告主が選択できるオプションとして広告商品に追加されます。一部の最上位オプションが必須ではない場合や、最上位オプションに **必須含む** と **必須除外** が混在している場合がこれにあたります。キャンペーンは変わりません。

つまり、すべてのオプションを必須にしている広告商品では、新しいオプションによってキャンペーンの配信先が広がる（**必須含む**）か、狭まる（**必須除外**）ことになります。広告商品でターゲティングの最上位オプションが1つでも必須でなくなると、それ以降に追加する新しいオプションも、選択可能なオプションとして追加されます。新しいオプションを必須にするには、コンソールで広告商品のターゲティングを変更してください。[ターゲティングの販売](/ja/targeting/sell)を参照してください。

オプショングループに追加した下位オプションは、それ自体としては広告商品に追加されません。代わりに、オプショングループが下位オプションのコンテキストIDにも一致するようになります。[オプショングループへのオプション追加](/ja/integrations/context-targeting/option-groups#オプショングループへのオプション追加)を参照してください。

**必須オプションの上限**

1つの広告商品で **必須含む** または **必須除外** に設定できるオプションは、すべてのターゲティングを合わせて最大500個です。上記のルールによって広告商品がこの上限を超える場合、新しい最上位オプションは作成されず、`400 AD_PRODUCT_TARGETING_POLICY_LIMIT_EXCEEDED`で失敗します。

| フィールド | 説明 |
| - | - |
| `detail.limit` | 広告商品あたりの必須オプションの上限 |
| `detail.count` | 変更後に広告商品が持つことになる必須オプションの数。複数の広告商品が上限を超える場合は、その中で最も大きい数 |
| `detail.products` | 上限を超えることになる広告商品のID |

一括リクエストでは、そのターゲティングに追加する新しい最上位オプションがすべて失敗し、ほかの項目は適用されます。コンソールで広告商品の必須オプションを減らしてから、リクエストを再送してください。オプショングループの削除や下位オプションの切り離しでも、オプショングループの設定が下位オプションにコピーされるため、同じ上限が適用されます。

**オプションを削除する場合**

[ターゲティングの削除](/ja/integrations/context-targeting/targetings#ターゲティングの削除)とは異なり、オプションはキャンペーンで使用中でも削除がブロックされません。オプションは、それを選択しているキャンペーンから削除されます。キャンペーンがそのターゲティングから含めていたオプションがそれ1つだけだった場合、キャンペーンはそのターゲティングのコンテキストIDを一切必要としなくなります。キャンペーンは停止せず、ほかのコンテキストIDを含むリクエストや、コンテキストIDのないリクエストにも配信されることがあります。

オプションを削除する前に、キャンペーンで使用されていないか確認してください。コンソールでは、キャンペーンが予約されているオプションのステータスが **使用中** になります。[ターゲティングの管理](/ja/targeting/manage)を参照してください。オプションを削除する前に、それらのキャンペーンを変更するか終了してください。

**コンテキストIDを除外する場合**

オプションには、一致させるコンテキストIDを並べることしかできません。「このオプションに含まれない」という条件はありません。特定のページに広告を表示しないようにするには、それらのページのコンテキストIDをオプションに登録し、広告商品やキャンペーンでそのオプションを除外します（例：広告商品で **必須除外** に設定）。それ以外のコンテキストIDをすべて並べたオプションは作らないでください。


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.