> ## 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.

# はじめに

> Kameleoon Automation API の認証方法と使い方を学びます。

**Automation API** は、REST 準拠のサービスであり、Kameleoon Web インターフェースで利用可能なほとんどの操作をプログラムで実行できるようにします。Automation API を使用して、Kameleoon プラットフォームおよびそのコア機能と連携するカスタムソフトウェアを構築できます。

たとえば、Automation API を使用して以下を行うことができます:

* Kameleoon を Git リポジトリと接続して、バリエーションコードを管理する。
* リアルタイムの実験結果が表示されるカスタムダッシュボードを設計する。
* 複数のプロジェクトにわたってゴールとセグメントの作成を自動化する。

<Warning>
  Kameleoon は、Automation API の新しいバージョンでエンドポイントやパラメータを変更する場合があります。予定されている変更に関する通知を受け取るには、[Kameleoon changelog](https://changelog.kameleoon.com/en/) の更新を購読してください。
</Warning>

<Warning>
  Automation API は大量のリクエストをサポートしません。アカウントまたはユーザーあたり **1 分間に 12 回** までに呼び出しを制限してください。すべての Web サイト訪問者の高頻度トラッキングに Automation API を使用しないでください。リクエスト量がより多い場合は、[Data API](../../data-api-rest/overview) を使用してください。
</Warning>

<Note>
  Automation API の機能拡張をリクエストするには、Kameleoon チームにご連絡ください。皆様のフィードバックをお待ちしており、既存の UI 機能をすばやく API に追加できます。
</Note>

## チュートリアル

### 実験を作成する

このチュートリアルでは、Kameleoon プラットフォームでの主要な操作を行うためのステップバイステップの手順を説明します。以下を学びます:

* [新しい実験を作成する](../tutorials/experiments/create-a-new-experiment)
* [バリエーションに JavaScript コードをプッシュおよび変更する](../tutorials/experiments/add-and-edit-javascript-in-the-variant-of-your-new-experiment)
* [新しいセグメントを作成する](../tutorials/experiments/create-a-segment-to-target-visitors-by-page-url)
* [新しいゴールを作成する](../tutorials/experiments/create-a-new-goal-for-an-experiment)
* [実験を更新して開始する](../tutorials/experiments/add-a-goal-and-segment-to-your-experiment-before-launching)

### 実験結果を取得する

実験を開始すると、最もパフォーマンスの良いバリエーションを判断するためのインサイトを提供する結果が生成されます。結果をリクエストして勝者のバリエーションを特定する方法は [Retrieving Experiments Results](../tutorials/experiments/retrieving-experiment-results-using-the-automation-api) チュートリアルで学べます。

## 認証

Automation API は、認可に OAuth 2.0 フレームワークを使用します。Kameleoon はユースケースに応じて 2 つの主要なフローをサポートします:

* **Client Credentials フロー**: 内部目的で API を使用する Kameleoon の顧客である場合は、このフローを使用します。このフローを使用すると、自身のアカウントと Web プロパティをプログラムで管理できます。
* **Authorization Code フロー**: アプリケーションを Kameleoon と統合する技術パートナーである場合は、このフローを使用します。このフローを使用すると、他の Kameleoon ユーザーに代わってデータに安全にアクセスできます。

### Client Credentials フロー

Client Credentials フローは最もシンプルな認証方法です。このフローを使用するには、クライアント認証情報をアクセストークンと交換します。

<Tip>
  `client_id` と `client_secret` は Kameleoon プラットフォーム上で確認できます。**Account > My profile** に移動し、**See my API credentials** をクリックしてください。
</Tip>

#### 1. アクセストークンを取得する

認証情報を指定して、トークンエンドポイントに POST リクエストを送信します。

```bash curl theme={null}
curl -X POST "https://api.kameleoon.com/oauth/token" \
     -H "Content-Type: application/x-www-form-urlencoded" \
     -d "grant_type=client_credentials" \
     -d "client_id=YOUR_CLIENT_ID" \
     -d "client_secret=YOUR_CLIENT_SECRET"
```

認可サーバーは `access_token` を含む JSON オブジェクトで応答します:

```json theme={null}
{
  "access_token": "eyJhbGciOiJIUzUxMiIsInR5cCI6IkpXVCJ9..."
}
```

#### 2. API にアクセスする

リクエストの `Authorization` HTTP ヘッダーに Bearer トークンとしてアクセストークンを含めます。

```bash curl theme={null}
curl -H "Authorization: Bearer <ACCESS_TOKEN>" \
     -H "Content-Type: application/json" \
     "https://api.kameleoon.com/experiments"
```

* アクセストークンはデフォルトで **2 時間** 有効です。
* Client Credentials フローではリフレッシュトークンは使用しません。
* すべての API リクエストには **HTTPS** を使用する必要があります。プレーンな HTTP で行われたリクエストは失敗します。

### Authorization Code フロー

Authorization Code フローを使用すると、サードパーティの開発者がアプリケーションを Kameleoon のデータと統合できます。ユーザーのアカウントリソースにアクセスするには、ユーザーから明示的な許可を得る必要があります。

<Note>
  OAuth アプリケーションをリクエストするには、Kameleoon のテクニカルアカウントマネージャーにご連絡ください。アプリケーション用のリダイレクト URL を提供する必要があります。Kameleoon は `client_id` と `client_secret` を提供します。
</Note>

#### 1. 認可のためにユーザーをリダイレクトする

アプリケーションからユーザーを認可 URL にリダイレクトします:

```https theme={null}
https://api.kameleoon.com/oauth/authorize?client_id=my-application-name&response_type=code&redirect_uri=https://application.company.com/
```

ユーザーが許可を与えると、Kameleoon は認可コードと共にユーザーをアプリケーション URL にリダイレクトします:

```https theme={null}
https://application.company.com/?code=AUTHORIZATION_CODE
```

#### 2. アクセストークンとリフレッシュトークンを取得する

認可コードをトークンと交換します。`client_id:client_secret` 文字列を Base64 エンコードして、`Authorization: Basic` ヘッダーに含めます。

```bash curl theme={null}
curl -X POST "https://api.kameleoon.com/oauth/token" \
     -H "Content-Type: application/x-www-form-urlencoded" \
     -H "Authorization: Basic <BASE64_ENCODED_CREDENTIALS>" \
     -d "grant_type=authorization_code" \
     -d "code=AUTHORIZATION_CODE" \
     -d "redirect_uri=https://application.company.com/"
```

レスポンスにはアクセストークンとリフレッシュトークンの両方が含まれます:

```json theme={null}
{
  "access_token": "...",
  "refresh_token": "..."
}
```

#### 3. 期限切れのトークンを更新する

ユーザーを再認可せずに新しいアクセストークンを取得するには:

```bash curl theme={null}
curl -X POST "https://api.kameleoon.com/oauth/token" \
     -H "Content-Type: application/x-www-form-urlencoded" \
     -H "Authorization: Basic <BASE64_ENCODED_CREDENTIALS>" \
     -d "grant_type=refresh_token" \
     -d "refresh_token=YOUR_REFRESH_TOKEN"
```

## レート制限

Automation API のレート制限は、ユーザーアクセストークンごとに発生します。Kameleoon は 2 つのレート制限ウィンドウを使用します:

* **10 秒間隔**: 最大 50 リクエスト。
* **1 時間間隔**: 最大 1,000 リクエスト。

これらの制限を超えると、API は `HTTP 429 Too Many Requests` エラーを返します。レート制限を最小限に抑えるには:

* **キャッシュを実装する**: API レスポンスをローカルに保存し、ページロードごとに API を呼び出さないようにします。
* **Data API を使用する**: アプリケーションが大規模なリアルタイムトラッキングを必要とする場合は、[Data API](../../data-api-rest/overview) を使用してください。

## HTTP ステータスコード

| Code | Status            | 説明                                                                |
| :--- | :---------------- | :---------------------------------------------------------------- |
| 200  | OK                | リクエストが成功しました。                                                     |
| 201  | Created           | リソースが正常に作成されました。                                                  |
| 400  | Bad Request       | リクエスト本文が無効です。`Content-Type: application/json` ヘッダーがあることを確認してください。 |
| 401  | Unauthorized      | API トークンが欠落しているか不正な形式です。                                          |
| 403  | Forbidden         | 必要な権限が不足しているか、トークンが取り消されています。                                     |
| 429  | Too Many Requests | レート制限を超えました。                                                      |
| 5xx  | Server Error      | 内部エラーが発生しました。問題が解決しない場合は Kameleoon サポートに連絡してください。                 |

## クエリパラメータ

複数のオブジェクトを取得するエンドポイントでは、データのページネーション、フィルタリング、ソートにクエリパラメータを使用します。

### ページネーション

クエリはデフォルトで **1 ページあたり 20 アイテム** を返します（最大 200）。最大上限を取得するには `perPage=-1` を使用します。

| パラメータ     | 型       | 説明                             |
| :-------- | :------ | :----------------------------- |
| `page`    | integer | 取得するページ番号。                     |
| `perPage` | integer | ページあたりのアイテム数（デフォルト 20、最大 200）。 |
| `filter`  | array   | フィルタリングパラメータ。                  |
| `sort`    | array   | ソートパラメータ。                      |

### フィルタリング

フィルタを URL で送信する際は、パーセントエンコードする必要があります。
**例**: `filter=[{"field":"name","operator":"EQUAL","parameters":["Test"]}]`

| Field        | 型      | 説明                                                                             |
| :----------- | :----- | :----------------------------------------------------------------------------- |
| `field`      | string | フィルタリング対象のフィールド。                                                               |
| `operator`   | enum   | オプションには次が含まれます: `EQUAL`、`NOT_EQUAL`、`LESS`、`GREATER`、`LIKE`、`IN`、`IS_NULL` など。 |
| `parameters` | array  | 一致させる具体的な値。                                                                    |

### ソート

| Field       | 型      | 説明                       |
| :---------- | :----- | :----------------------- |
| `field`     | string | ソート対象のフィールド。             |
| `direction` | enum   | `ASC`（昇順）または `DESC`（降順）。 |