実験的 API

概要

実験的 API とは、今後のアップデートで互換性を保証しない API です。

将来的には正式版としてリリースするか、または非推奨となり廃止するかのどちらかです。

シグナリング API

注意

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

ListChannels

x-sora-target:

Sora_20201013.ListChannels

全てのチャネル一覧を取得します。

$ http POST 127.0.0.1:3000/ \
    x-sora-target:Sora_20201013.ListChannels \
    -vvv
POST / HTTP/1.1
Accept: */*
Accept-Encoding: gzip, deflate
Connection: keep-alive
Content-Length: 0
Host: 127.0.0.1:3000
User-Agent: HTTPie/2.2.0
x-sora-target: Sora_20201013.ListChannels



HTTP/1.1 200 OK
access-control-allow-headers: Origin, X-Requested-With, Content-Type, Accept, x-sora-target
access-control-allow-methods: POST, OPTIONS
access-control-allow-origin: http://127.0.0.1:5000
access-control-max-age: 1000
content-length: 120
content-type: application/json
date: Thu, 26 Nov 2020 04:16:17 GMT
server: Cowboy

[
    {
        "channel_id": "sora",
        "multistream": true,
        "spotlight": false
    },
    {
        "channel_id": "akane",
        "multistream": true,
        "spotlight": false
    }
]

クラスター API

注意

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

JoinCluster

x-sora-target:

Sora_20211215.JoinCluster

指定したクラスターノードに参加します。

すでにクラスターが存在している場合には、そこに参加しているノードのいずれかを contact_node_name で指定してください。 クラスターに参加していれば、どのノードでもかまいません。 新規にクラスターを作成する場合には、起動中の任意のノードを contact_node_name に指定して大丈夫です。

事前にクラスターの参加ノードが判明している場合には sora.confcontact_node_name_list に指定しておくと、 それらのノードに対して、起動時に自動で JoinCluster を試行するようになります。

キー

contact_node_name

string

$ http POST 127.0.0.1:3000/ x-sora-target:Sora_20211215.JoinCluster \
    contact_node_name=node-03@10.99.0.8 \
    -vvv
POST / HTTP/1.1
Accept: application/json, */*
Accept-Encoding: gzip, deflate
Connection: keep-alive
Content-Length: 42
Content-Type: application/json
Host: 127.0.0.1:3000
User-Agent: HTTPie/1.0.3
x-sora-target: Sora_20211215.JoinCluster

{
    "contact_node_name": "node-03@192.0.2.8"
}

HTTP/1.1 200 OK
access-control-allow-headers: Origin, X-Requested-With, Content-Type, Accept, x-sora-target
access-control-allow-methods: POST, OPTIONS
access-control-allow-origin: http://127.0.0.1:5000
access-control-max-age: 1000
content-length: 116
content-type: application/json
date: Tue, 16 Nov 2021 09:28:11 GMT
server: Cowboy

{
    "node_name_list": [
        "node-02@192.0.2.7",
        "node-03@192.0.2.8",
        "node-04@192.0.2.9",
        "node-05@192.0.2.10",
        "node-01@192.0.2.5"
    ]
}

ListClusterNodes

x-sora-target:

Sora_20211215.ListClusterNodes

クラスターのノード一覧を表示します。

キー

include_all_known_nodes (オプション)

boolean

include_all_known_nodestrue に指定することで、接続していないノードも含め、そのノードが知っているすべてのノード一覧を返します。 接続していないノードについては node_nameconnected のみが結果に含まれます。

レスポンス JSON

キー

内容

external_api_url

string

sora.confexternal_api_url

epoch

integer

再起動回数

license_max_nodes

integer

ライセンスの最大ノード数

license_max_connections

integer

ライセンスの最大同時接続数

license_serial_code

string

ライセンスのシリアルコード

license_type

string

ライセンスのタイプ

member_since

string

クラスターに参加した時刻 (RFC3339 UTC マイクロ秒)

node_name

string

sora.confnode_name

connected

boolean

API 実行ノードと正常に接続できているかどうか

external_signaling_url

string

sora.confexternal_signaling_url

version

string

Sora のバージョン

mode

string

モード (normal / block_new_session / block_new_connection / initial)

$ http POST 127.0.0.1:3000/ \
    x-sora-target:Sora_20211215.ListClusterNodes \
    -vvv
