# シグナリング通知メタデータ拡張 API


## ListSignalingNotifyMetadata

**x-sora-target**: Sora_20201124.ListSignalingNotifyMetadata

指定したチャネルのすべての接続のメタデータをリストで返します。リストの中には `connection_id` と `bundle_id` と `client_id` と `metadata` をキーとしたオブジェクトがリストで入ってきます。順番保証はしません。

* - キー
  - 型
* - channel_id
  - string

```console
$ curl -sS \
    -X POST \
    http://127.0.0.1:3000/ \
    -H "x-sora-target: Sora_20201124.ListSignalingNotifyMetadata" \
    --json '{"channel_id":"sora"}' \
    | jq .
[
    {
        "client_id": "V3Q452QQBD5TQ6ZQDMTEDKA07C",
        "bundle_id": "V3Q452QQBD5TQ6ZQDMTEDKA07C",
        "connection_id": "V3Q452QQBD5TQ6ZQDMTEDKA07C",
        "metadata": {
            "abc": 10
        }
    }
]
```


## GetSignalingNotifyMetadata

**x-sora-target**: Sora_20201124.GetSignalingNotifyMetadata

指定した接続のメタデータを取得します。

* - キー
  - 型
* - channel_id
  - string
* - connection_id
  - string

```console
$ curl -sS \
    -X POST \
    http://127.0.0.1:3000/ \
    -H "x-sora-target: Sora_20201124.GetSignalingNotifyMetadata" \
    --json '{"channel_id":"sora","connection_id":"0FQE5EA5YN3FS13P01QZ1JG8R0"}' \
    | jq .
{
    "abc": "efg"
}
```


## PutSignalingNotifyMetadata

**x-sora-target**: Sora_20201124.PutSignalingNotifyMetadata

指定した接続のメタデータを作成します。

* - キー
  - 型
* - channel_id
  - string
* - connection_id
  - string
* - metadata
  - object
* - push (オプション)
  - boolean

指定した接続のメタデータを作成します。メタデータがすでにあった場合は更新します。
追加したあとのメタデータが値として返ってきます。

```console
$ curl -sS \
    -X POST \
    http://127.0.0.1:3000/ \
    -H "x-sora-target: Sora_20201124.PutSignalingNotifyMetadata" \
    --json '{"channel_id":"sora","connection_id":"0FQE5EA5YN3FS13P01QZ1JG8R0","metadata":{"abc":"efg"},"push":true}' \
    | jq .
{
    "abc": "efg"
}
```

push を有効にした場合は、そのチャネルのすべてのクライアントに以下のようなプッシュ通知が送られます。

```javascript
{
    "type": "push",
    "data": {
        "action": "PutMetadata",
        "connection_id": "0FQE5EA5YN3FS13P01QZ1JG8R0",
        "metadata": {"abc": "efg"},
        "type": "signaling_notify_metadata_ext"
    }
}
```

- action- "PutMetadata" 固定
- connection_id- シグナリング通知メタデータの項目が変更された接続の ID
- metadata- 作成、または更新したメタデータ


## DeleteSignalingNotifyMetadata

**x-sora-target**: Sora_20201124.DeleteSignalingNotifyMetadata

指定した接続のメタデータを削除します。

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

指定した接続のメタデータを削除します。メタデータが空だったとしてもエラーにはなりません。
削除される **まえ** のメタデータが値として返ってきます。

```console
$ curl -sS \
    -X POST \
    http://127.0.0.1:3000/ \
    -H "x-sora-target: Sora_20201124.DeleteSignalingNotifyMetadata" \
    --json '{"channel_id":"sora","connection_id":"0FQE5EA5YN3FS13P01QZ1JG8R0","push":true}' \
    | jq .
{
    "abc": "efg"
}
```

push を有効にした場合は、そのチャネルのすべてのクライアントに以下のようなプッシュ通知が送られます。

```javascript
{
    "type": "push",
    "data": {
        "action": "DeleteMetadata",
        "connection_id": "0FQE5EA5YN3FS13P01QZ1JG8R0",
        "metadata": {"abc": "efg"},
        "type": "signaling_notify_metadata_ext"
    }
}
```

- action- "DeleteMetadata" 固定
- connection_id- シグナリング通知メタデータの項目が変更された接続の ID
- metadata- 削除したメタデータ


## PutSignalingNotifyMetadataItem

**x-sora-target**: Sora_20201124.PutSignalingNotifyMetadataItem

指定した接続のメタデータ項目を作成または更新します。

* - キー
  - 型
* - channel_id
  - string
* - connection_id
  - string
* - key
  - string
* - value
  - json
* - push (オプション)
  - boolean

key/value で指定したメタデータ項目を追加します。その項目が既にあった場合は更新します。
追加したあとのメタデータが値として返ってきます。

```console
$ curl -sS \
    -X POST \
    http://127.0.0.1:3000/ \
    -H "x-sora-target: Sora_20201124.PutSignalingNotifyMetadataItem" \
    --json '{"channel_id":"sora","connection_id":"0FQE5EA5YN3FS13P01QZ1JG8R0","key":"abc","value":"efg","push":true}' \
    | jq .
{
    "abc": "efg"
}
```

push を有効にした場合は、そのチャネルのすべてのクライアントに以下のようなプッシュ通知が送られます。

```javascript
{
    "type": "push",
    "data": {
        "action": "PutMetadataItem",
        "connection_id": "0FQE5EA5YN3FS13P01QZ1JG8R0",
        "key": "abc",
        "value": "efg",
        "type": "signaling_notify_metadata_ext"
    }
}
```

- action- "PutMetadataItem" 固定
- connection_id- シグナリング通知メタデータの項目が変更された接続の ID
- key- シグナリング通知メタデータの項目が変更されたキー
- value- シグナリング通知メタデータの項目が変更されたバリュー


## DeleteSignalingNotifyMetadataItem

**x-sora-target**: Sora_20201124.DeleteSignalingNotifyMetadataItem

指定した接続のメタデータ項目を削除します。

* - キー
  - 型
* - channel_id
  - string
* - connection_id
  - string
* - key
  - string
* - push (オプション)
  - boolean

key で指定したメタデータ項目を削除します。その項目がなかったとしてもエラーにはなりません。
削除された **あと** のメタデータが値として返ってきます。

もしその項目がなかった場合は現状のメタデータが値として返ってきます。

```console
$ curl -sS \
    -X POST \
    http://127.0.0.1:3000/ \
    -H "x-sora-target: Sora_20201124.DeleteSignalingNotifyMetadataItem" \
    --json '{"channel_id":"sora","connection_id":"0FQE5EA5YN3FS13P01QZ1JG8R0","key":"abc","push":true}' \
    | jq .
{}
```

push を有効にした場合は、そのチャネルのすべてのクライアントに以下のようなプッシュ通知が送られます。

```javascript
{
    "type": "push",
    "data": {
        "action": "DeleteMetadataItem",
        "connection_id": "0FQE5EA5YN3FS13P01QZ1JG8R0",
        "key": "abc",
        "type": "signaling_notify_metadata_ext"
    }
}
```

- action- "DeleteMetadataItem" 固定
- connection_id- シグナリング通知メタデータの項目が変更された接続の ID
- key- シグナリング通知メタデータの項目が変更されたキー