> ## Documentation Index
> Fetch the complete documentation index at: https://docs.kameleoon.com/llms.txt
> Use this file to discover all available pages before exploring further.

# paramsIO の使用

> paramsIO オブジェクトを使用して、Automation API のクエリ結果のフィルタリング、ページネーション、ソートを行います。サイト、実験、複合フィルタの取得例を含みます。

## 目的

Automation API では、`paramsIO` オブジェクトを使用してクエリコレクションのフィルタリング、ページネーション、ソートを行います。このチュートリアルでは、`paramsIO` の実用的なユースケースを紹介します。

* `siteCode` 値を使用した**複数の `siteId` の取得**
* ステータスによる**実験のフィルタリング**
* 結果サイズを制御するための**ページネーション条件の設定**

`paramsIO` パターンは多くのエンドポイントで使用され、一貫した構造を持っているため、正確なデータ取得のための強力なツールとなります。

## 要件

### アクセストークン

Automation API には**アクセストークン**が必要です。

トークンをプログラム的に取得するには、[Get started の記事](/developer-docs/apis/automation-api-rest/get-started/get-started#1-obtain-an-access-token)の指示に従ってください。

***

## paramsIO の理解

`paramsIO` オブジェクトは、API エンドポイントに構造化されたクエリを渡します。通常、ページネーション、ソート、フィルタリングのツールが含まれます。`paramsIO` の詳細については、[Get started の記事](/developer-docs/apis/automation-api-rest/get-started/get-started#query-parameters)を参照してください。

### フィルター構造

フィルターは一貫した JSON 構造を使用します。

| プロパティ        | 型      | 説明                                            |
| :----------- | :----- | :-------------------------------------------- |
| `field`      | String | フィルター対象のコレクション内のプロパティ(例: `"code"`、`"status"`) |
| `operator`   | String | 比較演算子(例: `"EQUAL"`、`"BETWEEN"`、`"GREATER"`)   |
| `parameters` | Array  | マッチさせる値の配列                                    |

<Note>
  フィルタ JSON オブジェクトは、エンドポイント URL に追加する際に **URL エンコード** されている必要があります。たとえば、`[` は `%5B` に、`"` は `%22` になります。
</Note>

***

## ユースケース 1: siteCode で複数の siteId を取得する

Automation API は、ほとんどの操作で内部の数値 `id` を必要とします。この例では、`siteCode` 値を使って複数のサイト ID を同時に取得します。

### ステップ 1: フィルターを定義する

複数のサイトを取得するには、サイトコードの配列とともに `EQUAL` 演算子を使用します。

```json theme={null}
[
  {
    "field": "code",
    "operator": "EQUAL",
    "parameters": ["xdrio4plsn", "adflwp2mms", "lricdj5pqw"]
  }
]
```

### ステップ 2: リクエストを送信する

URL エンコードされたフィルターを付けて `/sites` エンドポイントに `GET` リクエストを送信します。

**エンドポイント:** `GET https://api.kameleoon.com/sites`

**リクエスト例:**

```bash theme={null}
curl -L -X GET 'https://api.kameleoon.com/sites?filter=%5B%7B%22field%22%3A%22code%22%2C%22operator%22%3A%22EQUAL%22%2C%22parameters%22%3A%5B%22xdrio4plsn%22%2C%22adflwp2mms%22%2C%22lricdj5pqw%22%5D%7D%5D' \
-H 'Authorization: Bearer <ACCESS_TOKEN>'
```

### ステップ 3: レスポンスを処理する

API は一致するすべてのサイトを JSON 配列で返します。

```json theme={null}
[
  {
    "id": 42099,
    "url": "https://www.example-production.com/",
    "name": "Production Environment",
    "code": "xdrio4plsn"
    ...
  },
  {
    "id": 42100,
    "url": "https://www.example-staging.com/",
    "name": "Staging Environment",
    "code": "adflwp2mms"
    ...
  },
  {
    "id": 42101,
    "url": "https://www.example-test.com/",
    "name": "Test Environment",
    "code": "lricdj5pqw"
    ...
  }
]
```

これらの `id` 値を後続の API 操作に使用します。

***

## ユースケース 2: ページネーションを使ってアクティブな実験をフィルタリングする

この例では、フィルタリングとページネーションを組み合わせて、アクティブな実験を管理しやすいバッチで取得する方法を示します。

### ステップ 1: フィルターとページネーションを定義する

アクティブな実験のフィルターを作成し、ページネーションパラメーターを指定します。

**フィルター JSON:**

```json theme={null}
[
  {
    "field": "status",
    "operator": "EQUAL",
    "parameters": ["ACTIVE"]
  }
]
```

**ページネーションパラメーター:**

* `page=1`: 結果の最初のページ
* `perPage=200`: 1 ページあたり最大 200 件

### ステップ 2: リクエストを送信する

`/experiments` エンドポイントに `GET` リクエストを送信します。

**エンドポイント:** `GET https://api.kameleoon.com/experiments`

**リクエスト例:**

```bash theme={null}
curl -L -X GET 'https://api.kameleoon.com/experiments?perPage=200&page=1&filter=%5B%7B%22field%22%3A%22status%22%2C%22operator%22%3A%22EQUAL%22%2C%22parameters%22%3A%5B%22ACTIVE%22%5D%7D%5D' \
-H 'Authorization: Bearer <ACCESS_TOKEN>'
```

### ステップ 3: レスポンスを処理する

API は最大 200 件のアクティブな実験を返します。

```json theme={null}
[
  {
    "id": 12345,
    "siteId": 54321,
    "name": "My Active Experiment",
    "description": "Testing new checkout page",
    "baseURL": "https://yourwebsite.com",
    "type": "AI",
    "trackingTools": [],
    "status": "ACTIVE",
    "dateCreated": "2026-02-03T18:41:00",
    "tags": ["checkout", "mobile"],
    ...
  }
]
```

**追加のページを取得する**には、後続のリクエストで `page` パラメーターをインクリメントします。

***

## ユースケース 3: 複数のフィルターを組み合わせる

より精密にクエリを行うには、複数のフィルター条件を組み合わせます。たとえば、特定のサイト上のアクティブな実験を見つけます。

```json theme={null}
[
  {
    "field": "status",
    "operator": "EQUAL",
    "parameters": ["ACTIVE"]
  },
  {
    "field": "siteId",
    "operator": "EQUAL",
    "parameters": ["xdrio4plsn"]
  }
]
```

**リクエスト例:**

```bash theme={null}
curl -L -X GET 'https://api.kameleoon.com/experiments?filter=%5B%7B%22field%22%3A%22status%22%2C%22operator%22%3A%22EQUAL%22%2C%22parameters%22%3A%5B%22ACTIVE%22%5D%7D%2C%7B%22field%22%3A%22siteId%22%2C%22operator%22%3A%22EQUAL%22%2C%22parameters%22%3A%5B%22xdrio4plsn%22%5D%7D%5D' \
-H 'Authorization: Bearer <ACCESS_TOKEN>'
```

***

## ベストプラクティス

1. **URL エンコーディング**: リクエスト URL に追加する前に、フィルター JSON を URL エンコードしてください。
2. **ページネーション**: `perPage` を使用して結果サイズを制限し、大きなコレクションでのタイムアウトを防ぎます。
3. **複数のフィルター**: フィルター条件を組み合わせて、不要なデータ転送を削減します。
4. **演算子の選択**: 複数の個別リクエストを行うのではなく、複数の値に対応する演算子を使用します。

## 関連リソース

* [Automation API Get Started](/developer-docs/apis/automation-api-rest/get-started/get-started)
* [siteCode の検索方法](/user-manual/faq#how-do-i-find-my-sitecode)