セッション API¶

注意

この API は実験的機能のため、正式版では仕様が変更される可能性があります。

TerminateSession¶

x-sora-target:: Sora_20230628.TerminateSession

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

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

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

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

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

$ 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 と同様です。

$ 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_202312020.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": "[email protected]",
  "version": "2023.2.0",
  "channel_id": "sora",
  "session_id": "JJJ5BFH7QN6DQBTKSS7JA8ZYQR",
  "session_metadata":  {"spam": "egg"},
  "created_time": 1638337454,
  "created_timestamp": "2021-12-01T05:44:14.523736Z",
  "multistream": true,
  "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 項目が含まれなくなります。

{
  "label": "WebRTC SFU Sora",
  "node_name": "[email protected]",
  "version": "2023.2.0",
  "channel_id": "sora",
  "session_id": "JJJ5BFH7QN6DQBTKSS7JA8ZYQR",
  "session_metadata":  {"spam": "egg"},
  "created_time": 1638337454,
  "created_timestamp": "2021-12-01T05:44:14.523736Z",
  "multistream": true,
  "spotlight": false,
  "max_connections": 4,
  "total_connections": 4,
  "external_signaling_url": "wss://node-01.example.com/signaling"
}

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

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

キー	型	内容
recording_id	string	録画機能 (セッション単位) の ID
recording_metadata (オプション)	JSON Value	録画機能 (セッション単位) のメタデータ
expire_time	integer	セッションでの録画期限
expired_at	integer	セッションでの録画期限 (Unix time)
split_only	boolean	セッションでの録画が分割のみかどうか
split_duration (オプション)	integer	セッションでの録画分割有効時の分割時間
start_timestamp	string	セッションでの録画が開始された時刻 (RFC 3339 (UTC))

{
  "label": "WebRTC SFU Sora",
  "node_name": "[email protected]",
  "version": "2023.2.0",
  "channel_id": "sora",
  "session_id": "JJJ5BFH7QN6DQBTKSS7JA8ZYQR",
  "session_metadata":  {"spam": "egg"},
  "created_time": 1638337454,
  "created_timestamp": "2021-12-01T05:44:14.523736Z",
  "multistream": true,
  "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"
  }
}

ListSessions¶

x-sora-target:: Sora_20231220.ListSessions

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

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

$ 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_202312020.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": "[email protected]",
    "version": "2023.2.0",
    "channel_id": "sora",
    "session_id": "JJJ5BFH7QN6DQBTKSS7JA8ZYQR",
    "session_metadata":  {"spam": "egg"},
    "created_time": 1638337454,
    "created_timestamp": "2021-12-01T05:44:14.523736Z",
    "multistream": true,
    "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": "[email protected]",
    "version": "2023.2.0",
    "channel_id": "sora",
    "session_id": "JJJ5BFH7QN6DQBTKSS7JA8ZYQR",
    "session_metadata":  {"spam": "egg"},
    "created_time": 1638337454,
    "created_timestamp": "2021-12-01T05:44:14.523736Z",
    "multistream": true,
    "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"
    }
  }
]

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

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

[
  {
    "label": "WebRTC SFU Sora",
    "node_name": "[email protected]",
    "version": "2023.2.0",
    "channel_id": "sora",
    "session_id": "JJJ5BFH7QN6DQBTKSS7JA8ZYQR",
    "session_metadata":  {"spam": "egg"},
    "created_time": 1638337454,
    "created_timestamp": "2021-12-01T05:44:14.523736Z",
    "multistream": true,
    "spotlight": false,
    "max_connections": 4,
    "total_connections": 4,
    "external_signaling_url": "wss://node-01.example.com/signaling"
  },
  {
    "label": "WebRTC SFU Sora",
    "node_name": "[email protected]",
    "version": "2023.2.0",
    "channel_id": "sora",
    "session_id": "JJJ5BFH7QN6DQBTKSS7JA8ZYQR",
    "session_metadata":  {"spam": "egg"},
    "created_time": 1638337454,
    "created_timestamp": "2021-12-01T05:44:14.523736Z",
    "multistream": true,
    "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"
    }
  }
]