# 転送フィルター API

転送フィルター API は、チャネル単位やコネクション単位で音声や映像の転送をフィルタリングする機能です。


## ListForwardingFilters

*バージョン 2023.1.0 で追加。*

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

指定したチャネルについて、チャネル単位とコネクション単位両方の転送フィルターを表示します。
また、 `blocked` オプションの指定により音声と映像のブロック状況を表示します。

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

- `blocked` を指定しない場合は `false` が指定されます
- `version` が指定されているフィルターに対しては `version` 項目が追加されます
- `metadata` が指定されているフィルターに対しては `metadata` 項目が追加されます

```
$ curl -sS \
    -X POST \
    http://127.0.0.1:3000/ \
    -H "x-sora-target: Sora_20230628.ListForwardingFilters" \
    --json '{"channel_id":"sora","blocked":true}' \
    | jq .
{
   "channel_forwarding_filters": [
     {
       "action": "block",
       "name": "default",
       "priority": 32767,
       "rules": [
           [
             {
                 "field": "kind",
                 "operator": "is_in",
                 "values": [
                   "video",
                   "audio"
                 ]
             }
           ]
       ]
     }
   ],
   "connection_forwarding_filters": [
      {
         "action": "allow",
         "name": "default",
         "priority": 32767,
         "connection_id": "6V9VANDZZH71HCQGVKBWKJ8GS0",
         "rules": [
            [
               {
                  "field": "kind",
                  "operator": "is_in",
                  "values": [
                     "video"
                  ]
               }
            ]
         ]
      },
      {
         "action": "allow",
         "name": "default",
         "priority": 32767,
         "connection_id": "XEDQM589M520Z50KM7C6C5PRB0",
         "rules": [
            [
               {
                  "field": "kind",
                  "operator": "is_in",
                  "values": [
                     "audio"
                  ]
               }
            ]
         ]
      }
   ],
   "blocked": [
      {
         "destination_connection_id": "6V9VANDZZH71HCQGVKBWKJ8GS0",
         "kind": "audio",
         "source_connection_id_list": [
            "ASJDFJ1PF94JN6DV59JQZ1HNDR"
         ]
      },
      {
         "destination_connection_id": "XEDQM589M520Z50KM7C6C5PRB0",
         "kind": "video",
         "source_connection_id_list": [
            "ASJDFJ1PF94JN6DV59JQZ1HNDR",
            "6V9VANDZZH71HCQGVKBWKJ8GS0"
         ]
      }
   ]
}
```

### レスポンス