POST / HTTP/1.1
Accept: */*
Accept-Encoding: gzip, deflate
Connection: keep-alive
Content-Length: 0
Host: 127.0.0.1:3000
User-Agent: HTTPie/1.0.3
x-sora-target: Sora_20211215.ListClusterNodes



HTTP/1.1 200 OK
access-control-allow-headers: Origin, X-Requested-With, Content-Type, Accept, x-sora-target
access-control-allow-methods: POST, OPTIONS
access-control-allow-origin: http://127.0.0.1:5000
access-control-max-age: 1000
content-length: 1753
content-type: application/json
date: Tue, 16 Nov 2021 09:22:16 GMT
server: Cowboy

[
    {
        "external_api_url": "http://192.0.2.9:3000/",
        "epoch": 1,
        "license_max_connections": 500,
        "license_serial_code": "ABCDEF-SRA-E004-203801-500",
        "license_type": "Experimental",
        "member_since": "2021-11-16T09:04:18.018150Z",
        "node_name": "node-04@192.0.2.9",
        "mode": "normal",
        "connected": true,
        "external_signaling_url": "wss://node-04.example.com/signaling",
        "version": "2021.2"
    },
    {
        "external_api_url": "http://192.0.2.8:3000/",
        "epoch": 2,
        "license_max_connections": 500,
        "license_serial_code": "ABCDEF-SRA-E003-203801-500",
        "license_type": "Experimental",
        "member_since": "2021-11-16T08:40:17.194809Z",
        "node_name": "node-03@192.0.2.8",
        "mode": "normal",
        "connected": true,
        "external_signaling_url": "wss://node-03.example.com/signaling",
        "version": "2021.2"
    },
    {
        "api_url": "http://192.0.2.7:3000/",
        "epoch": 2,
        "license_max_connections": 500,
        "license_serial_code": "ABCDEF-SRA-E002-203801-500",
        "license_type": "Experimental",
        "member_since": "2021-11-16T08:41:12.450300Z",
        "node_name": "node-02@192.0.2.7",
        "mode": "normal",
        "connected": true,
        "external_signaling_url": "wss://node-02.example.com/signaling",
        "version": "2021.2"
    },
    {
        "external_api_url": "http://192.0.2.5:3000/",
        "epoch": 1,
        "license_max_connections": 500,
        "license_serial_code": "ABCDEF-SRA-E001-203801-500",
        "license_type": "Experimental",
        "member_since": "2021-11-16T08:23:02.488711Z",
        "node_name": "node-01@192.0.2.5",
        "mode": "normal",
        "connected": true,
        "external_signaling_url": "wss://node-01.example.com/signaling",
        "version": "2021.2"
    },
    {
        "external_api_url": "http://192.0.2.10:3000/",
        "epoch": 2,
        "license_max_connections": 500,
        "license_serial_code": "ABCDEF-SRA-E005-203801-500",
        "license_type": "Experimental",
        "member_since": "2021-11-16T09:07:08.272556Z",
        "node_name": "node-05@192.0.2.10",
        "mode": "normal",
        "connected": true,
        "external_signaling_url": "wss://node-05.example.com/signaling",
        "version": "2021.2"
    }
]

ListClusterChannels

x-sora-target:

Sora_20211215.ListClusterChannels

レスポンス JSON

キー

内容

channel_id

string

チャネル ID

node_in_charge

string

担当ノード

node_in_charge_epoch

integer

担当ノードへ割り当てられた際のクラスターへの参加回数

node_in_charge_epoch_stale

boolean

担当ノードが無効かどうか

node_in_charge_connected

boolean

担当ノードが API 実行ノードと正常に接続できているかどうか

$ http POST 127.0.0.1:3000/ \
    x-sora-target:Sora_20211215.ListClusterChannels \
    -vvv
POST / HTTP/1.1
Accept: */*
Accept-Encoding: gzip, deflate
Connection: keep-alive
Content-Length: 0
Host: 127.0.0.1:3000
User-Agent: HTTPie/1.0.3
x-sora-target: Sora_20211215.ListClusterChannels



HTTP/1.1 200 OK
access-control-allow-headers: Origin, X-Requested-With, Content-Type, Accept, x-sora-target
access-control-allow-methods: POST, OPTIONS
access-control-allow-origin: http://127.0.0.1:5000
access-control-max-age: 1000
content-length: 796
content-type: application/json
date: Tue, 16 Nov 2021 09:34:15 GMT
server: Cowboy

[
    {
        "channel_id": "tobi",
        "node_in_charge": "node-05@192.0.2.10",
        "node_in_charge_epoch": 2,
        "node_in_charge_epoch_stale": false,
        "node_in_charge_connected": true
    },
    {
        "channel_id": "sora",
        "node_in_charge": "node-01@192.0.2.5",
        "node_in_charge_epoch": 2,
        "node_in_charge_epoch_stale": false,
        "node_in_charge_connected": true
    },
    {
        "channel_id": "kohaku",
        "node_in_charge": "node-02@192.0.2.7",
        "node_in_charge_epoch": 2,
        "node_in_charge_epoch_stale": false,
        "node_in_charge_connected": true
    },
    {
        "channel_id": "hisui",
        "node_in_charge": "node-04@192.0.2.9",
        "node_in_charge_epoch": 1,
        "node_in_charge_epoch_stale": false,
        "node_in_charge_connected": true
    },
    {
        "channel_id": "zakuro",
        "node_in_charge": "node-01@192.0.2.5",
        "node_in_charge_epoch": 2,
        "node_in_charge_epoch_stale": false,
        "node_in_charge_connected": true
    }
]

PurgeClusterNode

x-sora-target:

Sora_20211215.PurgeClusterNode

復旧がすぐには難しい障害が発生したノードや、縮退し再参加する予定が無いノードの情報をクラスターから消去します。

この API は 1 クラスターにつき 1 回実行すればすべての参加ノードから指定したノード情報が消去されます。

キー

target_node_name

string

$ http POST 127.0.0.1:3000/ x-sora-target:Sora_20220629.PurgeClusterNode \
    target_node_name=node-03@192.0.2.5 \
    -vvv
