転送フィルター機能¶
注意
この機能を利用する場合は事前にサポートまでご連絡ください
警告
この機能は 実験的機能 のため、正式版では仕様が変更される可能性があります
注釈
転送とは Sora がクライアントから受信した音声や映像を他のクライアントに送信することを意味します。
概要¶
転送フィルター機能は、Sora 側でクライアントへ転送する音声や映像のパケットをフィルターする機能です。
目的¶
転送フィルター機能を使うことで、Sora から音声や映像のパケットをクライアントへ転送しなくなるため、 クライアントやサーバー側の負荷を減らすことができます。
また、接続直後に音声や映像を転送しなくすることも可能です。 そのため、何らかのアクションを取ってから音声と映像を流し始めることができるようになります。
注意¶
利用可能なロール¶
この機能は role
が sendrecv
または recvonly
の場合にのみ利用できます。
データチャネルを利用したメッセージング¶
データチャネルを利用したメッセージング機能は転送フィルター機能の対象外です。
機能¶
注釈
チャネル単位、コネクション単位でフィルターが設定できます。
転送フィルターのルール指定は、チャネル単位、コネクション単位で指定できます
転送フィルターのルールにはコネクション ID とクライアント ID と種類 (音声、映像) が指定できます
転送フィルタールール に指定するコネクション ID は 音声や映像の 送信元の コネクション ID です。
転送フィルタールール に指定するクライアント ID は 音声や映像の 送信元の クライアント ID です。
シグナリング指定時や認証成功時に そのコネクションに対するのフィルター を指定可能です
転送フィルター更新時に転送フィルターのバージョンを確認し、一致した場合のみ更新することができます
転送フィルターにメタデータを持たせることができます
転送フィルタールールの仕様¶
シグナリング、認証成功時の払い出し、セッション払い出し、API で共通のフィルタールールについて説明します。
フィルターは AND と OR が指定できます。ルールはリストとオブジェクトを利用して設定します。
重要
転送フィルターのルールでは転送先のコネクション ID やクライアント ID を指定することはできません。 指定できるのは Sora に音声や映像を送信しているコネクションやクライアントの ID のみです。
チャネル単位でフィルターを設定する¶
CreateChannelForwardingFilter API またはセッション開始時の払い出しを利用することで、 指定したチャネルに参加している すべてのコネクションへ音声や映像を送信するかどうか を設定可能です。
コネクション単位でフィルター設定する¶
CreateConnectionForwardingFilter API 、シグナリング接続時の指定、または認証成功時の払い出しを利用することで、 指定したチャネルの 指定したコネクションへ音声や映像を送信するかどうか を設定可能です。
特定のコネクションに対してあるコネクションの映像を送りたくないなどが可能になります。
OR と AND¶
トップレベルリストは OR を表しており、リストのリストでは AND を表しています。
[[rule_1], [rule_2, rule_3]]
この場合は (rule_1 OR (rule_2 AND rule_3))
という転送フィルタールールが適用されます。
[[rule_1, rule_2]]
この場合は (rule_1 AND rule_2)
という転送フィルタールールが適用されます。
警告
[[[rule_1, rule_2], [rule_3]], [rule_5]]
のような 3 階層のルールは定義できません。
転送フィルターのルールで利用できるリストの階層は 2 階層までとなります。
action について¶
転送フィルターには action
を指定できます。
アクションには block
と allow
が指定できます。
block
を指定した場合は、 rules にマッチした条件でのみ転送をブロックしますallow
を指定した場合は、 rules にマッチした条件でのみ転送を許可します
デフォルトでは block
になります。
block
と allow
では allow
が優先されます。
例えばチャネル単位の転送フィルターでは映像を block
にして設定している状態で、
ある接続の転送フィルターでは映像を allow
に設定した場合、その接続にだけは映像の転送が許可されます。
version について¶
転送フィルターに文字列でバージョンを version
項目で指定することができます。これはオプションです。
転送フィルター作成時に version
を指定した場合、
転送フィルターを更新するには expected_version
と desired_version
を指定する必要があります。
expected_version
は更新する転送フィルターの version
を指定します。
転送フィルターのバージョンが異なった場合、転送フィルターの更新は失敗します。
転送フィルターのバージョンが一致した場合、転送フィルターの更新派生講師、
desired_version
の値が、新しい version
の値となります。
version
を利用する事で転送フィルターを並列で実行されても期待した値に変更することができるようになります。
metadata について¶
転送フィルターにはメタデータを metadata
項目を指定することができます。これはオプションです。
転送フィルター作成、または更新時に metadata
に JSON 値を指定することができます。
この metadata
は転送フィルターの挙動には影響せず、転送フィルターの情報を自由に書き込める項目です。
metadata
を利用する事で転送フィルターに関する情報を自由に管理することができるようになります。
rules の書き方¶
すべての項目は必須です
field
フィールドには
connection_id
とclient_id
とkind
とtarget
が指定できますconnection_id
フィルターの対象となる音声や映像の 送信元の コネクション ID を指定してください
client_id
フィルターの対象となる音声や映像の 送信元の クライアント ID を指定してください
kind
フィルターに音声や映像を指定できます
target
フィルターに録画を指定できます
operator
オペレーターには
is_in
とis_not_in
が指定できますis_in
values に指定されたリストに含まれる値にマッチしている場合は転送フィルターの対象とする
is_not_in
values に指定されたリストに含まれる値にマッチしていない場合は転送フィルターの対象とする
values
バリューにはかならず文字列のリスト
["string", ...]
を指定してくださいfield
に合った値を指定してくださいfield
がkind
の場合は"audio"
または"video"
を指定してくださいfield
がtarget
の場合は"recording"
を指定してください
{
"action": "block",
"rules": [
// チャネルに接続しているすべてのクライアントへ connection_id "S8YEN0TSE13JDC2991NG4XZ150" からの音声と映像をブロックし転送しない
// また
// チャネルに接続しているすべてのクライアントへ client_id が "screen-share" の音声をブロックし転送しない
[
{
"field": "connection_id",
"operator": "is_in",
"values": ["S8YEN0TSE13JDC2991NG4XZ150"]
}
],
[
{
"field": "client_id",
"operator": "is_in",
"values": ["screen-share"]
},
{
"field": "kind",
"operator": "is_in",
"values": ["audio"]
}
]
]
}
field に connection_id
を指定した場合¶
kind
を指定しなくても audio
と video
がブロックされます。
{
"action": "block",
"rules": [
// チャネルに接続しているすべてのコネクションへ connection_id "S8YEN0TSE13JDC2991NG4XZ150" からの音声と映像をブロックし転送しない
[
{
"field": "connection_id",
"operator": "is_in",
"values": ["S8YEN0TSE13JDC2991NG4XZ150"]
}
]
]
}
送信元の指定をせずすべての音声と映像をブロックする¶
kind
を指定することで送信元の指定がないフィルターを作成できます。
音声と映像の両方をブロックするので values
に audio
と video
両方を指定しています。
{
"action": "block",
"rules": [
// チャネルに接続しているすべてのコネクションに対して音声と映像をブロックし転送しない
[
{
"field": "kind",
"operator": "is_in",
"values": ["audio", "video"]
}
]
]
}
特定の接続の録画をブロックする¶
target
に recording
を指定することで録画をブロックすることができます。
{
"action": "block",
"rules": [
// connection_id "S8YEN0TSE13JDC2991NG4XZ150" の録画をブロックする
[
{
"field": "connection_id",
"operator": "is_in",
"values": ["S8YEN0TSE13JDC2991NG4XZ150"]
},
{
"field": "target",
"operator": "is_in",
"values": ["recording"]
}
]
]
}
フィルタールールの適用¶
チャネル単位でのフィルター
転送フィルターのルールにマッチした条件で、すべてのコネクションに対して転送するかどうか
コネクション単位でのフィルター
転送フィルターのルールでマッチした条件で、指定した
connection_id
に対して転送するかどうか
フィルターの優先度
チャネル単位でフィルターとコネクション単位でのフィルターに優先度はない
優先度は
allow
とblock
にだけありallow
が優先される
転送フィルター共通 API の仕様¶
ListForwardingFilters API¶
指定したチャネルのチャネルとコネクション両方の転送フィルターを確認できます。
channel_id
string
必須
blocked
boolean
オプション
ブロック状況を表示するかどうかを指定します
$ http POST 127.0.0.1:3000/ \
x-sora-target:Sora_20230628.ListForwardingFilters \
channel_id=sora \
blocked:=true \
-vvv
{
"channel_forwarding_filter": {
"action": "block",
"rules": [
[{"field": "kind", "operator": "is_in", "values": ["audio", "video"]}]
]
},
"connection_forwarding_filters": [
{
"connection_id": "9PZ98RZV1H3RSEZ82SBBC289F8",
"action": "allow",
"rules": [
[{"field": "kind", "operator": "is_in", "values": ["audio"]}]
]
},
{
"connection_id": "8QA9YX7ZJX3150ZJ87874TBFMG",
"action": "allow",
"rules": [
[{"field": "kind", "operator": "is_in", "values": ["audio"]}]
]
}
],
"blocked": [
{
"destination_connection_id": "9PZ98RZV1H3RSEZ82SBBC289F8",
"source_connection_id_list": [
"2VJPS671HH1EH3HNY13SXHS5RG"
],
"kind": "audio"
},
{
"destination_connection_id": "9PZ98RZV1H3RSEZ82SBBC289F8",
"source_connection_id_list": [
"2VJPS671HH1EH3HNY13SXHS5RG",
"C4D50FG8Q16BF4YCTT0V8YGSXM"
],
"kind": "video"
}
]
}
チャネル単位の転送フィルター API の仕様¶
CreateChannelForwardingFilter API¶
指定したチャネルに対して Sora の転送フィルターを作成する API です。
channel_id
string
必須
rules
[[object, ...], [object, ...]]
必須
転送フィルターのルールを指定します
action
string
オプション
block
またはallow
デフォルトは
block
version
string
オプション
転送フィルターのバージョンを指定します
metadata
json value
オプション
転送フィルターのメタデータを指定します
$ http POST 127.0.0.1:3000/ \
x-sora-target:Sora_20230628.CreateChannelForwardingFilter \
channel_id=sora \
rules:='[
[
{"field": "client_id", "operator": "is_in", "values": ["screen-share"]},
{"field": "kind", "operator": "is_in", "values": ["video"]}
]
]' \
-vvv
UpdateChannelForwardingFilter API¶
指定したチャネルの転送フィルターを更新します。
channel_id
string
必須
rules
[[object, ...], [object, ...]]
必須
転送フィルターのルールを指定します
action
string
オプション
block
またはallow
デフォルトは
block
デフォルトは
block
expected_version
string
オプション
転送フィルターの期待するバージョンを指定します
desired_version
string
オプション
転送フィルターの更新成功後のバージョンを指定します
metadata
json value
オプション
転送フィルターのメタデータを指定します
$ http POST 127.0.0.1:3000/ \
x-sora-target:Sora_20230628.UpdateChannelForwardingFilter \
channel_id=sora \
rules:='[
[
{"field": "connection_id", "operator": "is_in", "values": ["RAV7EG7Z693NDCZFGGXZS7WBRC"]}
],
[
{"field": "client_id", "operator": "is_in", "values": ["screen-share"]},
{"field": "kind", "operator": "is_in", "values": ["video"]}
]
]' \
-vvv
DeleteChannelForwardingFilter API¶
指定したチャネルの転送フィルターを削除します。
channel_id
string
必須
$ http POST 127.0.0.1:3000/ \
x-sora-target:Sora_20230628.DeleteChannelForwardingFilter \
channel_id=sora \
-vvv
コネクション単位の転送フィルター API の仕様¶
CreateConnectionForwardingFilter API¶
指定したチャネルの特定のコネクションの転送フィルターを作成します。
channel_id
string
必須
connection_id
string
必須
rules
[[object, ...], [object, ...]]
必須
転送フィルターのルールを指定します
action
string
オプション
block
またはallow
デフォルトは
block
version
string
オプション
転送フィルターのバージョンを指定します
metadata
json value
オプション
転送フィルターのメタデータを指定します
$ http POST 127.0.0.1:3000/ \
x-sora-target:Sora_20230628.CreateConnectionForwardingFilter \
channel_id=sora \
connection_id=T9J5FM3NTH6JH4JKFGTSHB1BA0 \
rules:='[
[
{"field": "client_id", "operator": "is_in", "values": ["screen-share"]},
{"field": "kind", "operator": "is_in", "values": ["video"]}
]
]' \
-vvv
UpdateConnectionForwardingFilter API¶
指定したチャネルの特定のコネクションの転送フィルターを更新します。
channel_id
string
必須
connection_id
string
必須
rules
[[object, ...], [object, ...]]
必須
転送フィルターのルールを指定します
action
string
オプション
block
またはallow
デフォルトは
block
expected_version
string
オプション
転送フィルターの期待するバージョンを指定します
desired_version
string
オプション
転送フィルターの更新成功後のバージョンを指定します
metadata
json value
オプション
転送フィルターのメタデータを指定します
$ http POST 127.0.0.1:3000/ \
x-sora-target:Sora_20230628.UpdateConnectionForwardingFilter \
channel_id=sora \
connection_id=T9J5FM3NTH6JH4JKFGTSHB1BA0 \
rules:='[
[
{"field": "connection_id", "operator": "is_in", "values": ["RX1GD666HD53F3M36PB7KEZMBR"]},
{"field": "kind", "operator": "is_in", "values": ["video"]}
]
]' \
-vvv
DeleteConnectionForwardingFilter API¶
指定したチャネルの特定のコネクションの転送フィルターを削除します。
channel_id
string
必須
connection_id
string
必須
$ http POST 127.0.0.1:3000/ \
x-sora-target:Sora_20230628.DeleteConnectionForwardingFilter \
channel_id=sora \
connection_id=T9J5FM3NTH6JH4JKFGTSHB1BA0 \
-vvv
セッション作成時のチャネル単位転送フィルター仕様¶
セッション作成時に転送フィルターを指定することが可能です。
以下はセッション接続時には音声しか転送しないフィルター例です。
{
"forwarding_filter": {
"action": "allow",
"rules": [
[
{"field": "kind", "operator": "is_in", "values": ["audio"]}
]
]
}
}
version
や metadata
も指定可能です。
注釈
セッション作成時に転送フィルターを指定した場合、 API 経由で変更するには UpdateChannelForwardingFilter API を利用する必要があります。
シグナリング時のコネクション単位転送フィルター仕様¶
シグナリング接続時に コネクション単位での転送フィルター を指定することが可能です。
この転送フィルターは接続したコネクションにのみ影響します。
重要
シグナリング接続時に転送フィルターを指定する場合は sora.conf
にて、
signaling_forwarding_filter を true
に設定する必要があります。
以下は接続時に映像を転送せずに音声だけを自分に転送するフィルター例です。
{
"type": "connect",
"role": "sendrecv",
"channel_id": "sora",
"forwarding_filter": {
"action": "block",
"rules": [
[
{"field": "kind", "operator": "is_in", "values": ["video"]}
]
]
}
}
version
や metadata
も指定可能です。
注釈
シグナリング時に転送フィルターを指定した場合、 API 経由で変更するには UpdateConnectionForwardingFilter API を利用する必要があります。
認証成功時払い出し時のコネクション単位転送フィルターの仕様¶
認証成功時に、コネクション単位の転送フィルターを指定することができます。
以下は映像を転送せずに音声だけをそのコネクションに転送するフィルター例です。
{
"allowed": true,
"forwarding_filter": {
"action": "block",
"rules": [
[
{"field": "kind", "operator": "is_in", "values": ["video"]}
]
]
}
}
version
や metadata
も指定可能です。
注釈
認証成功払い出し時に転送フィルターを作成した場合、 API 経由で変更するには UpdateConnectionForwardingFilter API を利用する必要があります。
シグナリング通知¶
転送フィルターを作成、更新、削除したタイミングで、 転送フィルターによって転送されていないかどうかを、シグナリング経由で通知します。
転送フィルターが影響する範囲にのみ通知されます。
通知は送信側と受信側の両方に送られます。
destination は映像または音声の送信先です
source は映像または音声の送信元です
destination_connection_id は映像または音声の送信先の connection_id です
souce_connection_id は映像または音声の送信元の connection_id です
forwarding.blocked¶
転送フィルターによりブロックが有効になったタイミングで送信側と受信側に通知されます。
以下の通知は、 source_connection_id
の送信元から destination_connection_id
の送信先へ送信した音声をブロックすることを表しています。
{
"type": "notify",
"kind": "audio",
"event_type": "forwarding.blocked",
"destination_connection_id": "14P91M6B5526928T14WGPW9H6G",
"source_connection_id": "GHRNJAQ40S15KCF3MZF0N7QS8R"
}
forwarding.allowed¶
転送フィルターによりブロックが解除されたタイミングで送信側と受信側に通知されます。
以下の通知は、 source_connection_id
の送信元から destination_connection_id
の送信先へ送信した音声のブロックが解除されたことを表しています。
{
"type": "notify",
"kind": "audio",
"event_type": "forwarding.allowed",
"destination_connection_id": "14P91M6B5526928T14WGPW9H6G",
"source_connection_id": "GHRNJAQ40S15KCF3MZF0N7QS8R"
}
フィルター例¶
特定のクライアントにだけ音声と映像を転送しない¶
CreateConnectionForwardingFilter
API で音声と映像を転送したくないクライアントに対してフィルターを設定してください
$ http POST 127.0.0.1:3000/ \
x-sora-target:Sora_20230628.CreateConnectionForwardingFilter \
channel_id=sora \
connection_id=T9J5FM3NTH6JH4JKFGTSHB1BA0 \
action=block \
rules:='[
[
{"field": "kind", "operator": "is_in", "values": ["audio", "video"]}
]
]' \
-vvv
このフィルターは指定したコネクションに転送するパケットのフィルターを設定しています。
kind
で audio
と video
が is_in
に設定されており、
すべてのクライアントから Sora に送信されてくる audio と video を指定したクライアントに転送しなくなります。
特定の connection_id の送信元以外の音声や映像を転送しない¶
CreateChannelForwardingFilter
API で音声と映像の転送を許可する送信元のコネクション ID を指定してください。
$ http POST 127.0.0.1:3000/ \
x-sora-target:Sora_20230628.CreateChannelForwardingFilter \
channel_id=sora \
action=block \
rules:='[
[
{"field": "connection_id", "operator": "is_not_in", "values": ["S8YEN0TSE13JDC2991NG4XZ150"]}
]
]' \
-vvv
このフィルターでは指定したチャネルに転送するパケットのフィルターを設定しています。
operator
に is_not_in
を指定することで指定したコネクション ID の送信元以外からのパケットの送信をブロックします。
全体をブロックしているが、一時的に特定の connection_id の送信先だけには全クライアントの音声と映像を転送する¶
CreateChannelForwardingFilter
API で音声と映像の転送をブロックしてください。
$ http POST 127.0.0.1:3000/ \
x-sora-target:Sora_20230628.CreateChannelForwardingFilter \
channel_id=sora \
action=block \
rules:='[
[
{"field": "kind", "operator": "is_in", "values": ["audio", "video"]}
]
]' \
-vvv
CreateConnectionForwardingFilter
API で一時的にブロックしない送信先の connection_id を指定してください。
ポイントはコネクション単位で action
に allow
を指定します。 allow
は block
を上書きします。
$ http POST 127.0.0.1:3000/ \
x-sora-target:Sora_20230628.CreateConnectionForwardingFilter \
channel_id=sora \
connection_id=T9J5FM3NTH6JH4JKFGTSHB1BA0 \
action=allow \
rules:='[
[
{"field": "kind", "operator": "is_in", "values": ["audio", "video"]}
]
]' \
-vvv
これで全体をブロックした状態で、指定した connection_id の送信先にだけ音声や映像が転送されます。
FAQ¶
チャネルとコネクションの転送フィルターはどちらが優先されますか?¶
チャネルとコネクションで優先度は特にありません。
ただしアクションの allow
が優先されます。
チャネルのアクションが block
でコネクションのアクションが allow
で、
同じコネクション ID を指定した場合は allow
が優先されます。
転送フィルターでブロックされたときの挙動を教えてください¶
Sora は転送フィルターでブロックされた音声や映像パケットをクライアントに転送しません。 そのため受信側ではパケットが「何も送られてこない」という状態になります。
転送フィルターが更新、または削除や allow
で転送される状態になるとパケットの転送を開始します。
転送フィルターを有効にした場合は ontrack は SDK 側で発火しますか?¶
発火します。転送フィルターはあくまで 本来転送する音声や映像を Sora でフィルターする機能 のため、 SDK 側の ontrack 自体は発火します。
フィルターでブロックされたりブロック解除されたタイミングをクライアント側で知ることはできますか?¶
Sora はシグナリング通知経由でブロック/ブロック解除されたタイミングで通知します。 これはブロックされた送信側と受信側両方に通知が飛びます。
録画のブロックとはなんですか?¶
セッション単位で録画を有効にした際、特定のコネクション ID またはクライアント ID を録画しない仕組みです。 転送フィルターによる録画のブロックが有効な場合は、録画ファイルが作成されません。
シーケンス図¶
チャネル単位のブロック例¶
チャネルフィルターとコネクションフィルター組み合わせ例¶
version を利用した変更保証¶
並列に転送フィルター更新 API が叩かれてもバージョンチェックをすることで更新結果を保証する。