実験的 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.conf の contact_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_nodes を true に指定することで、接続していないノードも含め、そのノードが知っているすべてのノード一覧を返します。 接続していないノードについては node_name と connected のみが結果に含まれます。

レスポンス JSON

キー	型	内容
external_api_url	string	sora.conf の external_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.conf の node_name
connected	boolean	API 実行ノードと正常に接続できているかどうか
external_signaling_url	string	sora.conf の external_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_id と bundle_id と client_id と metadata をキーとしたオブジェクトがリストで入ってきます。順番保証はしません。

キー	型
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

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

  • セットアップ時間とはシグナリング接続開始から WebRTC が確立するまでにかかった時間です

$ 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 は片方向とマルチストリームでのみ利用できます。

主に role が sendonly の 配信ビットレート を動的に変更し固定することを目的としている 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"
}

コンテンツ

• 実験的 API
  • 概要
  • シグナリング API
    • ListChannels
  • クラスター API
    • JoinCluster
    • ListClusterNodes
    • ListClusterChannels
    • PurgeClusterNode
  • モード API
    • ChangeMode
    • GetMode
  • RTP 転送 API
    • StartForwardingRtp
    • StopForwardingRtp
  • シグナリング通知メタデータ拡張 API
    • ListSignalingNotifyMetadata
    • GetSignalingNotifyMetadata
    • PutSignalingNotifyMetadata
    • DeleteSignalingNotifyMetadata
    • PutSignalingNotifyMetadataItem
    • DeleteSignalingNotifyMetadataItem
  • RTP ストリーム停止/再開 API
    • PauseRtpStream
    • ResumeRtpStream
    • ListPauseRtpStreams
  • 統計 API
    • GetStatsReport
      • レスポンス項目
  • ユーザーエージェント統計情報 API
    • 統計情報更新のタイミングについて
    • ListUserAgentStats
    • ListChannelUserAgentStats
    • GetUserAgentStats
  • その他の API
    • ChangeUpstreamVideoBitRate