POST / HTTP/1.1
Accept: application/json, */*;q=0.5
Accept-Encoding: gzip, deflate, br
Connection: keep-alive
Content-Length: 39
Content-Type: application/json
Host: 127.0.0.1:3000
User-Agent: HTTPie/3.2.1
x-sora-target: Sora_20220629.PurgeClusterNode

{
    "target_node_name": "node-03@192.0.2.5"
}


HTTP/1.1 200 OK
access-control-allow-headers: Origin, X-Requested-With, Content-Type, Accept, x-sora-target
access-control-allow-methods: POST, OPTIONS
access-control-allow-origin: http://127.0.0.1:3000
access-control-max-age: 1000
content-length: 38
content-type: application/json
date: Sun, 12 Jun 2022 03:13:42 GMT
server: Cowboy

{
    "target_node_name": "node-03@192.0.2.5"
}
 $ http POST 127.0.0.1:3001/ x-sora-target:Sora_20220629.PurgeClusterNode \
     target_node_name=node-03@192.0.2.5 \
         -vvv
 POST / HTTP/1.1
 Accept: application/json, */*;q=0.5
 Accept-Encoding: gzip, deflate, br
 Connection: keep-alive
 Content-Length: 39
 Content-Type: application/json
 Host: 127.0.0.1:3000
 User-Agent: HTTPie/3.2.1
 x-sora-target: Sora_20220629.PurgeClusterNode

 {
     "target_node_name": "node-03@192.0.2.5"
 }


 HTTP/1.1 400 Bad Request
 access-control-allow-headers: Origin, X-Requested-With, Content-Type, Accept, x-sora-target
 access-control-allow-methods: POST, OPTIONS
 access-control-allow-origin: http://127.0.0.1:3000
 access-control-max-age: 1000
 content-length: 79
 content-type: application/json
 date: Sun, 12 Jun 2022 03:13:29 GMT
 server: Cowboy

 {
     "error_reason": {
         "target_node": "node-03@192.0.2.5"
     },
     "error_type": "NODE-IS-ALIVE"
 }

モード API

注意

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

ChangeMode

x-sora-target:

Sora_20211215.ChangeMode

Sora のモードを変更します。

キー

mode

string

mode はすべての新規コネクションを受け入れる normal 、新規セッションの受け入れを停止する block_new_session と新規コネクションの受け入れを停止する block_new_connection が指定可能です。

$ http POST 127.0.0.1:3000/ \
    x-sora-target:Sora_20211215.ChangeMode \
    mode=block_new_connection \
    -vvv
POST / HTTP/1.1
Accept: application/json, */*
Accept-Encoding: gzip, deflate
Connection: keep-alive
Content-Length: 32
Content-Type: application/json
Host: 127.0.0.1:3000
User-Agent: HTTPie/1.0.3
x-sora-target: Sora_20211215.ChangeMode

{
    "mode": "block_new_connection"
}

HTTP/1.1 200 OK
access-control-allow-headers: Origin, X-Requested-With, Content-Type, Accept, x-sora-target
access-control-allow-methods: POST, OPTIONS
access-control-allow-origin: http://127.0.0.1:5000
access-control-max-age: 1000
content-length: 31
content-type: application/json
date: Tue, 16 Nov 2021 09:36:35 GMT
server: Cowboy

{
    "mode": "block_new_connection"
}

GetMode

x-sora-target:

Sora_20211215.GetMode

Sora のモードを取得します。

$ http POST 127.0.0.1:3000/ \
    x-sora-target:Sora_20211215.GetMode \
    -vvv
POST / HTTP/1.1
Accept: */*
Accept-Encoding: gzip, deflate
Connection: keep-alive
Content-Length: 0
Host: 127.0.0.1:3000
User-Agent: HTTPie/1.0.3
x-sora-target: Sora_20211215.GetMode



HTTP/1.1 200 OK
access-control-allow-headers: Origin, X-Requested-With, Content-Type, Accept, x-sora-target
access-control-allow-methods: POST, OPTIONS
access-control-allow-origin: http://127.0.0.1:5000
access-control-max-age: 1000
content-length: 17
content-type: application/json
date: Tue, 16 Nov 2021 09:35:26 GMT
server: Cowboy

{
    "mode": "normal"
}

RTP 転送 API

注意

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

指定したチャネル ID の配信している映像または音声の RTP を指定した IP アドレスとポートに送信します。

StartForwardingRtp

x-sora-target:

Sora_20170814.StartForwardingRtp

指定したチャネルの RTP の転送を開始します。

キー

channel_id

string

connection_id (オプション)

string

ip_address

string

audio_port

integer

video_port

integer

マルチストリームの音声や映像を転送する場合は connection_id を指定してください。

$ http POST 127.0.0.1:3000/ \
    x-sora-target:Sora_20170814.StartForwardingRtp \
    channel_id=sora \
    ip_address=127.0.0.1 \
    audio_port:=60001 \
    video_port:=60003 \
    -vvv

POST / HTTP/1.1
Accept: application/json
Accept-Encoding: gzip, deflate
Connection: keep-alive
Content-Length: 93
Content-Type: application/json
Host: 127.0.0.1:3000
User-Agent: HTTPie/0.9.2
x-sora-target: Sora_20170814.StartForwardingRtp

{
    "audio_port": 60001,
    "channel_id": "sora",
    "ip_address": "127.0.0.1",
    "video_port": 60003
}

HTTP/1.1 200 OK
access-control-allow-headers: Origin, X-Requested-With, Content-Type, Accept, x-sora-target
access-control-allow-methods: POST, OPTIONS
access-control-allow-origin: http://127.0.0.1:5000
access-control-max-age: 1000
content-length: 262
content-type: application/json
date: Wed, 30 Aug 2017 02:08:50 GMT
server: Cowboy

