# セッション API


## TerminateSession

**x-sora-target**: Sora_20230628.TerminateSession

指定したセッションを強制的に破棄させる API です。そのセッションに接続しているクライアントはすべて切断します。

この API は非同期のため、リクエストを受け付けた後に即座にレスポンスを返します。
セッション破棄の完了は [session.destroyed](SESSION_WEBHOOK.html#ccb165) で確認してください。

* - キー
  - 型
* - channel_id
  - string
* - session_id (オプション)
  - string

- `channel_id` を指定して、セッションを終了させます
- `session_id` を追加で指定することができますが、 `session_id` が見つからない場合はエラーになります

API 実行中に新規の接続が来た場合、その接続はいったん保留して、セッション破棄後に新規セッションでの接続として扱います。

```console
$ http POST 127.0.0.1:3000/ x-sora-target:Sora_20230628.TerminateSession \
    channel_id=sora \
    session_id=JJJ5BFH7QN6DQBTKSS7JA8ZYQR \
    -vvv

POST / HTTP/1.1
Accept: application/json, */*
Accept-Encoding: gzip, deflate
Connection: keep-alive
Content-Length: 66
Content-Type: application/json
Host: 127.0.0.1:3000
User-Agent: HTTPie/2.6.0
x-sora-target: Sora_20230628.TerminateSession

{
    "channel_id": "sora",
    "session_id": "JJJ5BFH7QN6DQBTKSS7JA8ZYQR"
}


HTTP/1.1 200 OK
content-length: 43
content-type: application/json
date: Tue, 23 May 2023 09:59:06 GMT
server: Cowboy

{
    "session_id": "JJJ5BFH7QN6DQBTKSS7JA8ZYQR"
}
```


## GetSession

**x-sora-target**: Sora_20231220.GetSession

指定したチャネルのセッションを表示する API です。

* - キー
  - 型
* - channel_id
  - string
* - session_id (オプション)
  - string

戻り値の項目はセッションウェブフック `session.updated` と同様です。

```console
$ http POST 127.0.0.1:3000/ x-sora-target:Sora_20231220.GetSession \
    channel_id=sora \
    -vvv
POST / HTTP/1.1
Accept: application/json, */*
Accept-Encoding: gzip, deflate
Connection: keep-alive
Content-Length: 66
Content-Type: application/json
Host: 127.0.0.1:3000
User-Agent: HTTPie/2.6.0
x-sora-target: Sora_20231220.GetSession

{
  "channel_id": "sora"
}


HTTP/1.1 200 OK
content-length: 43
content-type: application/json
date: Tue, 23 May 2023 09:59:06 GMT
server: Cowboy

{
  "label": "WebRTC SFU Sora",
  "node_name": "sora@127.0.0.1",
  "version": "2023.2.0",
  "channel_id": "sora",
  "group_id": "JJJ5BFH7QN6DQBTKSS7JA8ZYQR",
  "session_id": "JJJ5BFH7QN6DQBTKSS7JA8ZYQR",
  "session_metadata":  {"spam": "egg"},
  "created_time": 1638337454,
  "created_timestamp": "2021-12-01T05:44:14.523736Z",
  "spotlight": false,
  "max_connections": 4,
  "total_connections": 4,
  "external_signaling_url": "wss://node-01.example.com/signaling",
  "connections": [
    {
      "audio": true,
      "audio_codec_type": "OPUS",
      "client_id": "W9QE86Z0BS1QFFPZ2QB5DRZ2HC",
      "bundle_id": "W9QE86Z0BS1QFFPZ2QB5DRZ2HC",
      "connection_id": "W9QE86Z0BS1QFFPZ2QB5DRZ2HC",
      "connection_created_timestamp": "2021-12-01T05:44:23.051704Z",
      "connection_destroyed_timestamp": "2021-12-01T05:44:56.878019Z",
      "role": "sendrecv",
      "simulcast": false,
      "video": true,
      "video_bit_rate": 1000,
      "video_codec_type": "VP9",
      "video_vp9_params": { "profile_id": 0 }
    },
    {
      "audio": true,
      "audio_codec_type": "OPUS",
      "client_id": "JXMYW6GPX54EH0HGA5X4130FBM",
      "bundle_id": "JXMYW6GPX54EH0HGA5X4130FBM",
      "connection_id": "JXMYW6GPX54EH0HGA5X4130FBM",
      "connection_created_timestamp": "2021-12-01T05:44:23.051704Z",
      "connection_destroyed_timestamp": "2021-12-01T05:44:56.878019Z",
      "role": "sendrecv",
      "simulcast": false,
      "video": true,
      "video_bit_rate": 1000,
      "video_codec_type": "VP9",
      "video_vp9_params": { "profile_id": 0 }
    },
    {
      "audio": true,
      "audio_codec_type": "OPUS",
      "client_id": "F8VK9R71BN5S5EDE737C8XAA3C",
      "bundle_id": "F8VK9R71BN5S5EDE737C8XAA3C",
      "connection_id": "F8VK9R71BN5S5EDE737C8XAA3C",
      "connection_created_timestamp": "2021-12-01T05:44:23.051704Z",
      "connection_destroyed_timestamp": "2021-12-01T05:44:56.878019Z",
      "role": "sendrecv",
      "simulcast": false,
      "video": true,
      "video_bit_rate": 1000,
      "video_codec_type": "VP9",
      "video_vp9_params": { "profile_id": 0 }
    }
  ]
}
```

### クラスターが有効な場合

`connections` 項目が含まれなくなります。

```javascript
{
  "label": "WebRTC SFU Sora",
  "node_name": "sora@127.0.0.1",
  "version": "2023.2.0",
  "channel_id": "sora",
  "group_id": "JJJ5BFH7QN6DQBTKSS7JA8ZYQR",
  "session_id": "JJJ5BFH7QN6DQBTKSS7JA8ZYQR",
  "session_metadata":  {"spam": "egg"},
  "created_time": 1638337454,
  "created_timestamp": "2021-12-01T05:44:14.523736Z",
  "spotlight": false,
  "max_connections": 4,
  "total_connections": 4,
  "external_signaling_url": "wss://node-01.example.com/signaling"
}
```


### 録画機能 (セッション単位) が有効な場合

`recording` 項目が含まれるようになります。

* - キー
  - 型
  - 内容
* - recording_id
  - string
  - 録画機能 (セッション単位) の ID
* - recording_metadata (オプション)
  - JSONValue
  - 録画機能 (セッション単位) のメタデータ
* - expire_time
  - integer
  - セッションでの録画期限
* - expired_at
  - integer
  - セッションでの録画期限 (Unix time)
* - split_only
  - boolean
  - セッションでの録画が分割のみかどうか
* - split_duration (オプション)
  - integer
  - セッションでの録画分割有効時の分割時間
* - start_timestamp
  - string
  - セッションでの録画が開始された時刻 (RFC 3339 (UTC))
* - format
  - string
  - 録画フォーマット (``"webm"`` または ``"mp4"``)

```javascript
{
  "label": "WebRTC SFU Sora",
  "node_name": "sora@127.0.0.1",
  "version": "2023.2.0",
  "channel_id": "sora",
  "group_id": "JJJ5BFH7QN6DQBTKSS7JA8ZYQR",
  "session_id": "JJJ5BFH7QN6DQBTKSS7JA8ZYQR",
  "session_metadata":  {"spam": "egg"},
  "created_time": 1638337454,
  "created_timestamp": "2021-12-01T05:44:14.523736Z",
  "spotlight": false,
  "max_connections": 4,
  "total_connections": 4,
  "external_signaling_url": "wss://node-01.example.com/signaling",
  "recording": {
    "recording_id": "WHEJ888HQ55KDCFE3TZ4VPFQHR",
    "recording_metadata": {"spam": "egg"},
    "expire_time": 3600,
    "expired_at": 1615527737,
    "split_duration": 3600,
    "split_only": false,
    "start_timestamp": "2021-03-12T04:42:17.455668Z",
    "format": "mp4"
  }
}
```


## ListSessions

**x-sora-target**: Sora_20231220.ListSessions

Sora の全てのセッションを表示する API です。

* - キー
  - 型
* - group_id (オプション)
  - string

`group_id` を指定すると、セッションウェブフック [session.created](SESSION_WEBHOOK.html#1d1984) で払い出した `group_id` に一致するセッションのみを表示します。

- 録画機能 (セッション単位) が有効な場合は `"recording"` 項目が追加されます

```console
$ http POST 127.0.0.1:3000/ x-sora-target:Sora_20231220.ListSessions \
    -vvv
POST / HTTP/1.1
Accept: application/json, */*
Accept-Encoding: gzip, deflate
Connection: keep-alive
Content-Length: 66
Content-Type: application/json
Host: 127.0.0.1:3000
User-Agent: HTTPie/2.6.0
x-sora-target: Sora_20231220.ListSessions


HTTP/1.1 200 OK
content-length: 43
content-type: application/json
date: Tue, 23 May 2023 09:59:06 GMT
server: Cowboy

[
  {
    "label": "WebRTC SFU Sora",
    "node_name": "sora@127.0.0.1",
    "version": "2023.2.0",
    "channel_id": "sora",
    "group_id": "JJJ5BFH7QN6DQBTKSS7JA8ZYQR",
    "session_id": "JJJ5BFH7QN6DQBTKSS7JA8ZYQR",
    "session_metadata":  {"spam": "egg"},
    "created_time": 1638337454,
    "created_timestamp": "2021-12-01T05:44:14.523736Z",
    "spotlight": false,
    "max_connections": 4,
    "total_connections": 4,
    "connections": [
      {
        "audio": true,
        "audio_codec_type": "OPUS",
        "client_id": "W9QE86Z0BS1QFFPZ2QB5DRZ2HC",
        "bundle_id": "W9QE86Z0BS1QFFPZ2QB5DRZ2HC",
        "connection_id": "W9QE86Z0BS1QFFPZ2QB5DRZ2HC",
        "connection_created_timestamp": "2021-12-01T05:44:23.051704Z",
        "connection_destroyed_timestamp": "2021-12-01T05:44:56.878019Z",
        "role": "sendrecv",
        "simulcast": false,
        "video": true,
        "video_bit_rate": 1000,
        "video_codec_type": "VP9",
        "video_vp9_params": { "profile_id": 0 }
      },
      {
        "audio": true,
        "audio_codec_type": "OPUS",
        "client_id": "JXMYW6GPX54EH0HGA5X4130FBM",
        "bundle_id": "JXMYW6GPX54EH0HGA5X4130FBM",
        "connection_id": "JXMYW6GPX54EH0HGA5X4130FBM",
        "connection_created_timestamp": "2021-12-01T05:44:23.051704Z",
        "connection_destroyed_timestamp": "2021-12-01T05:44:56.878019Z",
        "role": "sendrecv",
        "simulcast": false,
        "video": true,
        "video_bit_rate": 1000,
        "video_codec_type": "VP9",
        "video_vp9_params": { "profile_id": 0 }
      },
      {
        "audio": true,
        "audio_codec_type": "OPUS",
        "client_id": "F8VK9R71BN5S5EDE737C8XAA3C",
        "bundle_id": "F8VK9R71BN5S5EDE737C8XAA3C",
        "connection_id": "F8VK9R71BN5S5EDE737C8XAA3C",
        "connection_created_timestamp": "2021-12-01T05:44:23.051704Z",
        "connection_destroyed_timestamp": "2021-12-01T05:44:56.878019Z",
        "role": "sendrecv",
        "simulcast": false,
        "video": true,
        "video_bit_rate": 1000,
        "video_codec_type": "VP9",
        "video_vp9_params": { "profile_id": 0 }
      }
    ]
  },
  {
    "label": "WebRTC SFU Sora",
    "node_name": "sora@127.0.0.1",
    "version": "2023.2.0",
    "channel_id": "sora",
    "group_id": "JJJ5BFH7QN6DQBTKSS7JA8ZYQR",
    "session_id": "JJJ5BFH7QN6DQBTKSS7JA8ZYQR",
    "session_metadata":  {"spam": "egg"},
    "created_time": 1638337454,
    "created_timestamp": "2021-12-01T05:44:14.523736Z",
    "spotlight": false,
    "max_connections": 4,
    "total_connections": 4,
    "connections": [
      {
        "audio": true,
        "audio_codec_type": "OPUS",
        "client_id": "W9QE86Z0BS1QFFPZ2QB5DRZ2HC",
        "bundle_id": "W9QE86Z0BS1QFFPZ2QB5DRZ2HC",
        "connection_id": "W9QE86Z0BS1QFFPZ2QB5DRZ2HC",
        "connection_created_timestamp": "2021-12-01T05:44:23.051704Z",
        "connection_destroyed_timestamp": "2021-12-01T05:44:56.878019Z",
        "role": "sendrecv",
        "simulcast": false,
        "video": true,
        "video_bit_rate": 1000,
        "video_codec_type": "VP9",
        "video_vp9_params": { "profile_id": 0 }
      },
      {
        "audio": true,
        "audio_codec_type": "OPUS",
        "client_id": "JXMYW6GPX54EH0HGA5X4130FBM",
        "bundle_id": "JXMYW6GPX54EH0HGA5X4130FBM",
        "connection_id": "JXMYW6GPX54EH0HGA5X4130FBM",
        "connection_created_timestamp": "2021-12-01T05:44:23.051704Z",
        "connection_destroyed_timestamp": "2021-12-01T05:44:56.878019Z",
        "role": "sendrecv",
        "simulcast": false,
        "video": true,
        "video_bit_rate": 1000,
        "video_codec_type": "VP9",
        "video_vp9_params": { "profile_id": 0 }
      }
    ],
    "recording": {
      "recording_id": "WHEJ888HQ55KDCFE3TZ4VPFQHR",
      "recording_metadata": {"spam": "egg"},
      "expire_time": 3600,
      "expired_at": 1615527737,
      "split_duration": 3600,
      "split_only": false,
      "start_timestamp": "2021-03-12T04:42:17.455668Z",
      "format": "webm"
    }
  }
]
```

### クラスターが有効な場合

`connections` 項目が含まれなくなります。

```javascript
[
  {
    "label": "WebRTC SFU Sora",
    "node_name": "sora@127.0.0.1",
    "version": "2023.2.0",
    "channel_id": "sora",
    "group_id": "JJJ5BFH7QN6DQBTKSS7JA8ZYQR",
    "session_id": "JJJ5BFH7QN6DQBTKSS7JA8ZYQR",
    "session_metadata":  {"spam": "egg"},
    "created_time": 1638337454,
    "created_timestamp": "2021-12-01T05:44:14.523736Z",
    "spotlight": false,
    "max_connections": 4,
    "total_connections": 4,
    "external_signaling_url": "wss://node-01.example.com/signaling"
  },
  {
    "label": "WebRTC SFU Sora",
    "node_name": "sora@127.0.0.1",
    "version": "2023.2.0",
    "channel_id": "sora",
    "group_id": "JJJ5BFH7QN6DQBTKSS7JA8ZYQR",
    "session_id": "JJJ5BFH7QN6DQBTKSS7JA8ZYQR",
    "session_metadata":  {"spam": "egg"},
    "created_time": 1638337454,
    "created_timestamp": "2021-12-01T05:44:14.523736Z",
    "spotlight": false,
    "max_connections": 4,
    "total_connections": 4,
    "external_signaling_url": "wss://node-01.example.com/signaling",
    "recording": {
      "recording_id": "WHEJ888HQ55KDCFE3TZ4VPFQHR",
      "recording_metadata": {"spam": "egg"},
      "expire_time": 3600,
      "expired_at": 1615527737,
      "split_duration": 3600,
      "split_only": false,
      "start_timestamp": "2021-03-12T04:42:17.455668Z",
      "format": "webm"
    }
  }
]
```