セッションウェブフック¶
概要¶
セッションウェブフックは、セッションの状態を送信するウェブフックです。
例えばチャネルに誰も接続していない状態で新しく接続されたタイミングや、 誰も接続しない状態が一定時間続いたタイミングで、 ウェブフックを利用してセッションの状態などを HTTP リクエストで送信する機能です。
また、セッション開始時にウェブフックの戻り値で録画開始や音声ストリーミングなどを指定することができ、 今まで API を叩いていた処理をウェブフックで行うことができるようになります。
目的¶
セッションは実際にチャネルに参加しているクライアントの集まりです。
もともと Sora にはチャネルを作るという概念がありません。 チャネルに誰も接続していない状態で、新しく接続があれば、チャネルが利用されている状態になります。
そのため、チャネルが利用されているかどうかの判断は HTTP API を利用したり、 イベントウェブフックリクエストの送信を利用したりして、アプリケーション側で判断する必要がありました。
このセッションウェブフックは、新しくチャネルに状態を持たせ、 その状態をウェブフックリクエストで送信することで、API やイベントウェブフックを利用せずに、 チャネルの状態を判断することができるようになります。
セッション ID¶
特定の期間チャネルに接続していたクライアントをグルーピングするために、 Sora はセッション ID という値を払い出します。 セッション ID は Sora が指定するため、書き換えることはできません。
セッション ID は UUIDv4 を Base32 でエンコードした 26 バイトの文字列です。
設定¶
session_webhook_url¶
セッションウェブフックリクエストの送信先を指定してください。
session_webhook_url = https://example.com/sora/session/webhook
session_created_timeout¶
セッションが存在しない状態で、新しくセッションを生成する際の制限時間です。 これはセッションウェブフック処理も含めた時間で、この時間を超えるとタイムアウトとなり、切断されます。
デフォルトでは 5 秒です。
session_created_timeout = 5 s
session_destroyed_timeout¶
そのチャネルの接続数が 0 になってから新しい接続が無い場合に、 session.destroyed
のセッションウェブフックリクエストを送信するまでの時間を指定します。
デフォルトでは 15 秒です。
session_destroyed_timeout = 15 s
session_updated_webhook_interval¶
session.updated
の送信間隔を指定します。
デフォルトでは 1 min
(1 分) です。単位は min
しか指定できません。
session_updated_webhook_interval = 1 min
ログ¶
セッションウェブフックのログは log/session_webhook.jsonl
と log/session_webhook_error.jsonl
に出力されます。
これは session_webhook_url を指定していなくても出力されます。
session_webhook.jsonl¶
セッションウェブフックの送信が 正常に動作した 処理を書き込みます。
項目¶
id
Base32 UUIDv4
timestamp
RFC 3339 UTC マイクロ秒
req
リクエスト
センシティブデータはマスクされます
res
レスポンス
センシティブデータはマスクされます
url
セッションウェブフック URL
セッションウェブフックが指定されていなければ含まれません
session_webhook_error.jsonl¶
セッションウェブフックの送信が正常に処理できなかった処理を書き込みます。
ステータスコードが 200 番台以外の場合
タイムアウトした場合
項目¶
id
Base32 UUIDv4
timestamp
RFC 3339 UTC マイクロ秒
req
リクエスト
センシティブデータはマスクされません
reason
ウェブフックエラー理由
url
セッションウェブフック URL
セッションウェブフックが指定されていなければ含まれません
multistream
と spotlight
が既存セッションと異なる場合の挙動¶
重要
この挙動は 2024 年 12 月リリースの Sora にて変更されます。
既存セッションの接続数が 0 の場合に multistream
と spotlight
が異なる新規接続が来た場合は、
INVALID-SIGNALING-PARAMS
エラーを返し切断するようになります。
警告
この挙動はクラスターリレー機能を利用する際は適用されません。
既存セッションの接続数が 0 の場合に multistream
と spotlight
が異なる新規接続が来た場合は、
INVALID-SIGNALING-PARAMS
エラーを返し切断するようになります。
セッションが存在するタイミングでシグナリングのパラメーターが異なる接続が来た場合、接続数によって挙動が変わります。
既存セッションの接続数が 0 の場合¶
セッションの接続数が 0 のタイミングで multistream
と spotlight
がセッションと異なる新規接続が来た場合は、既存のセッションを破棄し session.destroyed
ウェブフックリクエストを送信します。
その後に、新規でセッションを作成し session.created
ウェブフックリクエストを送信します。
既存セッションの接続数が 0 ではない場合¶
セッションの接続数が 0 ではないタイミングで multistream
と spotlight
がセッションと異なる新規接続が来た場合は、 INVALID-SIGNALING-PARAMS
エラーを返し切断します。
session.created¶
セッション生成
同時接続数が 0 のチャネル ID に対して、新しい接続の認証が成功したタイミングで session.created
ウェブフックリクエストを送信します。
チャネルの同時接続数が 0 の場合でも、 multistream
および spotlight
の値が一致するセッションが過去に生成されており、
まだ破棄されていない場合には、そのセッションが使用されるため session.created
ウェブフックは送信されません。
キー |
型 |
内容 |
---|---|---|
type |
string |
"session.created" |
id |
string |
ウェブフック ID (ユニーク) |
label |
string |
sora.conf の label にて指定した値 |
node_name |
string |
Sora ノード名 |
version |
string |
Sora のバージョン |
channel_id |
string |
チャネル ID |
session_id |
string |
セッション ID |
timestamp |
string (RFC3339 UTC マイクロ秒) |
ウェブフック作成時間 |
created_time |
integer (UNIX 時間) |
セッション生成時間 |
created_timestamp |
string (RFC3339 UTC マイクロ秒) |
セッション生成時間 |
multistream |
boolean |
マルチストリームが有効かどうか |
spotlight |
boolean |
スポットライトが有効かどうか |
external_signaling_url |
string |
(クラスター機能が有効の場合) 接続先の external_signaling_url |
{
"channel_id": "sora",
"created_time": 1638337454,
"created_timestamp": "2021-12-01T05:44:14.523736Z",
"id": "2YN2DQE5KD3GSFSVPAYZ7VTAV4",
"label": "WebRTC SFU Sora",
"multistream": true,
"spotlight": false,
"node_name": "[email protected]",
"session_id": "NPR769YPQ914K10FW42PGH4TKW",
"timestamp": "2021-12-01T05:44:14.523912Z",
"external_signaling_url": "wss://node-01.example.com/signaling",
"type": "session.created",
"version": "2023.2.0"
}
戻り値¶
セッションウェブフックは "type": "session.created"
の戻り値を指定できます。
session_metadata¶
注釈
この項目はセンシティブデータとして扱われます。
session_metadata
を指定した場合、セッション更新時の session.updated
とセッション破棄時の "type": "session.destroyed"
のウェブフックリクエストに session_metadata
が含まれます。
{
"session_metadata": "<JSON>"
}
session_lifetime¶
セッション生成のタイミングで、セッションのライフタイムを指定することができます。
例えば 3600
を指定した場合、 3600 秒後にセッションは破棄されます
{
"session_lifetime": 3600
}
session_lifetime
の指定にかかわらず、セッションの同時接続数が 0 になると、 session_destroyed_timeout に指定した時間が経過したタイミングでセッションが破棄されます秒 で指定してください
最大 2,592,000 秒 (30 日) まで指定できます
セッション生成後に変更することはできません
session_lifetime
が未指定の場合は 無制限 ですsession.destroyed
のreason
にlifetime_expired
が入りますconnection.destroyed
のreason
にsession_destroyed
が入りますセッションのライフタイムが終了すると、セッションが破棄され切断します
セッションのライフタイムが終了すると、セッションウェブフック
session.destroyed
が送信されます
spotlight_number¶
セッション生成のタイミングで、スポットライト機能が有効な場合に、スポットライトの数を指定することができます。
クライアント単位でのシグナリング接続時や認証ウェブフック成功時の spotlight_number
と異なる値を払い出した場合、
エラーとなりますので注意してください。 spotlight_number
はセッションウェブフックでの指定を推奨します。
セッション単位の spotlight_number
を変更するには ChangeSpotlightNumber API を利用する必要があります。
{
"spotlight_number": 3
}
recording¶
recording
を true
を指定した場合、セッション単位の録画を開始します。
詳細は 録画機能 (セッション単位) の session.created をご確認ください。
{
"recording": true
}
recording_expire_time¶
recording
がtrue
の場合のみ有効です。録画の有効期限を秒単位で指定しますrecording_expire_time
を3600
を指定した場合、 3600 秒後に録画は終了します
詳細は 録画機能 (セッション単位) の session.created をご確認ください。
{
"recording_expire_time": 3600
}
recording_split_only¶
recording
がtrue
の場合のみ有効です。録画を分割のみで行うかどうかを指定しますrecording_split_only
をtrue
に指定した場合、録画は分割のみで行われます
詳細は 録画機能 (セッション単位) の session.created をご確認ください。
{
"recording_split_only": true
}
recording_split_duration¶
recording
がtrue
の場合のみ有効です。分割録画の分割時間を秒単位で指定しますrecording_split_duration
を60
を指定した場合、 60 秒ごとに録画が分割されます
詳細は 録画機能 (セッション単位) の session.created をご確認ください。
{
"recording_split_duration": 60
}
recording_metadata¶
recording
が true
の場合のみ有効です。recording.report ウェブフックやレポートファイルに含まれます。
詳細は 録画機能 (セッション単位) の session.created をご確認ください。
{
"recording_metadata": {"spam": "egg"}
}
forwarding_filter¶
forwarding_filter
を指定した場合、転送フィルターをセッションに対して反映することができます。
転送フィルタールールの詳細については 転送フィルター機能 をご確認ください。
{
"forwarding_filter": {
"action": "allow",
"rules": [
// チャネルに接続しているすべてのコネクションに音声のみ転送する
[
{"field": "kind", "operator": "is_in", "values": ["audio"]}
]
]
}
}
audio_streaming¶
audio_streaming
を true
に指定した場合、そのセッションで音声ストリーミングが有効になります。
音声ストリーミング機能の詳細については 音声ストリーミング機能 をご確認ください。
{
"audio_streaming": true
}
audio_streaming_auto¶
audio_streaming_auto
を true
に指定した場合、そのセッションで音声ストリーミングが有効になり、
かつ自動開始、自動停止機能が有効になります。
この設定を true
にするときには audio_streaming
も true
に設定する必要があります。
詳細は audio_streaming 関連の払い出し設定の組み合わせによる動作 をご確認ください。
{
"audio_streaming": true,
"audio_streaming_auto": true
}
session.destroyed¶
セッション破棄
同時接続数が 0 になったチャネル ID が一定時間経過したタイミングで、 session.destroyed
ウェブフックリクエストを送信します。
キー |
型 |
内容 |
---|---|---|
type |
string |
"session.destroyed" |
id |
string |
ウェブフック ID (ユニーク) |
label |
string |
sora.conf の label にて指定した値 |
node_name |
string |
Sora ノード名 |
version |
string |
Sora のバージョン |
channel_id |
string |
チャネル ID |
session_id |
string |
セッション ID |
timestamp |
string (RFC3339 UTC マイクロ秒) |
ウェブフック作成時間 |
created_time |
integer (UNIX 時間) |
セッション生成時間 |
created_timestamp |
string (RFC3339 UTC マイクロ秒) |
セッション生成時間 |
destroyed_time |
integer (UNIX 時間) |
セッション破棄時間 |
destroyed_timestamp |
string (RFC3339 UTC マイクロ秒) |
セッション破棄時間 |
multistream |
boolean |
マルチストリームが有効かどうか |
spotlight |
boolean |
スポットライトが有効かどうか |
spotlight_number |
integer |
スポットライトが有効な場合、スポットライト数 |
total_connections |
integer |
延べ接続数 |
max_connections |
integer |
最大同時接続数 |
connections |
array (object) |
(クラスター機能が無効の場合) セッションに参加した接続情報 |
session_metadata |
json |
(値がある場合) session.created の戻り値で指定した値 |
external_signaling_url |
string |
(クラスター機能が有効の場合) 接続先の external_signaling_url |
reason |
string |
セッションが破棄された理由 ("normal", "validation_error", "webhook_error", "terminated_api", "lifetime_expired", "abort") |
{
"channel_id": "sora",
"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:57.083215Z",
"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:21.500272Z",
"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:19.811385Z",
"connection_destroyed_timestamp": "2021-12-01T05:44:55.897819Z",
"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": "VBYS5TV5S510F98GS2VK015AKG",
"bundle_id": "VBYS5TV5S510F98GS2VK015AKG",
"connection_id": "VBYS5TV5S510F98GS2VK015AKG",
"connection_created_timestamp": "2021-12-01T05:44:14.716974Z",
"connection_destroyed_timestamp": "2021-12-01T05:44:57.197372Z",
"role": "sendrecv",
"simulcast": false,
"video": true,
"video_bit_rate": 1000,
"video_codec_type": "VP9",
"video_vp9_params": { "profile_id": 0 },
}
],
"created_time": 1638337454,
"created_timestamp": "2021-12-01T05:44:14.523736Z",
"destroyed_time": 1638337502,
"destroyed_timestamp": "2021-12-01T05:45:02.199179Z",
"id": "M7K1AVS9KS34V9XFJJH04TB400",
"label": "WebRTC SFU Sora",
"max_connections": 4,
"multistream": true,
"node_name": "[email protected]",
"session_id": "NPR769YPQ914K10FW42PGH4TKW",
"spotlight": false,
"timestamp": "2021-12-01T05:45:02.199419Z",
"total_connections": 4,
"session_metadata": {"spam": "egg"},
"type": "session.destroyed",
"version": "2023.2.0"
}
connections¶
connections に入ってくる以下の二つは RFC3339 形式の時間ではなく null
が入ってくる場合があります。
connection_created_timestamp
connection_destroyed_timestamp
これは、認証は成功し、セッションに参加はしたが、何らかの理由で WebRTC が確立に失敗した場合発生します。
両方ともの値に null が入ってきます。
reason¶
session.destroyed には reason が含まれ、セッションが破棄された理由が入ります。
"normal"
は通常のセッション破棄"validation_error"
は session.created の戻り値が正常ではなかったことによるエラーによるセッション破棄このセッション破棄は session_created_response_validate_warning_as_error が
true
の場合のみ発生します
"webhook_error"
はセッション生成時のウェブフック session.created のウェブフック処理中にエラーが発生したことによるセッション破棄以下はエラー例です
session_webhook_url と接続できなかった場合
ウェブフック送信先からステータスコードが 2XX 以外だった場合
ウェブフック送信先からの JSON がパースできなかった場合
ウェブフック送信先からの JSON のパース結果が JSON Object 以外だった場合
ウェブフック送信先との HTTPS に失敗した場合
ウェブフック送信先との mTLS に失敗した場合
"terminated_api"
は TerminateSession API によるセッション破棄"lifetime_expired"
はセッションライフタイムの期限切れによるセッション破棄"abort"
は異常発生のセッション破棄
クラスター有効時¶
クラスター有効時には connections
項目は含まれません。
{
"channel_id": "sora",
"created_time": 1638337454,
"created_timestamp": "2021-12-01T05:44:14.523736Z",
"destroyed_time": 1638337502,
"destroyed_timestamp": "2021-12-01T05:45:02.199179Z",
"id": "M7K1AVS9KS34V9XFJJH04TB400",
"label": "WebRTC SFU Sora",
"max_connections": 4,
"multistream": true,
"node_name": "[email protected]",
"session_id": "NPR769YPQ914K10FW42PGH4TKW",
"spotlight": false,
"timestamp": "2021-12-01T05:45:02.199419Z",
"reason": "normal",
"total_connections": 4,
"session_metadata": {"spam": "egg"},
"external_signaling_url": "wss://node-01.example.com/signaling",
"type": "session.destroyed",
"version": "2023.2.0"
}
session.updated¶
セッション更新
注釈
このウェブフックリクエストの送信を停止することができます。
sora.conf
の ignore_session_updated_webhook を true
にしてください。
session.created
送信後、一定間隔で session.updated
ウェブフックリクエストを送信します。
送信間隔はデフォルトで 1 分です。 session_updated_webhook_interval で送信間隔を変更できます。
session.updated
の状態を記録することで、もし何らかの理由で session.destroyed
が送信されなかった場合でも、
そのセッションが存在しているかどうかの判断を行う事ができるようになります。
キー |
型 |
内容 |
---|---|---|
type |
string |
"session.updated" |
id |
string |
ウェブフック ID (ユニーク) |
label |
string |
sora.conf の label にて指定した値 |
node_name |
string |
Sora ノード名 |
version |
string |
Sora のバージョン |
channel_id |
string |
チャネル ID |
session_id |
string |
セッション ID |
timestamp |
string (RFC3339 UTC マイクロ秒) |
ウェブフック作成時間 |
created_time |
integer (UNIX 時間) |
セッション生成時間 |
created_timestamp |
string (RFC3339 UTC マイクロ秒) |
セッション生成時間 |
multistream |
boolean |
マルチストリームが有効かどうか |
spotlight |
boolean |
スポットライトが有効かどうか |
spotlight_number |
integer |
スポットライトが有効な場合、スポットライト数 |
total_connections |
integer |
延べ接続数 |
max_connections |
integer |
最大同時接続数 |
connections |
array (object) |
(クラスター機能が有効の場合) セッションに参加した接続情報 |
session_metadata |
json |
(値がある場合) session.created の戻り値で指定した値 |
external_signaling_url |
string |
(クラスター機能が有効の場合) 接続先の external_signaling_url |
{
"channel_id": "sora",
"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:57.083215Z",
"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:21.500272Z",
"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:19.811385Z",
"connection_destroyed_timestamp": "2021-12-01T05:44:55.897819Z",
"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": "VBYS5TV5S510F98GS2VK015AKG",
"bundle_id": "VBYS5TV5S510F98GS2VK015AKG",
"connection_id": "VBYS5TV5S510F98GS2VK015AKG",
"connection_created_timestamp": "2021-12-01T05:44:14.716974Z",
"connection_destroyed_timestamp": "2021-12-01T05:44:57.197372Z",
"role": "sendrecv",
"simulcast": false,
"video": true,
"video_bit_rate": 1000,
"video_codec_type": "VP9",
"video_vp9_params": { "profile_id": 0 },
}
],
"created_time": 1638337454,
"created_timestamp": "2021-12-01T05:44:14.523736Z",
"id": "M7K1AVS9KS34V9XFJJH04TB400",
"label": "WebRTC SFU Sora",
"max_connections": 4,
"multistream": true,
"node_name": "[email protected]",
"session_id": "NPR769YPQ914K10FW42PGH4TKW",
"spotlight": false,
"timestamp": "2021-12-01T05:45:02.199419Z",
"total_connections": 4,
"session_metadata": {"spam": "egg"},
"external_signaling_url": "wss://node-01.example.com/signaling",
"type": "session.updated",
"version": "2023.2.0"
}
connections¶
connections に入ってくる以下の二つは RFC3339 形式の時間ではなく null
が入ってくる場合があります。
connection_created_timestamp
connection_destroyed_timestamp
これは、認証は成功し、セッションに参加はしたが、何らかの理由で WebRTC が確立に失敗した場合発生します。
両方ともの値に null が入ってきます。
クラスター有効時¶
クラスター有効時には connections
項目は含まれません。
{
"channel_id": "sora",
"created_time": 1638337454,
"created_timestamp": "2021-12-01T05:44:14.523736Z",
"id": "M7K1AVS9KS34V9XFJJH04TB400",
"label": "WebRTC SFU Sora",
"max_connections": 4,
"multistream": true,
"node_name": "[email protected]",
"session_id": "NPR769YPQ914K10FW42PGH4TKW",
"spotlight": false,
"timestamp": "2021-12-01T05:45:02.199419Z",
"total_connections": 4,
"session_metadata": {"spam": "egg"},
"external_signaling_url": "wss://node-01.example.com/signaling",
"type": "session.updated",
"version": "2023.2.0"
}
録画機能 (セッション単位) 有効時¶
セッションで録画機能 (セッション単位) が有効な場合、 "recording"
が含まれます。
録画が有効ではない場合は "recording"
項目は含まれません。
キー |
型 |
内容 |
---|---|---|
recording_id |
string |
録画機能 (セッション単位) の ID |
recording_metadata (オプション) |
JSON Value |
録画機能 (セッション単位) のメタデータ |
split_only |
boolean |
セッションでの録画が分割のみかどうか |
expire_time (オプション) |
integer |
セッションでの録画期限 |
expired_at (オプション) |
integer |
セッションでの録画期限 (Unix time) |
split_duration (オプション) |
integer |
セッションでの録画分割有効時の分割時間 |
start_timestamp |
string |
セッションでの録画が開始された時刻 (RFC 3339 (UTC)) |
{
"channel_id": "sora",
"created_time": 1638337454,
"created_timestamp": "2021-12-01T05:44:14.523736Z",
"id": "M7K1AVS9KS34V9XFJJH04TB400",
"label": "WebRTC SFU Sora",
"max_connections": 4,
"multistream": true,
"node_name": "[email protected]",
"session_id": "NPR769YPQ914K10FW42PGH4TKW",
"spotlight": false,
"timestamp": "2021-12-01T05:45:02.199419Z",
"total_connections": 4,
"session_metadata": {"spam": "egg"},
"external_signaling_url": "wss://node-01.example.com/signaling",
"type": "session.destroyed",
"version": "2023.2.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"
}
}
session.vanished¶
注意
セッションウェブフック session.vanished
利用する場合は事前にサポートまでご連絡ください
警告
セッションウェブフック session.vanished
は 実験的機能 のため、正式版では仕様が変更される可能性があります
重要
このウェブフックリクエストが送信されるには
sora.conf
の ignore_session_vanished_webhook が false
である必要があります。
Sora のモードが block_new_session
または block_new_connection
の時に、
すべてのセッションがなくなったタイミングでウェブフックリクエストを送信します。
{
"id": "047MK20PWD14QBPBA2JAK585JM",
"label": "WebRTC SFU Sora",
"node_name": "[email protected]",
"timestamp": "2021-10-05T01:51:57.977800Z",
"type": "session.vanished",
"version": "2023.2.0"
}
recording.started¶
重要
このウェブフックリクエストが送信されるにはセッションベースの録画を利用する必要があります
録画開始
data.start_timestamp
録画機能 (セッション単位) を開始したタイムスタンプ (RFC3339 UTC マイクロ秒) が入ります
data.expire_time
この項目はオプションです
API による開始を行った場合は StartRecording API で指定した
expire_time
が入りますsession.created ウェブフックリクエストの戻り値により録画を開始した場合は戻り値
recording_expire_time
が入ります指定していない場合は
expire_time
の項目が入ってきません
data.expired_at
この項目はオプションです
API による開始を行った場合は StartRecording API で指定した
expire_time
から計算した有効期限 (UNIX Time) が入りますsession.created ウェブフックリクエストの戻り値により録画を開始した場合は戻り値
recording_expire_time
から計算した有効期限 (UNIX Time) が入りますexpire_time
を指定していない場合はexpired_at
の項目が入ってきません
data.split_duration
この項目はオプションです
API による開始を行った場合は StartRecording API で指定した
split_duration
が入りますsession.created ウェブフックリクエストの戻り値により録画を開始した場合は戻り値
recording_split_duration
が入ります指定していない場合は
split_duration
の項目が入ってきません
data.split_only
API による開始を行った場合は StartRecording API で指定した
split_only
が入りますsession.created ウェブフックリクエストの戻り値により録画を開始した場合は戻り値
recording_split_only
が入ります指定していない場合は
false
が入ります
data.recording_metadata
この項目はオプションです
API による開始を行った場合は StartRecording API で指定した
metadata
が入りますsession.created ウェブフックリクエストの戻り値により録画を開始した場合は戻り値
recording_metadata
が入ります指定していない場合は
recording_metadata
の項目が入ってきません
{
"type": "recording.started",
"id": "<Base32-UUIDv4>",
"version": "<String>",
"label": "<String>",
"node_name": "<String>",
"channel_id": "<String>",
"session_id": "<Base32-UUIDv4>",
"session_metadata": "<JSON>",
"timestamp": "<UTC RFC3339 Timestamp>",
"data": {
"channel_id": "<String>",
"recording_id": "<Base32-UUIDv4>",
"recording_metadata": "<JSON-Object>",
"split_only": "<Boolean>",
"created_at": "<UNIX-Time>",
"expire_time": "<Integer>",
"expired_at": "<UNIX-Time>",
"start_timestamp": "<UTC RFC3339 Timestamp>",
"split_duration": "<Integer>"
}
}
recording.report¶
重要
このウェブフックリクエストが送信するには、セッションベースの録画を利用する必要があります
注釈
セッションが破棄されたタイミングでの recording.report
は session.destroyed
の 後 に送信されます。
録画結果報告
data.archives[].start_time_offset
録画を開始してから何秒経過した後にこの録画が開始したかを表しています
data.archives[].stop_time_offset
録画を開始してから何秒経過した後にこの録画が終了したかを表しています
data.recording_metadata
StartRecording API で指定した metadata 、または
session.created
で払い出したrecording_metadata
が入ります指定していない場合は
recording_metadata
の項目が入ってきません
data.expired_at
期限が切れた日時を UNIX Time で返します
一括録画時 recording.report¶
{
"type": "recording.report",
"id": "<Base32-UUIDv4>",
"version": "<String>",
"label": "<String>",
"node_name": "<String>",
"channel_id": "<String>",
"session_id": "<String",
"session_metadata": "<JSON>",
"timestamp": "<UTC RFC3339 Timestamp>",
"data": {
"channel_id": "<String>",
"session_id": "<String>",
"recording_id": "<Base32-UUIDv4>",
"recording_metadata": "<JSON-Object>",
"split_only": "<Boolean>",
"split_duration": "<Integer>",
"created_at": "<UNIX-Time>",
"expire_time": "<Integer>",
"expired_at": "<UNIX-Time>",
"file_path": "<String>",
"filename": "<String>",
"file_written": "<Boolean>",
"start_timestamp": "<UTC RFC3339 Timestamp>",
"stop_timestamp": "<UTC RFC3339 Timestamp>",
"archives": [
{
"label": "<String>",
"node_name": "<String>",
"client_id": "<String | Base32-UUIDv4>",
"bundle_id": "<String | Base32-UUIDv4>",
"connection_id": "<Base32-UUIDv4>",
"file_path": "<String>",
"filename": "<String>",
"metadata_file_path": "<String>",
"metadata_filename": "<String>",
"start_time_offset": "<Integer>",
"start_timestamp": "<UTC RFC3339 Timestamp>",
"stop_time_offset": "<Integer>",
"stop_timestamp": "<UTC RFC3339 Timestamp>",
"size": "<Integer>"
},
{
"label": "<String>",
"node_name": "<String>",
"client_id": "<String | Base32-UUIDv4>",
"bundle_id": "<String | Base32-UUIDv4>",
"connection_id": "<Base32-UUIDv4>",
"file_path": "<String>",
"filename": "<String>",
"metadata_file_path": "<String>",
"metadata_filename": "<String>",
"start_time_offset": "<Integer>",
"start_timestamp": "<UTC RFC3339 Timestamp>",
"stop_time_offset": "<Integer>",
"stop_timestamp": "<UTC RFC3339 Timestamp>",
"size": "<Integer>"
}
],
"failed_archives": [
{
"label": "<String>",
"node_name": "<String>",
"client_id": "<String | Base32-UUIDv4>",
"bundle_id": "<String | Base32-UUIDv4>",
"connection_id": "<Base32-UUIDv4>"
},
{
"label": "<String>",
"node_name": "<String>",
"client_id": "<String | Base32-UUIDv4>",
"bundle_id": "<String | Base32-UUIDv4>",
"connection_id": "<Base32-UUIDv4>"
}
]
}
}
分割録画時 recording.report¶
{
"type": "recording.report",
"id": "<Base32-UUIDv4>",
"version": "<String>",
"label": "<String>",
"node_name": "<String>",
"channel_id": "<String>",
"session_id": "<String",
"session_metadata": "<JSON>",
"timestamp": "<UTC RFC3339 Timestamp>",
"data": {
"channel_id": "<String>",
"session_id": "<String>",
"recording_id": "<Base32-UUIDv4>",
"recording_metadata": "<JSON-Object>",
"split_only": "<Boolean>",
"split_duration": "<Integer>",
"created_at": "<UNIX-Time>",
"expire_time": "<Integer>",
"expired_at": "<UNIX-Time>",
"file_path": "<String>",
"filename": "<String>",
"file_written": "<Boolean>",
"start_timestamp": "<UTC RFC3339 Timestamp>",
"stop_timestamp": "<UTC RFC3339 Timestamp>",
"archives": [
{
"label": "<String>",
"node_name": "<String>",
"client_id": "<String | Base32-UUIDv4>",
"bundle_id": "<String | Base32-UUIDv4>",
"connection_id": "<Base32-UUIDv4>",
"start_time_offset": "<Integer>",
"start_timestamp": "<UTC RFC3339 Timestamp>",
"stop_time_offset": "<Integer>",
"stop_timestamp": "<UTC RFC3339 Timestamp>",
"split_last_index": "<String>"
},
{
"label": "<String>",
"node_name": "<String>",
"client_id": "<String | Base32-UUIDv4>",
"bundle_id": "<String | Base32-UUIDv4>",
"connection_id": "<Base32-UUIDv4>",
"start_time_offset": "<Integer>",
"start_timestamp": "<UTC RFC3339 Timestamp>",
"stop_time_offset": "<Integer>",
"stop_timestamp": "<UTC RFC3339 Timestamp>",
"split_last_index": "<String>"
}
],
"failed_archives": [
{
"label": "<String>",
"node_name": "<String>",
"client_id": "<String | Base32-UUIDv4>",
"bundle_id": "<String | Base32-UUIDv4>",
"connection_id": "<Base32-UUIDv4>"
},
{
"label": "<String>",
"node_name": "<String>",
"client_id": "<String | Base32-UUIDv4>",
"bundle_id": "<String | Base32-UUIDv4>",
"connection_id": "<Base32-UUIDv4>"
}
]
}
}
audio-streaming.started¶
重要
このウェブフックリクエストが送信されるには
sora.conf
の ignore_audio_streaming_webhook が false
である必要があります。
以下の 2 つの条件で音声ストリーミングが開始した時にウェブフックリクエストを送信します。
StartAudioStreaming API が実行されるか、 またはセッションウェブフックで
audio_streaming: true
払い出されたタイミングでウェブフックリクエストを送信します。音声ストリーミングの ウェブフック を利用時に SubscribeAudioStreamingResultPush API が呼び出される、もしくはクライアントが接続されて、 そのチャネルで音声ストリーミングの結果をサブスクライブしているクライアント数が 1 以上になった場合
session.created よりも必ず 後に ウェブフックが送信されます。
キー |
型 |
内容 |
---|---|---|
type |
string |
"audio-streaming.started" |
id |
string |
ウェブフック ID (ユニーク) |
label |
string |
sora.conf の label にて指定した値 |
node_name |
string |
Sora ノード名 |
version |
string |
Sora のバージョン |
channel_id |
string |
チャネル ID |
session_id |
string |
セッション ID |
timestamp |
string (RFC3339 UTC マイクロ秒) |
ウェブフック作成時間 |
created_time |
integer (UNIX 時間) |
セッション生成時間 |
created_timestamp |
string (RFC3339 UTC マイクロ秒) |
セッション生成時間 |
multistream |
boolean |
マルチストリームが有効かどうか |
spotlight |
boolean |
スポットライトが有効かどうか |
session_metadata |
json |
(値がある場合) session.created の戻り値で指定した値 |
external_signaling_url |
string |
(クラスター機能が有効の場合) 接続先の external_signaling_url |
data |
object |
音声ストリーミング固有 |
data には以下が含まれます。
キー |
型 |
内容 |
---|---|---|
audio_streaming_auto |
boolean |
自動開始/停止が有効かどうか |
audio_streaming_started_timestamp |
string (RFC3339 UTC マイクロ秒) |
音声ストリーミングを開始した時間 |
{
"channel_id": "sora",
"created_time": 1638337454,
"created_timestamp": "2021-12-01T05:44:14.523736Z",
"id": "2YN2DQE5KD3GSFSVPAYZ7VTAV4",
"label": "WebRTC SFU Sora",
"multistream": true,
"spotlight": false,
"node_name": "[email protected]",
"session_id": "NPR769YPQ914K10FW42PGH4TKW",
"timestamp": "2022-12-01T05:44:14.523912Z",
"type": "audio-streaming.started",
"version": "2023.2.0",
"session_metadata": {"spam": "egg"},
"external_signaling_url": "wss://node-01.example.com/signaling",
"data": {
"audio_streaming_auto": true,
"audio_streaming_started_timestamp": "2021-12-01T05:44:16.523912Z"
}
}
audio-streaming.stopped¶
重要
このウェブフックリクエストが送信されるには
sora.conf
の ignore_audio_streaming_webhook が false
である必要があります。
以下の 3 つの条件で音声ストリーミングが停止した時にウェブフックリクエストを送信します。
セッションが破棄された場合
StopAudioStreaming API が呼び出す場合
音声ストリーミングの ウェブフック を利用時に UnsubscribeAudioStreamingResultPush API が呼び出される、もしくはクライアントが切断されて、 そのチャネルで音声ストリーミングの結果をサブスクライブしているクライアント数が 0 になった場合
session.destroyed よりも必ず 前に ウェブフックが送信されます。
キー |
型 |
内容 |
---|---|---|
type |
string |
"audio-streaming.started" |
id |
string |
ウェブフック ID (ユニーク) |
label |
string |
sora.conf の label にて指定した値 |
node_name |
string |
Sora ノード名 |
version |
string |
Sora のバージョン |
channel_id |
string |
チャネル ID |
session_id |
string |
セッション ID |
timestamp |
string (RFC3339 UTC マイクロ秒) |
ウェブフック作成時間 |
created_time |
integer (UNIX 時間) |
セッション生成時間 |
created_timestamp |
string (RFC3339 UTC マイクロ秒) |
セッション生成時間 |
multistream |
boolean |
マルチストリームが有効かどうか |
spotlight |
boolean |
スポットライトが有効かどうか |
session_metadata |
json |
(値がある場合) session.created の戻り値で指定した値 |
external_signaling_url |
string |
(クラスター機能が有効の場合) 接続先の external_signaling_url |
data |
object |
音声ストリーミング固有 |
data には以下が含まれます。
キー |
型 |
内容 |
---|---|---|
audio_streaming_auto |
boolean |
自動開始/停止が有効かどうか |
audio_streaming_started_timestamp |
string (RFC3339 UTC マイクロ秒) |
音声ストリーミングを開始した時間 |
audio_streaming_stopped_timestamp |
string (RFC3339 UTC マイクロ秒) |
音声ストリーミングを停止した時間 |
{
"channel_id": "sora",
"created_time": 1638337454,
"created_timestamp": "2021-12-01T05:44:14.523736Z",
"id": "2YN2DQE5KD3GSFSVPAYZ7VTAV4",
"label": "WebRTC SFU Sora",
"multistream": true,
"spotlight": false,
"node_name": "[email protected]",
"session_id": "NPR769YPQ914K10FW42PGH4TKW",
"timestamp": "2022-12-01T05:44:14.523912Z",
"type": "audio-streaming.stopped",
"version": "2023.2.0",
"session_metadata": {"spam": "egg"},
"external_signaling_url": "wss://node-01.example.com/signaling",
"data": {
"audio_streaming_auto": true,
"audio_streaming_started_timestamp": "2021-12-01T05:44:16.523912Z",
"audio_streaming_stopped_timestamp": "2021-12-01T05:44:16.523912Z"
}
}
API¶
TerminateSession API¶
セッションを強制的に終了させる API です。
channel_id
を指定して、セッションを終了させます。
session_id
を追加で指定することができますが、 session_id
が見つからない場合はエラーになります。
API 実行中に新規の接続が来た場合、その接続はいったん保留して、セッション破棄後に新規セッションでの接続として扱います。
クラスター時の挙動について¶
セッションが存在していたノードで障害が起きた場合でも、 session.destroyed
は送信されます¶
別のノードが session.destroyed
を送信します。その際 reason
項目には abort
が入ります。
reason
が abort
の場合、以下の情報が 最新の状態 ではない場合があります。
total_connections
max_connections
セッションが存在していたノードで障害が起きた際、同一ウェブフックが複数回送られる事があります¶
以下のウェブフックは複数回送られる可能性はあります、その際はウェブフックの "id"
は同一になります。
session.destroyed
recording.started
recording.report
audio-streaming.stopped
クラスターリレー時の挙動について¶
セッションウェブフックはどのノードが送信しますか?¶
session.created
を送信したノードが session.destroyed
を送信します。
HTTP ヘッダー¶
警告
この機能は 実験的機能 のため、正式版では仕様が変更される可能性があります
注釈
JSON のパース時の判断などに利用してください。
sora-session-webhook-type¶
注意
x-sora-session-webhook-type
は非推奨です、 sora-session-webhook-type
を利用してください
セッションウェブフックの HTTP ヘッダー に sora-session-webhook-type
または x-sora-session-webhook-type
というヘッダー名でセッションウェブフックのタイプが入ってきます。
type
が session.created
の場合は sora-session-webhook-type: session.created
または x-sora-session-webhook-type: session.created
のように値が入ってきます。
sora-session-id¶
セッションウェブフックの HTTP ヘッダー に sora-session-id
というヘッダー名でセッション ID が入ってきます。
セッション ID が 46NNAV9S0X3TD778A1JBYYCBS8
の場合は sora-session-id: 46NNAV9S0X3TD778A1JBYYCBS8
のように値が入ってきます。