{
    "sdp": "v=0\r\no=- 0 0 IN IP4 0.0.0.0\r\ns=-\r\nt=0 0\r\nm=audio 60001 RTP/SAVPF 109\r\nc=IN IP4 127.0.0.1\r\na=rtpmap:109 opus/48000/2\r\nm=video 60003 RTP/SAVPF 120\r\nc=IN IP4 127.0.0.1\r\na=rtpmap:120 VP9/90000\r\na=fmtp:120 max-fs=12288;max-fr=60\r\n"
}

StopForwardingRtp

x-sora-target:

Sora_20170814.StopForwardingRtp

指定したチャネルの RTP の転送を停止します。

キー

channel_id

string

connection_id (オプション)

string

マルチストリームの音声や映像の転送を停止する場合は connection_id を指定してください。

$ http POST 127.0.0.1:3000/ \
    x-sora-target:Sora_20170814.StopForwardingRtp \
    channel_id=sora \
    -vvv

POST / HTTP/1.1
Accept: application/json, */*
Accept-Encoding: gzip, deflate
Connection: keep-alive
Content-Length: 22
Content-Type: application/json
Host: 127.0.0.1:3000
User-Agent: HTTPie/0.9.9
x-sora-target: Sora_20170814.StopForwardingRtp

{
    "channel_id": "sora"
}

HTTP/1.1 200 OK
access-control-allow-headers: Origin, X-Requested-With, Content-Type, Accept, x-sora-target
access-control-allow-methods: POST, OPTIONS
access-control-allow-origin: http://127.0.0.1:5000
access-control-max-age: 1000
content-length: 21
content-type: application/json
date: Fri, 25 Aug 2017 13:32:48 GMT
server: Cowboy

{
    "channel_id": "sora"
}

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

注意

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

ListSignalingNotifyMetadata

x-sora-target:

Sora_20201124.ListSignalingNotifyMetadata

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

キー

channel_id

string

$ http POST 127.0.0.1:3000/ \
    x-sora-target:Sora_20201124.ListSignalingNotifyMetadata \
    channel_id=sora \
    -vvv
POST / HTTP/1.1
Accept: application/json, */*;q=0.5
Accept-Encoding: gzip, deflate
Connection: keep-alive
Content-Length: 22
Content-Type: application/json
Host: 127.0.0.1:3000
User-Agent: HTTPie/2.2.0
x-sora-target: Sora_20201124.ListSignalingNotifyMetadata

{
    "channel_id": "sora"
}

HTTP/1.1 200 OK
access-control-allow-headers: Origin, X-Requested-With, Content-Type, Accept, x-sora-target
access-control-allow-methods: POST, OPTIONS
access-control-allow-origin: http://127.0.0.1:5000
access-control-max-age: 1000
content-length: 111
content-type: application/json
date: Thu, 26 Nov 2020 03:45:25 GMT
server: Cowboy

