マルチ転送フィルター拡張機能¶

注意

この機能を利用する場合は事前にサポートまでご連絡ください

警告

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

概要¶

これは転送フィルター機能にあった更新の難しさを解決するための拡張機能です。複数の転送フィルターを一つの channel_id や connection_id に指定できるようになります。

マルチ転送フィルターは既存の転送フィルターの拡張機能です。既存の転送フィルターを利用していても影響はありません。

マルチ転送フィルター拡張機能が有効になる条件¶

CreateChannelForwardingFilter API で name と priority を指定した場合
- ただし name が "default" かつ priority が 32767 の場合はマルチ転送フィルター拡張機能が有効になりません
セッション生成時の払い出しに forwarding_filters を指定した場合

認証成功時とセッション生成時の払い出し¶

認証成功時とセッション生成時の払い出しには forwarding_filter または forwarding_filters が利用できます
- セッション生成時の払い出しが優先されるため、認証成功時に forwarding_filter を指定したとしてもセション生成時の払い出しで forwarding_filters が指定されている場合はマルチ転送フィルター拡張機能が有効になったセッションとして扱われます

制限¶

現時点ではマルチ転送フィルター拡張機能は "type": "connect" 時には指定できません
一度マルチ転送フィルター拡張機能を有効にしたセッションでは、セッションが破棄されるまでマルチ転送フィルター拡張機能は有効です

仕様¶

Sora 単位では転送フィルター機能とマルチ転送フィルター拡張機能は同時に利用できます
セッション単位では転送フィルター機能とマルチ転送フィルター拡張機能のどちらかが利用できます
マルチ転送フィルター拡張機能は複数の転送フィルターを一つの channel_id や connection_id に指定できます
転送フィルターは転送を判定するタイミングで、複数の転送フィルターを判定します
- ただし判定するタイミングで、優先度が高いものから判定します
転送フィルター追加時に名前 (name) と優先度 (priority) を指定するとマルチ転送フィルター拡張機能が有効になります
- ただし name が "default" かつ priority が 32767 の場合はマルチ転送フィルター拡張機能が有効になりません
転送フィルター更新時に名前 (name) と優先度 (priority) を指定してください
転送フィルター削除時に名前 (name) を指定して削除してください
名前は任意の文字列 (最大 255 バイト) が指定できます
名前は重複できません
- channel_id または connection_id 単位でユニークな名前が必要
- 名前が重複している場合はエラーになります
優先度は 0-32767 (16#7FFF) の間で指定してください
優先度が一番高いのは 0 で、数値が大きいほど優先度が低くなります
優先度は重複できます
- 優先度が同じ場合は allow が優先される
- block のみの場合は OR で判定
- allow のみの場合は OR で判定
- block / block / allow なら allow のみで判定
name と priority を指定しない場合はデフォルト値が設定されます
- name は "default"
- priority は 32767

性能¶

1 channel や 1 connection に対して数千などのフィルターを設定しない限り、性能が劣化することはありません。

認証成功時の払い出し¶

認証成功時の払い出しが forwarding_filter だった場合でも、セッション生成時の払い出しが forwarding_filters の場合、マルチ転送フィルター拡張機能は有効になります。

forwarding_filters: [
   {
      "name": "client-id-carol-block",
      "priority": 0,
      "action": "allow",
      "rules": [
         [
            {
               "field": "client_id",
               "operator": "is_in",
               "values": [
                  "carol",
               ]
            }
         ]
      ]
   },
   {
      "name": "default",
      "priority": 32767,
      "action": "block",
      "rules": [
         [
            {
               "field": "kind",
               "operator": "is_in",
               "values": [
                  "audio",
                  "video",
               ]
            }
         ]
      ]
   }
]

セッション生成時の払い出し¶

forwarding_filters: list() で払い出すことでマルチ転送フィルターを利用するようになります

forwarding_filters: [
   {
      "name": "client-id-alice-block",
      "priority": 0,
      "action": "block",
      "rules": [
         [
            {
               "field": "client_id",
               "operator": "is_in",
               "values": [
                  "alice",
               ]
            }
         ]
      ]
   },
   {
      "name": "client-id-bob-block",
      "priority": 0,
      "action": "block",
      "rules": [
         [
            {
               "field": "client_id",
               "operator": "is_in",
               "values": [
                  "bob",
               ]
            }
         ]
      ]
   },
   {
      "name": "default",
      "priority": 32767,
      "action": "block",
      "rules": [
         [
            {
               "field": "kind",
               "operator": "is_in",
               "values": [
                  "audio"
               ]
            }
         ]
      ]
   }
]

API 仕様¶

転送フィルター API はそのまま利用できます。

ListForwardingFilters API
- name と priority がデフォルト値でない場合、または複数の転送フィルターが設定されている場合、マルチ転送フィルター拡張機能が有効になります
- マルチ転送フィルター拡張機能が有効な場合は channel_forwarding_filter が channel_forwarding_filters になり、 [] になります。
CreateChannelForwardingFilter API
- name と priority はオプションです
- name か priority のどちらかを指定することはできません、両方指定する必要があります
- マルチ転送フィルター拡張機能が有効な場合は一回の API では一つの転送フィルターしか追加できません
UpdateChannelForwardingFilter API
- name と priority はオプションです
- name か priority のどちらかを指定することはできません、両方指定する必要があります
- マルチ転送フィルター拡張機能が有効な場合は一回の API では一つの転送フィルターしか更新できません
DeleteChannelForwardingFilter API
- name はオプションです
- name が指定された場合はその名前の転送フィルターを削除
- マルチ転送フィルター拡張機能が有効な場合は一回の API では一つの転送フィルターしか削除できません
CreateConnectionForwardingFilter API
- name と priority はオプションです
- name か priority のどちらかを指定することはできません、両方指定する必要があります
- マルチ転送フィルター拡張機能が有効な場合は一回の API では一つの転送フィルターしか追加できません
UpdateConnectionForwardingFilter API
- name と priority はオプションです
- name か priority のどちらかを指定することはできません、両方指定する必要があります
- マルチ転送フィルター拡張機能が有効な場合は一回の API では一つの転送フィルターしか更新できません
DeleteConnectionForwardingFilter API
- name はオプションです
- name が指定された場合はその名前の転送フィルターを削除
- マルチ転送フィルター拡張機能が有効な場合は一回の API では一つの転送フィルターしか削除できません