SkyWay Channel API
SkyWay Channel API は、SkyWay の Channel の作成と取得を行うことができるサーバーサイド向けの API です。API は JSON-RPC 2.0 に準拠しています。
類似するサーバーサイド向け API として SkyWay Room API を提供しております。 SkyWay Room API は、SkyWay Channel API と比較して以下のような優位点があります。
- SFU Bot に関する考慮が不要で直感的な利用が可能
- Member の強制退出機能および Room (Channel) のクローズ機能を提供
- Room (Channel) の失効タイミングを取得可能
将来的には SkyWay Room API への移行を予定しているため、SkyWay Room API の利用を推奨いたします。 現在 SkyWay Channel API をご利用の方も、是非 SkyWay Room API をお試しください。
API エンドポイント
https://channel.skyway.ntt.com/v1/json-rpcHTTP POST メソッドでリクエストを行ってください。
認証
リクエストの Authorization ヘッダーに SkyWay Admin Auth Token を入れる必要があります。YOUR_SKYWAY_ADMIN_AUTH_TOKEN は生成した SkyWay Admin Auth Token で置き換えてください。
Authorization: Bearer YOUR_SKYWAY_ADMIN_AUTH_TOKENSkyWay Admin Auth Token の詳細については SkyWay Admin Auth Token のドキュメントを参照してください。
エラーレスポンスについて
エラーレスポンスのレスポンスボディに含まれる error.code は JSON-RPC 2.0 の Error object で定義されているエラーコードのほか、SkyWay Channel API として以下のコードを定義しています。
| code | 説明 |
|---|---|
| 401 | SkyWay Admin Auth Token が不正な場合 |
| 404 | リソースが見つからなかった場合 |
| 409 | すでにリソースが存在する場合 |
| 429 | Free プランをご利用のプロジェクトで 月次の接続回数制限を超過している場合 |
findChannel
id または name から Channel を取得します。id と name の両方が指定された場合は id によって Channel を取得します。
リクエストボディ
| プロパティ | 形式 | 必須 | 説明 |
|---|---|---|---|
| jsonrpc | string | ️✔ | 2.0 を指定する |
| id | string | integer | ✔ | 任意の値を指定する。レスポンスボディにはリクエストボディで指定した id の値が入る |
| method | string | ✔ | findChannel を指定する |
| params | object | ✔ | Channel の id または name を指定する（id あるいは name のいずれかは必須） |
| params.id | string (UUID v4) | Channel の id を指定する | |
| params.name | string | Channel の name を指定する |
例 1. id 7e19cb20-fc79-4d2f-bf29-d498ff76299a の Channel を id から取得する場合のリクエストボディ
{
"jsonrpc": "2.0",
"id": 0,
"method": "findChannel",
"params": {
"id": "7e19cb20-fc79-4d2f-bf29-d498ff76299a"
}
}例 2. name sample-channel の Channel を name から取得する場合のリクエストボディ
{
"jsonrpc": "2.0",
"id": 0,
"method": "findChannel",
"params": {
"name": "sample-channel"
}
}レスポンスボディ
正常系
レスポンスボディ
| プロパティ | 形式 | 必須 | 説明 |
|---|---|---|---|
| jsonrpc | string | ️✔ | 2.0 が入る |
| id | string | integer | ✔ | リクエストボディで指定した id の値が入る |
| result | object | ✔ | |
| result.channel | Channel | ✔ | Channel 情報を表すオブジェクト |
Channel オブジェクト
| プロパティ | 形式 | 必須 | 説明 |
|---|---|---|---|
| id | string (UUID v4) | ️✔ | Channel を一意に特定する値 |
| name | string | アプリケーション内で Channel を一意に特定する値 | |
| members | Member[] | ✔ | Member 情報を表すオブジェクトの配列 |
| publications | Publication[] | ✔ | Publication 情報を表すオブジェクトの配列 |
| subscriptions | Subscription[] | ✔ | Subscription 情報を表すオブジェクトの配列 |
| metadata | string |
Member オブジェクト
| プロパティ | 形式 | 必須 | 説明 |
|---|---|---|---|
| id | string (UUID v4) | ️✔ | Member を一意に特定する値 |
| name | string | Channel 内で Member を一意に特定する値 | |
| type | string | ✔ | person または bot が入る |
| subtype | string | SFU が入る | |
| metadata | string |
Publication オブジェクト
| プロパティ | 形式 | 必須 | 説明 |
|---|---|---|---|
| id | string (UUID v4) | ️✔ | Publication を一意に特定する値 |
| publisherId | string (UUID v4) | ️✔ | publish している Member の id |
| contentType | string | ✔ | AUDIO、VIDEO または DATA が入る |
| isEnabled | boolean | ✔ | Publication が有効の場合 true、そうでなければ false が入る |
| originId | string | forwarding されている Publication の id | |
| originPublisherId | string | forwarding されている Publication を publish している Member の id | |
| metadata | string | ||
| type | string | P2P または SFU が入る |
Subscription オブジェクト
| プロパティ | 形式 | 必須 | 説明 |
|---|---|---|---|
| id | string (UUID v4) | ️✔ | Subscription を一意に特定する値 |
| publicationId | string (UUID v4) | ️✔ | subscribe している Publication の id |
| subscriberId | string | ✔ | subscribe している Member の id |
例
{
"jsonrpc": "2.0",
"id": 0,
"result": {
"channel": {
"id": "7e19cb20-fc79-4d2f-bf29-d498ff76299a",
"name": "sample-channel",
"members": [
{
"id": "16548baf-e4b8-4137-afc0-e8e329837a39",
"type": "person",
"name": "publisher-user"
},
{
"id": "82e31b82-b391-4f84-924a-ca1e89f1a037",
"type": "person",
"name": "subscriber-user"
},
{
"id": "e5782c43-d1f6-4e27-b8f0-4e23269f48d2",
"type": "bot",
"subtype": "SFU"
}
],
"publications": [
{
"id": "f124ab4a-c3c6-40f1-800d-889c6c664924",
"publisherId": "16548baf-e4b8-4137-afc0-e8e329837a39",
"contentType": "AUDIO",
"isEnabled": true,
"type": "P2P",
},
{
"id": "cbb6f98e-2e29-4b3c-a17c-c2cc76c54182",
"publisherId": "16548baf-e4b8-4137-afc0-e8e329837a39",
"contentType": "VIDEO",
"isEnabled": true,
"type": "SFU"
},
{
"id": "81c0c1c0-7ec2-4b71-ba79-15033954de14",
"publisherId": "e5782c43-d1f6-4e27-b8f0-4e23269f48d2",
"contentType": "VIDEO",
"originId": "cbb6f98e-2e29-4b3c-a17c-c2cc76c54182",
"originPublisherId": "16548baf-e4b8-4137-afc0-e8e329837a39",
"isEnabled": true,
"type": "SFU",
}
],
"subscriptions": [
{
"id": "bbc6ac3c-6d13-44ad-9f66-251974bb2635",
"publicationId": "81c0c1c0-7ec2-4b71-ba79-15033954de14",
"subscriberId": "82e31b82-b391-4f84-924a-ca1e89f1a037"
}
]
}
}
}
異常系
例 1. 認証に失敗した場合のレスポンスボディ
{
"jsonrpc": "2.0",
"id": 0,
"error": {
"code": 401,
"message": "Verify admin token failed"
}
}例 2. 指定した id の Channel が存在しなかった場合のレスポンスボディ
{
"jsonrpc": "2.0",
"id": 0,
"error": {
"code": 404,
"message": "Channel '7e19cb20-fc79-4d2f-bf29-d498ff76299a' not found"
}
}例 3. 指定した name の Channel が存在しなかった場合のレスポンスボディ
{
"jsonrpc": "2.0",
"id": 0,
"error": {
"code": 404,
"message": "Channel with name 'sample-channel' not found"
}
}例 4. Free プランをご利用のプロジェクトで接続回数制限※を超過している場合のレスポンスボディ
{
"jsonrpc": "2.0",
"id": 0,
"error": {
"code": 429,
"message": "Project usage limit has been exceeded"
}
}※接続回数の上限はプランの詳細の接続料をご確認ください。
createChannel
Channel を新規作成します。作成時に name や metadata を指定することができます。
リクエストボディ
| プロパティ | 形式 | 必須 | 説明 |
|---|---|---|---|
| jsonrpc | string | ️✔ | 2.0 を指定する |
| id | string | integer | ✔ | 任意の値を指定する。レスポンスボディにはリクエストボディで指定した id の値が入る |
| method | string | ✔ | createChannel を指定する |
| params | object | ✔ | Channel の name または metadata を指定できる |
| params.name | string | Channel の name を指定する。アプリケーション内で一意である必要がある | |
| params.metadata | string | Channel の metadata を指定する |
例
{
"jsonrpc": "2.0",
"id": 0,
"method": "createChannel",
"params": {
"name": "sample-channel"
}
}レスポンスボディ
正常系
レスポンスボディ
| プロパティ | 形式 | 必須 | 説明 |
|---|---|---|---|
| jsonrpc | string | ️✔ | 2.0 が入る |
| id | string | integer | ✔ | リクエストボディで指定した id の値が入る |
| result | object | ✔ | |
| result.channel | Channel | ✔ | Channel 情報を表すオブジェクト |
Channel オブジェクト
| プロパティ | 形式 | 必須 | 説明 |
|---|---|---|---|
| id | string (UUID v4) | ️✔ | Channel を一意に特定する値 |
| name | string | アプリケーション内で Channel を一意に特定する値 | |
| metadata | string |
例
{
"jsonrpc": "2.0",
"id": 0,
"result": {
"channel": {
"id": "7e19cb20-fc79-4d2f-bf29-d498ff76299a",
"name": "sample-channel"
}
},
}異常系
例 1. 認証に失敗した場合のレスポンスボディ
{
"jsonrpc": "2.0",
"id": 0,
"error": {
"code": 401,
"message": "Verify admin token failed"
}
}例 2. 指定した name の Channel がすでに存在していた場合のレスポンスボディ
{
"jsonrpc": "2.0",
"id": 0,
"error": {
"code": 409,
"message": "Channel with name 'sample-channel' already exists"
}
}例 3. Free プランをご利用のプロジェクトで接続回数制限※を超過している場合のレスポンスボディ
{
"jsonrpc": "2.0",
"id": 0,
"error": {
"code": 429,
"message": "Project usage limit has been exceeded"
}
}※接続回数の上限はプランの詳細の接続料をご確認ください。
findOrCreateChannel
指定された name の Channel が存在すればその Channel 情報を取得し、そうでなければ新規作成します。
リクエストボディ
| プロパティ | 形式 | 必須 | 説明 |
|---|---|---|---|
| jsonrpc | string | ️✔ | 2.0 を指定する |
| id | string | integer | ✔ | 任意の値を指定する。レスポンスボディにはリクエストボディで指定した id の値が入る |
| method | string | ✔ | findOrCreateChannel を指定する |
| params | object | ✔ | Channel の name および metadata を指定する（name は必須） |
| params.name | string | ✔ | Channel の name を指定する |
| params.metadata | string | Channel の metadata を指定する |
例
{
"jsonrpc": "2.0",
"id": 0,
"method": "findOrCreateChannel",
"params": {
"name": "sample-channel"
}
}レスポンスボディ
正常系
レスポンスボディ
| プロパティ | 形式 | 必須 | 説明 |
|---|---|---|---|
| jsonrpc | string | ️✔ | 2.0 が入る |
| id | string | integer | ✔ | リクエストボディで指定した id の値が入る |
| result | object | ✔ | |
| result.channel | Channel | ✔ | Channel 情報を表すオブジェクト |
Channel オブジェクト
| プロパティ | 形式 | 必須 | 説明 |
|---|---|---|---|
| id | string (UUID v4) | ️✔ | Channel を一意に特定する値 |
| name | string | アプリケーション内で Channel を一意に特定する値 | |
| members | Member[] | ✔ | Member 情報を表すオブジェクトの配列 |
| publications | Publication[] | ✔ | Publication 情報を表すオブジェクトの配列 |
| subscriptions | Subscription[] | ✔ | Subscription 情報を表すオブジェクトの配列 |
| metadata | string |
Member オブジェクト
| プロパティ | 形式 | 必須 | 説明 |
|---|---|---|---|
| id | string (UUID v4) | ️✔ | Member を一意に特定する値 |
| name | string | Channel 内で Member を一意に特定する値 | |
| type | string | ✔ | person または bot が入る |
| subtype | string | SFU が入る | |
| metadata | string |
Publication オブジェクト
| プロパティ | 形式 | 必須 | 説明 |
|---|---|---|---|
| id | string (UUID v4) | ️✔ | Publication を一意に特定する値 |
| publisherId | string (UUID v4) | ️✔ | publish している Member の id |
| contentType | string | ✔ | AUDIO、VIDEO または DATA が入る |
| isEnabled | boolean | ✔ | Publication が有効の場合 true、そうでなければ false が入る |
| originId | string | forwarding されている Publication の id | |
| originPublisherId | string | forwarding されている Publication を publish している Member の id | |
| metadata | string | ||
| type | string | P2P または SFU が入る |
Subscription オブジェクト
| プロパティ | 形式 | 必須 | 説明 |
|---|---|---|---|
| id | string (UUID v4) | ️✔ | Subscription を一意に特定する値 |
| publicationId | string (UUID v4) | ️✔ | subscribe している Publication の id |
| subscriberId | string | ✔ | subscribe している Member の id |
例
{
"jsonrpc": "2.0",
"id": 0,
"result": {
"channel": {
"id": "7e19cb20-fc79-4d2f-bf29-d498ff76299a",
"name": "sample-channel",
"members": [
{
"id": "16548baf-e4b8-4137-afc0-e8e329837a39",
"type": "person",
"name": "publisher-user"
},
{
"id": "82e31b82-b391-4f84-924a-ca1e89f1a037",
"type": "person",
"name": "subscriber-user"
},
{
"id": "e5782c43-d1f6-4e27-b8f0-4e23269f48d2",
"type": "bot",
"subtype": "SFU"
}
],
"publications": [
{
"id": "f124ab4a-c3c6-40f1-800d-889c6c664924",
"publisherId": "16548baf-e4b8-4137-afc0-e8e329837a39",
"contentType": "AUDIO",
"isEnabled": true,
"type": "P2P",
},
{
"id": "cbb6f98e-2e29-4b3c-a17c-c2cc76c54182",
"publisherId": "16548baf-e4b8-4137-afc0-e8e329837a39",
"contentType": "VIDEO",
"isEnabled": true,
"type": "SFU"
},
{
"id": "81c0c1c0-7ec2-4b71-ba79-15033954de14",
"publisherId": "e5782c43-d1f6-4e27-b8f0-4e23269f48d2",
"contentType": "VIDEO",
"originId": "cbb6f98e-2e29-4b3c-a17c-c2cc76c54182",
"originPublisherId": "16548baf-e4b8-4137-afc0-e8e329837a39",
"isEnabled": true,
"type": "SFU"
}
],
"subscriptions": [
{
"id": "bbc6ac3c-6d13-44ad-9f66-251974bb2635",
"publicationId": "81c0c1c0-7ec2-4b71-ba79-15033954de14",
"subscriberId": "82e31b82-b391-4f84-924a-ca1e89f1a037"
}
]
}
}
}
異常系
例 1. 認証に失敗した場合のレスポンスボディ
{
"jsonrpc": "2.0",
"id": 0,
"error": {
"code": 401,
"message": "Verify admin token failed"
}
}例 2. Free プランをご利用のプロジェクトで接続回数制限※を超過している場合のレスポンスボディ
{
"jsonrpc": "2.0",
"id": 0,
"error": {
"code": 429,
"message": "Project usage limit has been exceeded"
}
}※接続回数の上限はプランの詳細の接続料をご確認ください。