[
    {
        "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

$ http POST 127.0.0.1:3000/ \
    x-sora-target:Sora_20201124.GetSignalingNotifyMetadata \
    channel_id=sora \
    connection_id=0FQE5EA5YN3FS13P01QZ1JG8R0 \
    -vvv
POST / HTTP/1.1
Accept: application/json, */*;q=0.5
Accept-Encoding: gzip, deflate
Connection: keep-alive
Content-Length: 69
Content-Type: application/json
Host: 127.0.0.1:3000
User-Agent: HTTPie/2.2.0
x-sora-target: Sora_20201124.GetSignalingNotifyMetadata

{
    "channel_id": "sora",
    "connection_id": "0FQE5EA5YN3FS13P01QZ1JG8R0"
}

HTTP/1.1 200 OK
access-control-allow-headers: Origin, X-Requested-With, Content-Type, Accept, x-sora-target
access-control-allow-methods: POST, OPTIONS
access-control-allow-origin: http://127.0.0.1:5000
access-control-max-age: 1000
content-length: 13
content-type: application/json
date: Thu, 26 Nov 2020 03:48:44 GMT
server: Cowboy

{
    "abc": "efg"
}

PutSignalingNotifyMetadata

x-sora-target:

Sora_20201124.PutSignalingNotifyMetadata

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

キー

channel_id

string

connection_id

string

metadata

object

push (オプション)

boolean

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

$ http POST 127.0.0.1:3000/ \
    x-sora-target:Sora_20201124.PutSignalingNotifyMetadata \
    channel_id=sora \
    connection_id=0FQE5EA5YN3FS13P01QZ1JG8R0 \
    metadata:='{"abc": "efg"}' \
    -vvv
POST / HTTP/1.1
Accept: application/json, */*;q=0.5
Accept-Encoding: gzip, deflate
Connection: keep-alive
Content-Length: 97
Content-Type: application/json
Host: 127.0.0.1:3000
User-Agent: HTTPie/2.2.0
x-sora-target: Sora_20201124.PutSignalingNotifyMetadata

{
    "channel_id": "sora",
    "connection_id": "0FQE5EA5YN3FS13P01QZ1JG8R0",
    "metadata": {
        "abc": "efg"
    }
}

HTTP/1.1 200 OK
access-control-allow-headers: Origin, X-Requested-With, Content-Type, Accept, x-sora-target
access-control-allow-methods: POST, OPTIONS
access-control-allow-origin: http://127.0.0.1:5000
access-control-max-age: 1000
content-length: 13
content-type: application/json
date: Thu, 26 Nov 2020 03:47:52 GMT
server: Cowboy

{
    "abc": "efg"
}

DeleteSignalingNotifyMetadata

x-sora-target:

Sora_20201124.DeleteSignalingNotifyMetadata

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

キー

channel_id

string

connection_id

string

push (オプション)

boolean

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

$ http POST 127.0.0.1:3000/ \
    x-sora-target:Sora_20201124.DeleteSignalingNotifyMetadata \
    channel_id=sora \
    connection_id=0FQE5EA5YN3FS13P01QZ1JG8R0 \
    -vvv
POST / HTTP/1.1
Accept: application/json, */*;q=0.5
Accept-Encoding: gzip, deflate
Connection: keep-alive
Content-Length: 69
Content-Type: application/json
Host: 127.0.0.1:3000
User-Agent: HTTPie/2.2.0
x-sora-target: Sora_20201124.DeleteSignalingNotifyMetadata

{
    "channel_id": "sora",
    "connection_id": "0FQE5EA5YN3FS13P01QZ1JG8R0"
}

HTTP/1.1 200 OK
access-control-allow-headers: Origin, X-Requested-With, Content-Type, Accept, x-sora-target
access-control-allow-methods: POST, OPTIONS
access-control-allow-origin: http://127.0.0.1:5000
access-control-max-age: 1000
content-length: 13
content-type: application/json
date: Thu, 26 Nov 2020 03:51:48 GMT
server: Cowboy

{
    "abc": "efg"
}

PutSignalingNotifyMetadataItem

x-sora-target:

Sora_20201124.PutSignalingNotifyMetadataItem

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

キー

channel_id

string

connection_id

string

key

string

value

json

push (オプション)

boolean

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

$ http POST 127.0.0.1:3000/ \
    x-sora-target:Sora_20201124.PutSignalingNotifyMetadataItem \
    channel_id=sora \
    connection_id=0FQE5EA5YN3FS13P01QZ1JG8R0 \
    key=abc \
    value=efg \
    -vvv
POST / HTTP/1.1
Accept: application/json, */*;q=0.5
Accept-Encoding: gzip, deflate
Connection: keep-alive
Content-Length: 99
Content-Type: application/json
Host: 127.0.0.1:3000
User-Agent: HTTPie/2.2.0
x-sora-target: Sora_20201124.PutSignalingNotifyMetadataItem

{
    "channel_id": "sora",
    "connection_id": "0FQE5EA5YN3FS13P01QZ1JG8R0",
    "key": "abc",
    "value": "efg"
}

HTTP/1.1 200 OK
access-control-allow-headers: Origin, X-Requested-With, Content-Type, Accept, x-sora-target
access-control-allow-methods: POST, OPTIONS
access-control-allow-origin: http://127.0.0.1:5000
access-control-max-age: 1000
content-length: 13
content-type: application/json
date: Thu, 26 Nov 2020 03:51:48 GMT
server: Cowboy

{
    "abc": "efg"
}

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

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

    • 呼ばれた API 名

  • connection_id

    • シグナリング通知メタデータの項目が変更された接続の ID

  • key

    • シグナリング通知メタデータの項目が変更されたキー

  • value

    • シグナリング通知メタデータの項目が変更されたバリュー

DeleteSignalingNotifyMetadataItem

x-sora-target:

Sora_20201124.DeleteSignalingNotifyMetadataItem

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

キー

channel_id

string

connection_id

string

key

string

push (オプション)

boolean

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

$ http POST 127.0.0.1:3000/ \
    x-sora-target:Sora_20201124.DeleteSignalingNotifyMetadataItem \
    channel_id=sora \
    connection_id=0FQE5EA5YN3FS13P01QZ1JG8R0 \
    key=abc \
    push:=true \
    -vvv
POST / HTTP/1.1
Accept: application/json, */*;q=0.5
Accept-Encoding: gzip, deflate
Connection: keep-alive
Content-Length: 97
Content-Type: application/json
Host: 127.0.0.1:3000
User-Agent: HTTPie/2.2.0
x-sora-target: Sora_20201124.DeleteSignalingNotifyMetadataItem

{
    "channel_id": "sora",
    "connection_id": "0FQE5EA5YN3FS13P01QZ1JG8R0",
    "key": "abc",
    "push": true
}

HTTP/1.1 200 OK
access-control-allow-headers: Origin, X-Requested-With, Content-Type, Accept, x-sora-target
access-control-allow-methods: POST, OPTIONS
access-control-allow-origin: http://127.0.0.1:5000
access-control-max-age: 1000
content-length: 2
content-type: application/json
date: Thu, 26 Nov 2020 03:54:50 GMT
server: Cowboy

{}

RTP ストリーム停止/再開 API

注意

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

PauseRtpStream

現時点では映像のみを停止します

x-sora-target:

Sora_20200401.PauseRtpStream

指定した接続からのストリームを停止します。

この API はマルチストリーム、サイマルキャスト、スポットライトで利用できます。

キー

channel_id

string

recv_connection_id

string

send_connection_id

string

  • recv_connection_id

    • RTP ストリームの受信を停止する接続の connection_id を指定します

  • send_connection_id

    • 受信を停止する RTP ストリームを配信している接続の connection_id を指定します

映像自体は Sora までは届いていますが、実際の配信が一時停止されるという仕組みになっています。

$ http POST 127.0.0.1:3000/ x-sora-target:Sora_20200401.PauseRtpStream \
      channel_id=sora \
      recv_connection_id=VTGYC92AZX6M72K860BPREFTMC \
      send_connection_id=3X0W1C23KS1TQAAYMKA9TXJS4G \
      -vvv
POST / HTTP/1.1
Accept: application/json, */*
Accept-Encoding: gzip, deflate
Connection: keep-alive
Content-Length: 121
Content-Type: application/json
Host: 127.0.0.1:3000
User-Agent: HTTPie/2.0.0
x-sora-target: Sora_20200401.PauseRtpStream

{
    "channel_id": "sora",
    "recv_connection_id": "VTGYC92AZX6M72K860BPREFTMC",
    "send_connection_id": "3X0W1C23KS1TQAAYMKA9TXJS4G"
}

HTTP/1.1 200 OK
access-control-allow-headers: Origin, X-Requested-With, Content-Type, Accept, x-sora-target
access-control-allow-methods: POST, OPTIONS
access-control-allow-origin: http://127.0.0.1:5000
access-control-max-age: 1000
content-length: 121
content-type: application/json
date: Thu, 16 Apr 2020 02:06:39 GMT
server: Cowboy

{
    "channel_id": "sora",
    "recv_connection_id": "VTGYC92AZX6M72K860BPREFTMC",
    "send_connection_id": "3X0W1C23KS1TQAAYMKA9TXJS4G"
}

ResumeRtpStream

x-sora-target:

Sora_20200401.ResumeRtpStream

指定した接続からのストリームを再開します。

この API はマルチストリーム、サイマルキャスト、スポットライトで利用できます。

キー

channel_id

string

recv_connection_id

string

send_connection_id

string

  • recv_connection_id

    • RTP ストリームの受信を再開する接続の connection_id を指定します

  • send_connection_id

    • 受信を停止している RTP ストリームを配信している接続の connection_id を指定します

$ http POST 127.0.0.1:3000/ x-sora-target:Sora_20200401.ResumeRtpStream \
      channel_id=sora \
      recv_connection_id=VTGYC92AZX6M72K860BPREFTMC \
      send_connection_id=3X0W1C23KS1TQAAYMKA9TXJS4G \
      -vvv
POST / HTTP/1.1
Accept: application/json, */*
Accept-Encoding: gzip, deflate
Connection: keep-alive
Content-Length: 121
Content-Type: application/json
Host: 127.0.0.1:3000
User-Agent: HTTPie/2.0.0
x-sora-target: Sora_20200401.ResumeRtpStream

{
    "channel_id": "sora",
    "recv_connection_id": "VTGYC92AZX6M72K860BPREFTMC",
    "send_connection_id": "3X0W1C23KS1TQAAYMKA9TXJS4G"
}

HTTP/1.1 200 OK
access-control-allow-headers: Origin, X-Requested-With, Content-Type, Accept, x-sora-target
access-control-allow-methods: POST, OPTIONS
access-control-allow-origin: http://127.0.0.1:5000
access-control-max-age: 1000
content-length: 121
content-type: application/json
date: Thu, 16 Apr 2020 02:07:27 GMT
server: Cowboy

{
    "channel_id": "sora",
    "recv_connection_id": "VTGYC92AZX6M72K860BPREFTMC",
    "send_connection_id": "3X0W1C23KS1TQAAYMKA9TXJS4G"
}

ListPauseRtpStreams

x-sora-target:

Sora_20200401.ListPauseRtpStreams

指定したチャネルの停止しているストリーム一覧を返します。

キー

channel_id

string

$ http POST 127.0.0.1:3000/ x-sora-target:Sora_20200401.ListPauseRtpStreams \
    channel_id=sora \
    -vvv
POST / HTTP/1.1
Accept: application/json, */*
Accept-Encoding: gzip, deflate
Connection: keep-alive
Content-Length: 22
Content-Type: application/json
Host: 127.0.0.1:3000
User-Agent: HTTPie/2.0.0
x-sora-target: Sora_20200401.ListPauseRtpStreams

{
    "channel_id": "sora"
}

HTTP/1.1 200 OK
access-control-allow-headers: Origin, X-Requested-With, Content-Type, Accept, x-sora-target
access-control-allow-methods: POST, OPTIONS
access-control-allow-origin: http://127.0.0.1:5000
access-control-max-age: 1000
content-length: 111
content-type: application/json
date: Thu, 09 Apr 2020 07:10:18 GMT
server: Cowboy

[
    {
        "channel_id": "sora",
        "recv_connection_id": "G8AN156DSD3DBBN4P15VJ74QRW",
        "role": "sendrecv",
        "send_connection_id": "47YZ3NYNRN2CS5MW2W8V28W6QW"
    }
]

統計 API

注意

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

GetStatsReport

x-sora-target:

Sora_20171010.GetStatsReport

Sora が起動している間の Sora 全体の統計情報を取得することができます。この統計情報は Sora を止めたり再起動したりすることでクリアされますので注意してください。

レスポンス項目

  • version

    • sora のバージョン

  • total_connection_created

    • 現在までの接続が作成された数

  • total_connection_updated

    • 現在までの接続が更新された数

  • total_connection_destroyed

    • 現在までの接続が破棄された数

  • total_session_created

    • 現在までのセッションが作成された数

  • total_session_destroyed

    • 現在までのセッションが破棄された数

  • total_successful_connections

    • 現在までの接続が成功した数

  • total_ongoing_connections

    • 現在接続している数

  • total_failed_connections

    • 現在までの接続が失敗した数

  • total_duration_sec

    • 現在までの合計接続時間 (秒)

  • total_turn_udp_connections

    • 現在までの TURN-UDP での接続数

  • total_turn_tcp_connections

    • 現在までの TURN-TCP または TURN-TLS での接続数

  • total_received_invalid_turn_tcp_packet

    • 現在までの TURN-TCP でパースできないパケットが送られてきた数

  • average_duration_sec

    • 平均接続時間 (秒)

  • average_setup_time_msec

    • 平均セットアップ時間 (ミリ秒)

$ http POST 127.0.0.1:3000/ \
    x-sora-target:Sora_20171010.GetStatsReport \
    -vvv

POST / HTTP/1.1
Accept: */*
Accept-Encoding: gzip, deflate
Connection: keep-alive
Content-Length: 0
Host: 127.0.0.1:3000
User-Agent: HTTPie/0.9.9
x-sora-target: Sora_20171010.GetStatsReport



HTTP/1.1 200 OK
access-control-allow-headers: Origin, X-Requested-With, Content-Type, Accept, x-sora-target
access-control-allow-methods: POST, OPTIONS
access-control-allow-origin: http://127.0.0.1:5000
access-control-max-age: 1000
content-length: 172
content-type: application/json
date: Tue, 10 Oct 2017 10:23:22 GMT
server: Cowboy

{
    "version": "2022.1.0",
    "average_duration_sec": 127,
    "average_setup_time_msec": 358,
    "total_connection_created": 100,
    "total_connection_destroyed": 100,
    "total_connection_updated": 174,
    "total_session_created": 30,
    "total_session_destroyed": 30,
    "total_duration_sec": 12769,
    "total_failed_connections": 80,
    "total_ongoing_connections": 0,
    "total_successful_connections": 100,
    "total_received_invalid_turn_tcp_packet": 0,
    "total_turn_tcp_connections": 2,
    "total_turn_udp_connections": 98
}

ユーザーエージェント統計情報 API

注意

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

統計情報更新のタイミングについて

この統計情報は、クライアントからシグナリングで送信されてくる統計情報の最新の値を返します。 WebSocket 経由の場合は 5 秒間隔で更新され、DataChannel 経由の場合は 30 秒間隔で更新されます。

ListUserAgentStats

x-sora-target:

Sora_20211215.ListUserAgentStats

すべてのユーザーエージェント統計情報の一覧を取得する。

$ http POST 127.0.0.1:3000/ x-sora-target:Sora_20211215.ListUserAgentStats -vvv
POST / HTTP/1.1
Accept: */*
Accept-Encoding: gzip, deflate
Connection: keep-alive
Content-Length: 0
Host: 127.0.0.1:3000
User-Agent: HTTPie/2.4.0
x-sora-target: Sora_20211215.ListUserAgentStats



HTTP/1.1 200 OK
access-control-allow-headers: Origin, X-Requested-With, Content-Type, Accept, x-sora-target
access-control-allow-methods: POST, OPTIONS
access-control-allow-origin: http://127.0.0.1:5000
access-control-max-age: 1000
content-length: 30262
content-type: application/json
date: Sat, 13 Nov 2021 13:05:51 GMT
server: Cowboy

[
    {
        "channel_id": "sora",
        "connection_id": "FNRGZ8VFSN3R98DK7NBA38MFNR",
        "timestamp": "2021-11-13T13:05:33.264Z",
        "user_agent_stats": [
            {
                "audioLevel": 0,
                "id": "RTCAudioSource_1",
                "kind": "audio",
                "timestamp": 1636808733258.573,
                "totalAudioEnergy": 0,
                "totalSamplesDuration": 90.08000000000918,
                "trackIdentifier": "222a181f-d0fe-4434-b7a1-a8e05e3abbb4",
                "type": "media-source"
            }, ...
        ]
    },
    {
        "channel_id": "zakuro",
        "connection_id": "X019KW3ZT95WZ6T15S6HHTM59C",
        "timestamp": "2021-11-13T13:05:44.044Z",
        "user_agent_stats": [
            {
                "audioLevel": 0,
                "id": "RTCAudioSource_1",
                "kind": "audio",
                "timestamp": 1636808744029.488,
                "totalAudioEnergy": 0,
                "totalSamplesDuration": 31.070000000002057,
                "trackIdentifier": "9a84b996-d3ab-4cea-8131-04f96232dde5",
                "type": "media-source"
            }, ...
        ]
    }
]

ListChannelUserAgentStats

x-sora-target:

Sora_20211215.ListChannelUserAgentStats

指定したチャネルのユーザーエージェント統計情報の一覧を取得します。

キー

channel_id

string

$ http POST 127.0.0.1:3000/ x-sora-target:Sora_20211215.ListChannelUserAgentStats \
    channel_id=sora \
    -vvv
POST / HTTP/1.1
Accept: application/json, */*;q=0.5
Accept-Encoding: gzip, deflate
Connection: keep-alive
Content-Length: 22
Content-Type: application/json
Host: 127.0.0.1:3000
User-Agent: HTTPie/2.4.0
x-sora-target: Sora_20211215.ListChannelUserAgentStats

{
    "channel_id": "sora"
}


HTTP/1.1 200 OK
access-control-allow-headers: Origin, X-Requested-With, Content-Type, Accept, x-sora-target
access-control-allow-methods: POST, OPTIONS
access-control-allow-origin: http://127.0.0.1:5000
access-control-max-age: 1000
content-length: 30368
content-type: application/json
date: Sat, 13 Nov 2021 13:10:35 GMT
server: Cowboy

[
    {
        "channel_id": "sora",
        "connection_id": "1BW6V4P6A14MZ0W2HHXV3M8MCW",
        "timestamp": "2021-11-13T13:10:25.736Z",
        "user_agent_stats": [
            {
                "audioLevel": 0,
                "id": "RTCAudioSource_1",
                "kind": "audio",
                "timestamp": 1636809025720.942,
                "totalAudioEnergy": 0,
                "totalSamplesDuration": 90.08000000000918,
                "trackIdentifier": "58c7f808-5b7f-4283-8816-0ac1f7d75387",
                "type": "media-source"
            }, ...
        ]
    },
    {
        "channel_id": "sora",
        "connection_id": "VDH8HN6X6S4MZF2FCQJF3Z4M8G",
        "timestamp": "2021-11-13T13:10:30.643Z",
        "user_agent_stats": [
            {
                "audioLevel": 0,
                "id": "RTCAudioSource_1",
                "kind": "audio",
                "timestamp": 1636809030622.809,
                "totalAudioEnergy": 0,
                "totalSamplesDuration": 91.08000000000968,
                "trackIdentifier": "e6d3182d-706c-445f-9a91-c5951d55e000",
                "type": "media-source"
            }, ...
        ]
    }
]

GetUserAgentStats

x-sora-target:

Sora_20211215.GetUserAgentStats

指定した接続のユーザーエージェント統計情報を取得する

キー

channel_id

string

connection_id

string

$ http POST 127.0.0.1:3000/ x-sora-target:Sora_20211215.GetUserAgentStats \
    channel_id=sora \
    connection_id=VDH8HN6X6S4MZF2FCQJF3Z4M8G \
    -vvv
POST / HTTP/1.1
Accept: application/json, */*;q=0.5
Accept-Encoding: gzip, deflate
Connection: keep-alive
Content-Length: 69
Content-Type: application/json
Host: 127.0.0.1:3000
User-Agent: HTTPie/2.4.0
x-sora-target: Sora_20211215.GetUserAgentStats

{
    "channel_id": "sora",
    "connection_id": "VDH8HN6X6S4MZF2FCQJF3Z4M8G"
}


HTTP/1.1 200 OK
access-control-allow-headers: Origin, X-Requested-With, Content-Type, Accept, x-sora-target
access-control-allow-methods: POST, OPTIONS
access-control-allow-origin: http://127.0.0.1:5000
access-control-max-age: 1000
content-length: 15181
content-type: application/json
date: Sat, 13 Nov 2021 13:11:46 GMT
server: Cowboy

{
    "channel_id": "sora",
    "connection_id": "VDH8HN6X6S4MZF2FCQJF3Z4M8G",
    "stats": [
        {
            "audioLevel": 0,
            "id": "RTCAudioSource_1",
            "kind": "audio",
            "timestamp": 1636809090624.392,
            "totalAudioEnergy": 0,
            "totalSamplesDuration": 151.08000000000757,
            "trackIdentifier": "e6d3182d-706c-445f-9a91-c5951d55e000",
            "type": "media-source"
        }, ...
    ],
    "timestamp": "2021-11-13T13:11:30.647Z"
}

その他の API

注意

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

ChangeUpstreamVideoBitRate

x-sora-target:

Sora_20190327.ChangeUpstreamVideoBitRate

指定した接続のビットレートを動的に変更します。

この API は片方向とマルチストリームでのみ利用できます。

主に rolesendonly配信ビットレート を動的に変更し固定する事を目的としている API です。

警告

マルチストリームの sendrecv でも利用可能ですが、この API を利用してビットレートを変更した場合、ビットレートシェアリングが無効になり、配信ビットレートが固定されます。

キー

channel_id

string

connection_id

string

bit_rate

integer (1 - 30000)

$ http POST 127.0.0.1:3000/ x-sora-target:Sora_20190327.ChangeUpstreamVideoBitRate \
    channel_id=sora \
    connection_id=HMRVPQEXJX03D3B3WE778SJGRC \
    bit_rate:=300 \
    -vvv
POST / HTTP/1.1
Accept: application/json, */*
Accept-Encoding: gzip, deflate
Connection: keep-alive
Content-Length: 96
Content-Type: application/json
Host: 127.0.0.1:3000
User-Agent: HTTPie/1.0.2
x-sora-target: Sora_20190327.ChangeUpstreamVideoBitRate

{
    "bit_rate": 300,
    "channel_id": "sora",
    "connection_id": "HMRVPQEXJX03D3B3WE778SJGRC"
}

HTTP/1.1 200 OK
access-control-allow-headers: Origin, X-Requested-With, Content-Type, Accept, x-sora-target
access-control-allow-methods: POST, OPTIONS
access-control-allow-origin: http://127.0.0.1:5000
access-control-max-age: 1000
content-length: 91
content-type: application/json
date: Wed, 27 Mar 2020 08:38:03 GMT
server: Cowboy

{
    "bit_rate": 300,
    "channel_id": "sora",
    "connection_id": "HMRVPQEXJX03D3B3WE778SJGRC"
}
© Copyright 2022, Shiguredo Inc Created using Sphinx 5.0.2