SkyWay Channel API
SkyWay Channel API は、SkyWay の Channel の作成と取得を行うことができるサーバーサイド向けの API です。API は JSON-RPC 2.0 に準拠しています。
API エンドポイント
https://channel.skyway.ntt.com/v1/json-rpc
HTTP POST メソッドでリクエストを行ってください。
認証
リクエストの Authorization ヘッダーに SkyWay Admin Auth Token を入れる必要があります。YOUR_SKYWAY_ADMIN_AUTH_TOKEN は生成した SkyWay Admin Auth Token で置き換えてください。
Authorization: Bearer YOUR_SKYWAY_ADMIN_AUTH_TOKEN
SkyWay 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 | すでにリソースが存在する場合 |
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 |
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": "cbb6f98e-2e29-4b3c-a17c-c2cc76c54182", "publisherId": "16548baf-e4b8-4137-afc0-e8e329837a39", "contentType": "VIDEO", "isEnabled": true }, { "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 } ], "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" } }
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" } }
findOrCreateChannel
指定された name の Channel が存在すればその Channel 情報を取得し、そうでなければ新規作成します。
リクエストボディ
| プロパティ | 形式 | 必須 | 説明 |
|---|---|---|---|
| jsonrpc | string | ️✔ | 2.0 を指定する |
| id | string | integer | ✔ | 任意の値を指定する。レスポンスボディにはリクエストボディで指定した id の値が入る |
| method | string | ✔ | findChannel を指定する |
| 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 |
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": "cbb6f98e-2e29-4b3c-a17c-c2cc76c54182", "publisherId": "16548baf-e4b8-4137-afc0-e8e329837a39", "contentType": "VIDEO", "isEnabled": true }, { "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 } ], "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. 指定した name の Channel が存在しなかった場合のレスポンスボディ
{ "jsonrpc": "2.0", "id": 0, "error": { "code": 404, "message": "Channel with name 'sample-channel' not found" } }
例 3. 指定した name の Channel がすでに存在していた場合のレスポンスボディ
{ "jsonrpc": "2.0", "id": 0, "error": { "code": 409, "message": "Channel with name 'sample-channel' already exists" } }