レスポンスの内容は以下の通りです。転送フィルターについての詳細は [転送フィルタールールの仕様](FORWARDING_FILTER.html#86374f) をご確認ください。

- channel_forwarding_filters- 指定したチャネルに設定されているチャネル単位の転送フィルターをリストで表示します
- connection_forwarding_filters- 指定したチャネルに設定されているコネクション単位の転送フィルターを配列で表示します
- blocked- destination_connection_id- ブロックされている送信先のコネクション ID
  - kind- ブロックされているメディア (audio または video)
  - source_connection_id_list- ブロックされている送信元のコネクション ID の配列


## CreateChannelForwardingFilter

*バージョン 2023.1.0 で追加。*

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

指定したチャネルに対して転送フィルターを作成します。
チャネル単位での転送フィルター作成は、**送信元からの音声や映像を送信先に転送するかどうか** を制御します。 
送信先はチャネルに参加しているすべてのコネクションです。

指定した送信先だけにブロックをさせたい場合は [CreateConnectionForwardingFilter](API_FORWARDING_FILTER.html#d80a51) を使用してください。

転送フィルターの指定方法についての詳細は [転送フィルタールールの仕様](FORWARDING_FILTER.html#86374f) をご確認ください。

* - キー
  - 型
* - channel_id
  - string
* - action (オプション)
  - string (block | allow)
* - rules
  - array of object
* - version (オプション)
  - string
* - metadata (オプション)
  - JSONValue
* - name (オプション)
  - string (最大 255 バイト)
* - priority (オプション)
  - integer (0-32767)

- `action` の指定がない場合は `block` が指定されます
- `name` と `priority` を指定することができます- 複数の転送フィルターを指定する場合は `name` と `priority` を指定する必要があります
- `rules` は転送フィルターの対象を配列で指定します。 `rules` で指定する array of object の object の内容は以下の通りです

* - キー
  - 型
* - field
  - string (connection_id | client_id | kind)
* - operator
  - string (is_in | is_not_in)
* - values
  - array of string

```
$ curl -sS \
    -X POST \
    http://127.0.0.1:3000/ \
    -H "x-sora-target: Sora_20230628.CreateChannelForwardingFilter" \
    --json '{"channel_id":"sora","action":"block","rules":[[{"field":"connection_id","operator":"is_in","values":["XEDQM589M520Z50KM7C6C5PRB0"]},{"field":"client_id","operator":"is_not_in","values":["screen-share"]},{"field":"kind","operator":"is_in","values":["video"]}]]}' \
    | jq .
{
  "action": "block",
  "channel_id": "sora",
  "rules": [
    [
      {
        "field": "connection_id",
        "operator": "is_in",
        "values": [
          "XEDQM589M520Z50KM7C6C5PRB0"
        ]
      },
      {
        "field": "client_id",
        "operator": "is_not_in",
        "values": [
          "screen-share"
        ]
      },
      {
        "field": "kind",
        "operator": "is_in",
        "values": [
          "video"
        ]
      }
    ]
  ]
}
```


## UpdateChannelForwardingFilter

*バージョン 2023.1.0 で追加。*

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

指定したチャネルの転送フィルターの設定を、 `rules` と `action` の内容で置き換えます。

> **注意**
>
> この API を実行するには事前に指定したチャネル単位の転送フィルターが作成されている必要があります

* - キー
  - 型
* - channel_id
  - string
* - action (オプション)
  - string (block | allow)
* - rules
  - array of object
* - expected_version (オプション)
  - string
* - desired_version (オプション)
  - string
* - metadata (オプション)
  - JSONValue
* - name (オプション)
  - string (最大 255 バイト)
* - priority (オプション)
  - integer (0-32767)

- `action` の指定がない場合は `block` が指定されます
- `name` と `priority` を指定することができます- 指定しない場合は `name` には `default` 、 `priority` には `32767` が指定されます
  - `name` と `priority` のどちらかだけを指定することはできません
  - 複数の転送フィルターを指定する場合は `name` と `priority` を指定する必要があります
- `rules` は転送フィルターの対象を配列で指定します。 `rules` で指定する array of object の object の内容は以下の通りです

* - キー
  - 型
* - field
  - string (connection_id | client_id | kind)
* - operator
  - string (is_in | is_not_in)
* - values
  - array of string

```
$ curl -sS \
    -X POST \
    http://127.0.0.1:3000/ \
    -H "x-sora-target: Sora_20230628.UpdateChannelForwardingFilter" \
    --json '{"channel_id":"sora","action":"block","rules":[[{"field":"connection_id","operator":"is_in","values":["XEDQM589M520Z50KM7C6C5PRB0"]},{"field":"client_id","operator":"is_not_in","values":["screen-share"]},{"field":"kind","operator":"is_in","values":["video"]}]]}' \
    | jq .
{
   "action": "block",
   "channel_id": "sora",
   "rules": [
      [
         {
            "field": "connection_id",
            "operator": "is_in",
            "values": [
               "XEDQM589M520Z50KM7C6C5PRB0"
            ]
         },
         {
            "field": "client_id",
            "operator": "is_not_in",
            "values": [
               "screen-share"
            ]
         },
         {
            "field": "kind",
            "operator": "is_in",
            "values": [
               "video"
            ]
         }
      ]
   ]
}
```


## DeleteChannelForwardingFilter

*バージョン 2023.1.0 で追加。*

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

指定したチャネルの転送フィルターの設定を削除します。

> **注意**
>
> この API を実行するには事前に指定したチャネル単位の転送フィルターが作成されている必要があります

* - キー
  - 型
* - channel_id
  - string
* - name (オプション)
  - string (最大 255 バイト)

- `name` はマルチ転送フィルター機能が有効になっている場合に指定します

```
$ curl -sS \
    -X POST \
    http://127.0.0.1:3000/ \
    -H "x-sora-target: Sora_20230628.DeleteChannelForwardingFilter" \
    --json '{"channel_id":"sora"}' \
    | jq .
{
   "channel_id": "sora"
}
```


## CreateConnectionForwardingFilter

*バージョン 2023.1.0 で追加。*

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

指定したチャネルの特定コネクションに対して転送フィルターを作成します。

コネクション単位での転送フィルター作成は、**指定したコネクションに対して送信元からの音声や映像を転送するかどうか** を制御します。 
指定した送信先だけをブロックしたい場合に利用します。

転送フィルターの指定方法についての詳細は [転送フィルタールールの仕様](FORWARDING_FILTER.html#86374f) をご確認ください。

* - キー
  - 型
* - channel_id
  - string
* - connection_id
  - string
* - action (オプション)
  - string (block | allow)
* - rules
  - array of object
* - version (オプション)
  - string
* - metadata (オプション)
  - JSONValue
* - name (オプション)
  - string
* - priority (オプション)
  - integer

- `action` の指定がない場合は `block` が指定されます
- `name` と `priority` を指定することができます- `name` と `priority` のどちらかだけを指定することはできません
  - 複数の転送フィルターを指定する場合は `name` と `priority` を指定する必要があります
  - 指定しない場合は `name` には `default` 、 `priority` には `32767` が指定されます
- `rules` は転送フィルターの対象を配列で指定します。 `rules` で指定する array of object の object の内容は以下の通りです

* - キー
  - 型
* - field
  - string (connection_id | client_id | kind)
* - operator
  - string (is_in | is_not_in)
* - values
  - array of string

```
$ curl -sS \
    -X POST \
    http://127.0.0.1:3000/ \
    -H "x-sora-target: Sora_20230628.CreateConnectionForwardingFilter" \
    --json '{"channel_id":"sora","connection_id":"EQ13WT731S1EK452YRJVFGYAY8","action":"block","rules":[[{"field":"connection_id","operator":"is_in","values":["XEDQM589M520Z50KM7C6C5PRB0"]},{"field":"client_id","operator":"is_not_in","values":["screen-share"]},{"field":"kind","operator":"is_in","values":["video"]}]]}' \
    | jq .
{
  "action": "block",
  "channel_id": "sora",
  "connection_id": "EQ13WT731S1EK452YRJVFGYAY8",
  "rules": [
    [
      {
        "field": "connection_id",
        "operator": "is_in",
        "values": [
          "XEDQM589M520Z50KM7C6C5PRB0"
        ]
      },
      {
        "field": "client_id",
        "operator": "is_not_in",
        "values": [
          "screen-share"
        ]
      },
      {
        "field": "kind",
        "operator": "is_in",
        "values": [
          "video"
        ]
      }
    ]
  ]
}
```


## UpdateConnectionForwardingFilter

*バージョン 2023.1.0 で追加。*

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

指定したチャネルの特定コネクションに対する転送フィルターの設定を、 `rules` と `action` の内容で置き換えます。

> **注意**
>
> この API を実行するには事前に指定したコネクション単位の転送フィルターが作成されている必要があります

* - キー
  - 型
* - channel_id
  - string
* - connection_id
  - string
* - action (オプション)
  - string (block | allow)
* - rules
  - array of object
* - expected_version (オプション)
  - string
* - desired_version (オプション)
  - string
* - metadata (オプション)
  - JSONValue
* - name (オプション)
  - string (最大 255 バイト)
* - priority (オプション)
  - integer (0-32767)

- `action` の指定がない場合は `block` が指定されます
- `name` と `priority` を指定することができます- `name` と `priority` のどちらかだけを指定することはできません
- `rules` は転送フィルターの対象を配列で指定します。 `rules` で指定する array of object の object の内容は以下の通りです

* - キー
  - 型
* - field
  - string (connection_id | client_id | kind)
* - operator
  - string (is_in | is_not_in)
* - values
  - array of string
* - name (オプション)
  - string (最大 255 バイト)
* - priority (オプション)
  - integer (0-32767)

```
$ curl -sS \
    -X POST \
    http://127.0.0.1:3000/ \
    -H "x-sora-target: Sora_20230628.UpdateConnectionForwardingFilter" \
    --json '{"channel_id":"sora","connection_id":"T9J5FM3NTH6JH4JKFGTSHB1BA0","action":"block","rules":[[{"field":"connection_id","operator":"is_in","values":["XEDQM589M520Z50KM7C6C5PRB0"]},{"field":"client_id","operator":"is_not_in","values":["screen-share"]},{"field":"kind","operator":"is_in","values":["video"]}]]}' \
    | jq .
{
  "action": "block",
  "channel_id": "sora",
  "connection_id": "EQ13WT731S1EK452YRJVFGYAY8",
  "rules": [
    [
      {
        "field": "connection_id",
        "operator": "is_in",
        "values": [
          "XEDQM589M520Z50KM7C6C5PRB0"
        ]
      },
      {
        "field": "client_id",
        "operator": "is_not_in",
        "values": [
          "screen-share"
        ]
      },
      {
        "field": "kind",
        "operator": "is_in",
        "values": [
          "video"
        ]
      }
    ]
  ]
}
```


## DeleteConnectionForwardingFilter

*バージョン 2023.1.0 で追加。*

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

指定したチャネルの特定コネクションの転送フィルターを削除します。

> **注意**
>
> この API を実行するには事前に指定したコネクション単位の転送フィルターが作成されている必要があります

* - キー
  - 型
* - channel_id
  - string
* - connection_id
  - string
* - name (オプション)
  - string (最大 255 バイト)

- `name` はマルチ転送フィルター機能が有効になっている場合に指定します

```
$ curl -sS \
    -X POST \
    http://127.0.0.1:3000/ \
    -H "x-sora-target: Sora_20230628.DeleteConnectionForwardingFilter" \
    --json '{"channel_id":"sora","connection_id":"T9J5FM3NTH6JH4JKFGTSHB1BA0"}' \
    | jq .
{
  "channel_id": "sora",
  "connection_id": "EQ13WT731S1EK452YRJVFGYAY8"
}
```