# Live API ガイド

Kollus Live は外部システムとのデータ連携のために RESTful API を提供しています。
このガイドでは、リクエスト仕様と認証方式について説明します。サンプルを参考に開発環境を構成することができます。

## リクエスト仕様

### 呼び出し制限

1分あたり最大60回の呼び出しが可能です。連続呼び出し時は最低1秒以上の間隔を維持してください。

### リクエストヘッダー

HTTP Method に応じて Accept ヘッダーと Content-Type を指定する必要があります。

| HTTP Method | Accept ヘッダー | Content-Type |
|  --- | --- | --- |
| **`GET` / `DELETE`** | `application/json` | - |
| **`POST` / `PUT`** | `application/json` | `application/x-www-form-urlencoded` |


### 認証方式

すべての API リクエストは OAuth2 仕様に準拠しており、リクエストヘッダーに Bearer Token を含める必要があります。

1. Kollus Live コンソールで [設定] > [基本情報] > [サービスアカウント] タブ に移動します。
2. 下部の `[Personal Access Tokens]` セクションで `[Create New Token]` をクリックします。

3. トークン名を入力し、必要な Scopes を選択して `[保存]` をクリックします。

各 API に必要な Scope は API リファレンスの Security 項目で確認できます。

4. 生成されたトークンは、セキュリティ上の理由によりこれ以降は再照会できません。トークンを速やかにコピーし、安全な場所に保存してください。



### リクエスト例

#### チャンネル情報照会

```curl
curl -X GET "https://api-live-jp.kollus.com/api/v1/live/service-accounts/{SERVICE_ACCOUNT_KEY}/channels/{CHANNEL_KEY}/broadcasts?order=id_desc&page=1&per_page=10" -H "accept: application/json" -H "Authorization: Bearer accesstoken...."
```

### サービスアカウントの役割と権限

サービスアカウントに付与された役割に応じて、利用可能な機能とアクセス範囲が異なります。役割ごとの詳細な権限については、サービスアカウントの役割と権限 ドキュメントを参照してください。

### キー(Key)情報

リクエストURLに含まれるキー情報については、認証および主要キー ドキュメントを参照してください。

## サンプル

### チャンネル生成 (POST)

```js
// Implementation using axios

import axios from "axios";

const url =
  "https://api-live-jp.kollus.com/api/v1/live/service-accounts/{SERVICE_ACCOUNT_KEY}/channels";

const body = new URLSearchParams({
  title: "test-channel",
  customer_code: "catenoidtest",
  concurrently_viewer_limit: 100,
  is_shared: 1,
  live_media_profile_group_key: "{ENCODING_PROFILE_KEY}"
});

axios.post(url, body.toString(), {
  headers: {
    Accept: "application/json",
    "Content-Type": "application/x-www-form-urlencoded",
    Authorization: "Bearer {ACCESS_TOKEN}"
  }
})
.then(response => {
  console.log("Channel created successfully:", response.data);
})
.catch(error => {
  console.error(
    "Failed to create channel:",
    error.response?.data || error.message
  );
});
```

### チャンネル内配信照会 (GET)

```js
// Implementation using fetch API

const url = "https://api-live-jp.kollus.com/api"
+ "/v1/live/service-accounts/{SERVICE_ACCOUNT_KEY}/channels/{CHANNEL_KEY}/broadcasts?order=id_desc&page=1&per_page=10";

fetch(url, {
  method: "GET",
  headers: {
    "Accept": "application/json",
    "Authorization": "Bearer {ACCESS_TOKEN}"
  }
})
  .then(response => {
    if (!response.ok) {
      throw new Error(`HTTP error! status: ${response.status}`);
    }
    return response.json();
  })
  .then(data => {
    console.log("Response Data:", data);
  })
  .catch(error => {
    console.error("Request failed:", error);
  });
```