> ## 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では、オプショングループの作成、下位オプションの追加と移動を行えるほか、広告主が下位オプションを個別に選択できるかどうかを設定できます。

このページのリクエストには、`context-targeting:write`スコープを持つAPIキーが必要です。オプショングループの取得には`context-targeting:read`が必要です。[事前準備](/ja/integrations/context-targeting/overview#事前準備)を参照してください。

このページの例では **News Sections** ターゲティング（`01JAB3XK5Q8V7M2N4P6R9T0W1Y`）に、下位オプション **Baseball** と **Soccer** を持つ **Sports** オプショングループを作成します。オプション名はターゲティング内で一意である必要があるため、このターゲティングには **Sports** という名前のオプションがほかにないものとします。

***

## オプショングループとは

オプショングループは、自身のコンテキストIDと下位オプションのコンテキストIDの両方に一致します。次の構成では **Sports** を含むキャンペーンが、コンテキストIDが`sport`、`baseball`、`soccer`のいずれかである広告リクエストに一致します。

| オプション | タイプ | 自身のコンテキストID | 一致するコンテキストID |
| - | - | - | - |
| **Sports** | オプショングループ | `sport` | `sport`、`baseball`、`soccer` |
| **Baseball** | Sportsの下位オプション | `baseball` | `baseball` |
| **Soccer** | Sportsの下位オプション | `soccer` | `soccer` |

* **階層は1段階のみ**：下位オプションは常に通常のオプション（`type: "atomic"`）です。オプショングループは常に最上位のオプションで、ほかのオプショングループを含むことはできません。
* **空にはできない**：オプショングループには、下位オプションか自身のコンテキストIDが少なくとも1つ必要です。
* **自身のコンテキストIDは一意**：オプショングループ自身のコンテキストIDを、プロジェクト内のほかのオプショングループの自身のコンテキストIDと重複させることはできません。[制約事項](#制約事項)を参照してください。
* **名前**：オプショングループと下位オプションの名前は[名前のルール](/ja/integrations/context-targeting/errors#名前のルール)に従い、オプショングループと下位オプションを含めてターゲティング内で一意である必要があります。重複すると`409 TARGETING_CATEGORY_NAME_DUPLICATE`で失敗します。

[オプションオブジェクト](/ja/integrations/context-targeting/options#オプションオブジェクト)では、オプショングループと下位オプションに次のフィールドがあります。

| フィールド | タイプ | 説明 |
| - | - | - |
| `type` | string | オプショングループは`collection`です。下位オプションは`atomic`です。 |
| `contextCount` | number | オプショングループの場合は、一致するコンテキストIDの数。自身と下位オプションのコンテキストIDを合わせ、重複を除いて数えます |
| `ownContextCount` | number | オプショングループのみ。自身のコンテキストIDの数 |
| `exposeChildren` | boolean | オプショングループのみ。下位オプションを広告主に表示するかどうか。一度も設定していない場合は`false` |
| `children` | string\[] | オプショングループのみ。先頭50個の下位オプションのID |
| `childCount` | number | オプショングループのみ。下位オプションの総数 |
| `parent` | string | 下位オプションのみ。所属するオプショングループのID |

オプショングループの内容は、次のように取得します。

* [オプションの取得](/ja/integrations/context-targeting/options#オプションの取得)の`contexts`にはオプショングループ自身のコンテキストIDだけが含まれ、`offset`と`limit`でページ単位に取得します（合計`ownContextCount`件）。下位オプションのコンテキストIDは、各下位オプションを取得して確認してください。
* `childCount`が50を超える場合は、[オプション一覧の取得](/ja/integrations/context-targeting/options#オプション一覧の取得)で`parent`クエリパラメータにオプショングループIDを指定すると、すべての下位オプションを取得できます。

オプショングループや下位オプションの名前、コンテキストIDを変更するには、ほかのオプションと同じように[オプションの更新](/ja/integrations/context-targeting/options#オプションの更新)を使います。オプショングループの場合、`contexts`で変更されるのは自身のコンテキストIDだけです。変更は少し時間をおいて広告配信に反映されます。[変更が反映されるタイミング](/ja/integrations/context-targeting/overview#変更が反映されるタイミング)を参照してください。

***

## オプショングループの作成

[オプションの追加](/ja/integrations/context-targeting/options#オプションの追加)と同じエンドポイントに、`type: "collection"`と`children`のどちらか、または両方を指定して送信します。`children`の各項目は新しい下位オプションになり、オプショングループと一緒に作成されます。

### リクエスト

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

### パスパラメータ

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

### リクエストボディ

| フィールド | タイプ | 必須 | 説明 |
| - | - | :-: | - |
| `name` | string | O | オプショングループ名 |
| `type` | string | - | `collection`。`children`を送信する場合は省略できます |
| `contexts` | string\[] | - | オプショングループ自身のコンテキストID |
| `children` | object\[] | - | オプショングループと一緒に作成する下位オプション |
| `children[].name` | string | O | 下位オプション名 |
| `children[].contexts` | string\[] | - | 下位オプションのコンテキストID |
| `exposeChildren` | boolean | - | 下位オプションを広告主に表示するかどうか。デフォルトは`false`。[下位オプションを広告主に表示](#下位オプションを広告主に表示)を参照してください |

* `children`に1件以上の項目、または`contexts`に1つ以上のコンテキストIDを指定してください。どちらもないオプショングループは`400 TARGETING_CATEGORY_NOT_SUPPORTED`で失敗します。`type: "atomic"`と`children`を一緒に指定した場合も同様です。
* `children`の項目に指定できるのは`name`と`contexts`だけです。下位オプションが自身の下位オプションを持つことはできません。
* オプショングループ自身のコンテキストIDのいずれかが、プロジェクト内のほかのオプショングループの自身のコンテキストIDとしてすでに使われている場合、リクエストは`400 TARGETING_COLLECTION_CONTEXT_DUPLICATED`で失敗します。[制約事項](#制約事項)を参照してください。
* 新しいオプショングループは新しい最上位オプションなので、ほかの新しいオプションと同じく[広告商品とキャンペーンへの影響](/ja/integrations/context-targeting/options#広告商品とキャンペーンへの影響)が適用されます。

オプショングループは、[ターゲティングの作成](/ja/integrations/context-targeting/targetings#ターゲティングの作成)時に`categories`の各項目に同じフィールドを指定して作成することも、[オプションの一括追加](/ja/integrations/context-targeting/options#オプションの一括追加)で作成することもできます。

### リクエスト例

```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": "Sports",
    "type": "collection",
    "contexts": ["sport"],
    "children": [
      { "name": "Baseball", "contexts": ["baseball"] }
    ]
  }'
```

自身のコンテキストIDだけを持つオプショングループを作成するには、`type: "collection"`を指定し、`children`は省略します。

```json theme={null}
{
  "name": "Sports",
  "type": "collection",
  "contexts": ["sport"]
}
```

### レスポンス例

レスポンスは`201`で、作成されたオプショングループが返されます。

```json theme={null}
{
  "_id": "01JAB3XK5SB1C2D3E4F5G6H7J8",
  "name": "Sports",
  "type": "collection",
  "contextCount": 2,
  "ownContextCount": 1,
  "exposeChildren": false,
  "children": ["01JAB3XK5TC1D2E3F4G5H6J7K8"],
  "childCount": 1,
  "createdAt": "2026-10-13T01:23:45.000Z",
  "updatedAt": "2026-10-13T01:23:45.000Z"
}
```

***

## オプショングループへのオプション追加

既存のオプショングループに新しい下位オプションを追加するには、[オプションの追加](/ja/integrations/context-targeting/options#オプションの追加)のエンドポイントに、`parent`としてオプショングループIDを指定して送信します。

* `parent`には、同じターゲティング内の最上位のオプショングループを指定する必要があります。ターゲティングにそのIDのオプションがない場合、リクエストは`404 TARGETING_CATEGORY_NOT_FOUND`で失敗します。そのオプションがオプショングループでない場合は`400 TARGETING_CATEGORY_NOT_SUPPORTED`で失敗します。
* 新しいオプションは通常のオプションになります。`parent`と一緒に`type: "collection"`、`children`、`exposeChildren`のいずれかを指定すると、`400 TARGETING_CATEGORY_NOT_SUPPORTED`で失敗します。
* オプショングループは、新しいオプションのコンテキストIDにも一致するようになります。オプショングループを含むキャンペーンはそれらのコンテキストIDもターゲットにし、オプショングループを除外するキャンペーンはそれらも除外するようになります。広告商品の設定は変わりません。

既存のオプションをオプショングループに入れる方法は、[オプションの移動と切り離し](#オプションの移動と切り離し)を参照してください。

### リクエスト

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

### パスパラメータ

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

### リクエストボディ

| フィールド | タイプ | 必須 | 説明 |
| - | - | :-: | - |
| `name` | string | O | 下位オプション名 |
| `contexts` | string\[] | - | 下位オプションのコンテキストID |
| `parent` | string | O | オプションを追加するオプショングループのID |

### リクエスト例

```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": "Soccer",
    "contexts": ["soccer"],
    "parent": "01JAB3XK5SB1C2D3E4F5G6H7J8"
  }'
```

### レスポンス例

レスポンスは`201`で、作成された下位オプションが返されます。

```json theme={null}
{
  "_id": "01JAB3XK5TC1D2E3F4G5H6J7K9",
  "name": "Soccer",
  "type": "atomic",
  "contextCount": 1,
  "parent": "01JAB3XK5SB1C2D3E4F5G6H7J8",
  "createdAt": "2026-10-13T01:25:10.000Z",
  "updatedAt": "2026-10-13T01:25:10.000Z"
}
```

***

## オプションの移動と切り離し

オプションの位置を変更するには、[オプションの更新](/ja/integrations/context-targeting/options#オプションの更新)で`parent`を送信します。

* オプショングループIDを指定すると、オプションは最上位またはほかのオプショングループから、そのオプショングループの下に移動します。
* `null`を指定すると、下位オプションはオプショングループから切り離され、最上位に移動します。

| 移動 | 広告商品とキャンペーンへの影響 |
| - | - |
| 最上位 → オプショングループ | 広告商品にあるそのオプション自体の設定は削除されます。広告商品でそのオプションが **必須含む** または **必須除外** に設定されている場合や、終了していないキャンペーンがそのオプションを含むか除外している場合（削除・キャンセルされたキャンペーンと、広告主が作成した下書きは対象外）は、`400 TARGETING_CATEGORY_LOCKED`で失敗します。先にそれらの設定を解除してください。 |
| オプショングループ → 最上位 | オプションは広告商品とキャンペーンにおけるオプショングループの設定を引き継ぐため、オプショングループを含んでいた、または除外していたキャンペーンは、引き続きそのオプションのコンテキストIDを含む、または除外します。これにより **必須含む** または **必須除外** に設定されたオプションが500個を超える広告商品が生じる場合、リクエストは`400 AD_PRODUCT_TARGETING_POLICY_LIMIT_EXCEEDED`で失敗します。 |
| オプショングループ → 別のオプショングループ | 広告商品とキャンペーンは変わりません。 |

移動先のオプショングループはそのオプションのコンテキストIDに一致するようになり、移動元のオプショングループは一致しなくなります。

* オプショングループは移動できません。オプショングループに`parent`を指定すると`400 TARGETING_CATEGORY_NOT_SUPPORTED`で失敗します。
* 移動先は、同じターゲティング内の最上位のオプショングループである必要があります。そうでない場合、リクエストは`404 TARGETING_CATEGORY_NOT_FOUND`または`400 TARGETING_CATEGORY_NOT_SUPPORTED`で失敗します。
* 自身のコンテキストIDを持たないオプショングループの最後の下位オプションは、移動も切り離しもできません。リクエストは`400 TARGETING_CATEGORY_NOT_SUPPORTED`で失敗します。

<Warning>
  このロックは、オプションの **必須含む** や **必須除外** の設定、キャンペーンでの含む・除外の設定が自動で付いた場合にも適用されます（例：切り離されたときやオプショングループが削除されたときに、オプショングループから引き継いだ設定）。その設定が解除されるまで、APIでそのオプションをオプショングループの下に戻すことはできません。オプションをオプショングループに置く場合は、最初から`parent`または`children`で作成してください。
</Warning>

### リクエスト

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

### パスパラメータ

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

### リクエストボディ

| フィールド | タイプ | 必須 | 説明 |
| - | - | :-: | - |
| `parent` | stringまたはnull | O | オプションの移動先のオプショングループID、または最上位に切り離す場合は`null` |
| `name` | string | - | 新しい名前で、移動と同時に適用されます。移動が失敗した場合は、名前も変更されません |

`parent`は`contexts`と一緒に指定できません。コンテキストIDは別のリクエストで変更してください。

### リクエスト例

**Soccer** を切り離して最上位に移動します。

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

**Sports** の下に戻すには、代わりにオプショングループIDを送信します。

```json theme={null}
{
  "parent": "01JAB3XK5SB1C2D3E4F5G6H7J8"
}
```

### レスポンス例

レスポンスは`200`で、更新後のオプションが返されます。切り離されたオプションには`parent`がありません。

```json theme={null}
{
  "_id": "01JAB3XK5TC1D2E3F4G5H6J7K9",
  "name": "Soccer",
  "type": "atomic",
  "contextCount": 1,
  "createdAt": "2026-10-13T01:25:10.000Z",
  "updatedAt": "2026-10-13T01:30:00.000Z"
}
```

***

## 下位オプションを広告主に表示

デフォルトでは、広告主はオプショングループを全体としてしか選択できません。`exposeChildren`を`true`にすると、広告主はキャンペーンの予約時に、下位オプションを1つずつ含めたり除外したりできるようになります。

* 広告主が下位オプションを選択できるのは、広告商品でそのオプショングループの選択方法が **自由選択** の場合だけです。[ターゲティングの販売](/ja/targeting/sell)を参照してください。
* `exposeChildren`によって、オプショングループが一致する対象は変わりません。変更しても、既存の広告商品やキャンペーンは変更されません。
* `exposeChildren`を指定できるのはオプショングループだけです。ほかのオプションに指定すると`400 TARGETING_CATEGORY_NOT_SUPPORTED`で失敗します。`null`は`400`で失敗するため、値は`true`または`false`で指定してください。
* [オプショングループの作成](#オプショングループの作成)時に設定することもできます。

### リクエスト

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

### パスパラメータ

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

### リクエストボディ

| フィールド | タイプ | 必須 | 説明 |
| - | - | :-: | - |
| `exposeChildren` | boolean | O | `true`で下位オプションを広告主に表示し、`false`で非表示にします |

同じリクエストで`name`と`contexts`も送信できます。

### リクエスト例

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

### レスポンス例

レスポンスは`200`で、更新後のオプショングループが返されます。

```json theme={null}
{
  "_id": "01JAB3XK5SB1C2D3E4F5G6H7J8",
  "name": "Sports",
  "type": "collection",
  "contextCount": 3,
  "ownContextCount": 1,
  "exposeChildren": true,
  "children": ["01JAB3XK5TC1D2E3F4G5H6J7K8", "01JAB3XK5TC1D2E3F4G5H6J7K9"],
  "childCount": 2,
  "createdAt": "2026-10-13T01:23:45.000Z",
  "updatedAt": "2026-10-13T01:35:00.000Z"
}
```

***

## オプショングループの削除

オプショングループは[オプションの削除](/ja/integrations/context-targeting/options#オプションの削除)で削除します。下位オプションは削除されません。

* 下位オプションは最上位に移動し、広告商品とキャンペーンにおけるオプショングループの設定を引き継ぎます。たとえば、広告商品で **Sports** が **必須含む** に設定されている場合は **Baseball** と **Soccer** が **必須含む** になり、Sportsを含んでいたキャンペーンはBaseballとSoccerを含むようになります。
* オプショングループ自身のコンテキストIDは削除され、一致しなくなります。この例では、Sportsを含んでいたキャンペーンは`sport`に一致しなくなります。
* 設定の引き継ぎにより **必須含む** または **必須除外** に設定されたオプションが500個を超える広告商品が生じる場合、リクエストは`400 AD_PRODUCT_TARGETING_POLICY_LIMIT_EXCEEDED`で失敗し、何も削除されません。

キャンペーンで使用中でも削除できます。オプショングループに下位オプションがない場合、そのオプショングループを含んでいたキャンペーンからはその条件がなくなります。[広告商品とキャンペーンへの影響](/ja/integrations/context-targeting/options#広告商品とキャンペーンへの影響)を参照してください。

<Note>
  コンソールでグループを**削除**すると、下位オプションも一緒に削除されます。APIでオプショングループを削除すると、コンソールの**グループを解除**と同じように、下位オプションが最上位オプションとして残ります。
</Note>

### リクエスト

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

### パスパラメータ

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

### リクエスト例

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

### レスポンス例

レスポンスは`200`で、削除されたオプショングループのIDが返されます。

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

***

## 制約事項

**構造**

* オプショングループは移動できず、オプションのタイプは作成後に変更できません。既存のオプションをまとめるには、オプショングループを作成してから、その下にオプションを[移動](#オプションの移動と切り離し)します。新しいオプショングループは空にできないため、自身のコンテキストIDか新しい下位オプションを指定して作成してください。
* `children`で作成した下位オプションも、1リクエストあたりと1ターゲティングあたりのオプション数の上限に含まれます。[上限](/ja/integrations/context-targeting/errors#上限)を参照してください。

**自身のコンテキストIDはオプショングループ間で一意**

* オプショングループ自身のコンテキストIDは、ほかのオプショングループがどのコンテキストターゲティングにあっても、プロジェクト内のほかのオプショングループの自身のコンテキストIDと重複できません。通常のオプションと下位オプションは、どのオプションともコンテキストIDを共有できます。
* このルールは、オプショングループの作成時と、`add`または`set`でオプショングループに自身のコンテキストIDを追加するときに適用されます。重複すると`400 TARGETING_COLLECTION_CONTEXT_DUPLICATED`で失敗し、`detail.conflicts`には、重複したコンテキストIDとそれをすでに持つオプショングループが最大20件まで含まれます。[エラーコード](/ja/integrations/context-targeting/errors#エラーコード)を参照してください。

**オプショングループは空にできない**

| リクエスト | 結果 |
| - | - |
| 自身のコンテキストIDを持たないオプショングループの最後の下位オプションを削除、移動、または切り離す | `400 TARGETING_CATEGORY_NOT_SUPPORTED`。代わりにオプショングループを削除してください。下位オプションは最上位に移動します。 |
| 下位オプションを持たないオプショングループの最後の自身のコンテキストIDを、`remove`または`set: []`で削除する | `400 TARGETING_CATEGORY_NOT_SUPPORTED` |

自身のコンテキストIDを持つオプショングループは、下位オプションをすべてなくすことができます。その場合、自身のコンテキストIDだけを持つオプショングループとして残ります。

**一括リクエストあたりのオプショングループ関連項目**

オプションの一括リクエスト1件に含められるオプショングループ関連項目は、最大150件です。これを超えるとリクエスト全体が`400`で失敗し、何も反映されません。項目を分割し、リクエストを1件ずつ順番に送信してください。

| 一括リクエスト | オプショングループ関連項目 |
| - | - |
| [オプションの一括追加](/ja/integrations/context-targeting/options#オプションの一括追加) | オプショングループを作成する項目（`type: "collection"`または`children`）と、`parent`を指定した項目 |
| [オプションの一括更新](/ja/integrations/context-targeting/options#オプションの一括更新) | `parent`を指定した項目（`null`を含む） |
| [オプションの一括削除](/ja/integrations/context-targeting/options#オプションの一括削除) | オプショングループと下位オプションのID |

* 一括削除の場合、エラーコードは`TARGETING_CATEGORY_TREE_ITEMS_LIMIT_EXCEEDED`です。`detail.limit`は上限、`detail.count`はリクエストに含まれるオプショングループと下位オプションの数です。
* オプショングループ名の変更、自身のコンテキストIDの変更、`exposeChildren`の設定は、オプショングループ関連項目に含まれません。

**オプショングループとその下位オプションを同じ一括リクエストで削除しない**

結果は`ids`内の順序によって変わります。

* **オプショングループが先**：下位オプションは最上位に移動してオプショングループの設定を引き継いだ後、最上位のオプションとして削除されます。オプショングループを含んでいたキャンペーンから、その条件がなくなることがあります。
* **下位オプションが先**：オプショングループが自身のコンテキストIDを持たない場合、最後の下位オプションの削除は`400 TARGETING_CATEGORY_NOT_SUPPORTED`で失敗します。そのオプションは、その後オプショングループが削除されたときに最上位に移動します。


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