--- lang: ja path: api-reference/rtc-api-server/room-api labels: APIリファレンス/Room API ／ Channel API/Room API metaTitle: Room API ｜ APIリファレンス ｜ SkyWay（スカイウェイ） --- # SkyWay Room API SkyWay Room API は、SkyWay の Room に対する操作を実行するサーバーサイド向け API です。 API は [JSON-RPC 2.0](https://www.jsonrpc.org/specification) に準拠しています。 > 類似するサーバーサイド向け API として [SkyWay Channel API](/ja/docs/api-reference/rtc-api-server/channel-api) を提供しておりますが、現在は非推奨です。 > SkyWay Room API をご利用ください。 ## API エンドポイント ``` https://room.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 のドキュメント](/ja/docs/user-guide/authentication/skyway-admin-auth-token/)を参照してください。 ## エラーレスポンスについて エラーレスポンスのレスポンスボディに含まれる `error.code` は [JSON-RPC 2.0](https://www.jsonrpc.org/specification) の Error object で定義されているエラーコードのほか、SkyWay Room API として以下のコードを定義しています。 |code|説明| |---|---| |401|SkyWay Admin Auth Token が不正な場合| |404|リソースが見つからなかった場合| |409|すでにリソースが存在する場合| |429|Free プランをご利用のプロジェクトで
月次の接続回数制限を超過している場合| |429|リクエストのレートリミットを超過した場合| 以下のエラーレスポンスは、実行する Room API のメソッドに関わらず共通して発生し得る異常ケースです。 - SkyWay Admin Auth Token が不正な場合のレスポンスボディ ```json { "jsonrpc": "2.0", "id": 0, "error": { "code": 401, "message": "Verify admin token failed" } } ``` - Free プランをご利用のプロジェクトで月次の接続回数制限※を超過している場合のレスポンスボディ ```json { "jsonrpc": "2.0", "id": 0, "error": { "code": 429, "message": "Project usage limit has been exceeded" } } ``` ※接続回数の上限は[「プランの詳細」ページの「接続料」](https://skyway.ntt.com/ja/pricing/#plan)をご確認ください。 - リクエストのレートリミット※を超過した場合のレスポンスボディ ```json { "jsonrpc": "2.0", "id": 0, "error": { "code": 429, "message": "exceeded rate limit", } } ``` ※リクエストレートの制限に関する詳細は[「割り当てと制限」ページの「リクエストレートの制限」セクション](/ja/docs/user-guide/commons/quotas-and-limits)をご確認ください。 - リクエストボディの id プロパティが文字列もしくは整数以外の場合のレスポンスボディ ```json { "jsonrpc": "2.0", "id": null, "error": { "code": -32600, "message": "Request 'id' must be a string or integer", } } ``` ## findRoom id または name から Room を取得します。 id と name の両方が指定された場合は id に基づいて Room を取得します。 ### リクエストボディ リクエストボディ |プロパティ|形式|必須|説明| |---|---|---|---| |jsonrpc|string|️✔|`2.0` を指定する| |id|string \| integer|✔|任意の値を指定する。レスポンスボディにはリクエストボディで指定した id の値が入る| |method|string|✔|`findRoom` を指定する| |params|object|✔|Room の id または name を指定する（id あるいは name のいずれかは必須）| params プロパティの構造 |プロパティ|形式|必須|説明| |---|---|---|---| |id|string (UUID v4)||Room の id を指定する| |name|string||Room の name を指定する| 例 1. id `6abbecae-dd86-4e8b-ab9f-8da2c7740ddc` の Room を取得する場合のリクエストボディ ```json { "jsonrpc": "2.0", "id": 0, "method": "findRoom", "params": { "id": "6abbecae-dd86-4e8b-ab9f-8da2c7740ddc" } } ``` 例 2. name `sample-room` の Room を取得する場合のリクエストボディ ```json { "jsonrpc": "2.0", "id": 0, "method": "findRoom", "params": { "name": "sample-room" } } ``` ### レスポンスボディ #### 正常系 レスポンスボディ |プロパティ|形式|必須|説明| |---|---|---|---| |jsonrpc|string|️✔|`2.0` が入る| |id|string \| integer|✔|リクエストボディで指定した id の値が入る| |result|object|✔|| |result.room|Room|✔|Room 情報を表すオブジェクト| Room オブジェクト |プロパティ|形式|必須|説明| |---|---|---|---| |id|string (UUID v4)|️✔|Room を一意に特定する値| |name|string||アプリケーション内で Room を一意に特定する値| |expiresAt|string|✔|Room の失効時刻（ISO 8601 形式）| |members|Member[]|✔|Member 情報を表すオブジェクトの配列| |publications|Publication[]|✔|Publication 情報を表すオブジェクトの配列| |subscriptions|Subscription[]|✔|Subscription 情報を表すオブジェクトの配列| |metadata|string||| Member オブジェクト |プロパティ|形式|必須|説明| |---|---|---|---| |id|string (UUID v4)|️✔|Member を一意に特定する値| |name|string||Room 内で Member を一意に特定する値| |metadata|string||| Publication オブジェクト |プロパティ|形式|必須|説明| |---|---|---|---| |id|string (UUID v4)|️✔|Publication を一意に特定する値| |publisher|Publisher|✔|Publish している Member の情報| |contentType|string|✔|`AUDIO`、`VIDEO` または `DATA` が入る| |isEnabled|boolean|✔|Publication が有効の場合 `true`、そうでなければ `false` が入る| |type|string|✔|`P2P` または `SFU` が入る| |metadata|string||| Publisher オブジェクト |プロパティ|形式|必須|説明| |---|---|---|---| |id|string (UUID v4)|️✔|Publisher の Member id| |name|string||Publisher の Member name| Subscription オブジェクト |プロパティ|形式|必須|説明| |---|---|---|---| |id|string (UUID v4)|️✔|Subscription を一意に特定する値| |publicationId|string (UUID v4)|️✔|subscribe している Publication の id| |subscriber|Subscriber|✔|subscribe している Member の情報| Subscriber オブジェクト |プロパティ|形式|必須|説明| |---|---|---|---| |id|string (UUID v4)|️✔|Subscriber の Member id| |name|string||Subscriber の Member name| 例 ```json { "jsonrpc": "2.0", "id": 0, "result": { "room": { "id": "6abbecae-dd86-4e8b-ab9f-8da2c7740ddc", "name": "sample-room", "expiresAt": "2025-11-25T12:34:56Z", "members": [ { "id": "1adee02b-811d-4a79-b07d-cdcb1437c7c3", "name": "user01", "metadata": "publisher" }, { "id": "504ac623-7880-49b5-855f-aa73856ae5e7", "name": "user02", "metadata": "subscriber" } ], "publications": [ { "id": "aa63b6d1-c1c5-447b-b7ea-faebe70a8b11", "contentType": "VIDEO", "isEnabled": true, "type": "SFU", "publisher": { "id": "1adee02b-811d-4a79-b07d-cdcb1437c7c3", "name": "user01" } }, { "id": "7b213f12-42ba-40f2-9b36-9eb967d263d6", "contentType": "DATA", "isEnabled": true, "type": "P2P", "publisher": { "id": "1adee02b-811d-4a79-b07d-cdcb1437c7c3", "name": "user01" } } ], "subscriptions": [ { "id": "be35b8dc-bcc3-4005-bf2a-b4d52d51f2db", "publicationId": "aa63b6d1-c1c5-447b-b7ea-faebe70a8b11", "subscriber": { "id": "504ac623-7880-49b5-855f-aa73856ae5e7", "name": "user02" } }, { "id": "4fcef9c1-3f7a-4287-92de-332c2baf3ce6", "publicationId": "7b213f12-42ba-40f2-9b36-9eb967d263d6", "subscriber": { "id": "504ac623-7880-49b5-855f-aa73856ae5e7", "name": "user02" } } ] } } } ``` #### 異常系 例 1. 指定した id の Room が存在しなかった場合のレスポンスボディ ```json { "jsonrpc": "2.0", "id": 0, "error": { "code": 404, "message": "Room '6abbecae-dd86-4e8b-ab9f-8da2c7740ddc' not found" } } ``` 例 2. 指定した name の Room が存在しなかった場合のレスポンスボディ ```json { "jsonrpc": "2.0", "id": 0, "error": { "code": 404, "message": "Room with name 'sample-room' not found" } } ``` 例 3. Room の id および name がどちらも指定されていない場合 ```json { "jsonrpc": "2.0", "id": 0, "error": { "code": -32602, "message": "'id' or 'name' must be specified", }, } ``` ## createRoom Room を新規作成します。作成時に name や metadata を指定することができます。 ### リクエストボディ リクエストボディ |プロパティ|形式|必須|説明| |---|---|---|---| |jsonrpc|string|️✔|`2.0` を指定する| |id|string \| integer|✔|任意の値を指定する。レスポンスボディにはリクエストボディで指定した id の値が入る| |method|string|✔|`createRoom` を指定する| |params|object|✔|Room の name および metadata を指定できる| params プロパティの構造 |プロパティ|形式|必須|説明| |---|---|---|---| |name|string||Room の name を指定する。アプリケーション内で一意である必要がある| |metadata|string||Room の metadata を指定する| 例 1. `sample-room` という name を指定して Room を作成する場合のリクエストボディ ```json { "jsonrpc": "2.0", "id": 0, "method": "createRoom", "params": { "name": "sample-room" } } ``` 例 2. name を指定しないで Room を作成する場合のリクエストボディ ```json { "jsonrpc": "2.0", "id": 0, "method": "createRoom", "params": {} } ``` ### レスポンスボディ #### 正常系 レスポンスボディ |プロパティ|形式|必須|説明| |---|---|---|---| |jsonrpc|string|️✔|`2.0` が入る| |id|string \| integer|✔|リクエストボディで指定した id の値が入る| |result|object|✔|| |result.room|Room|✔|Room 情報を表すオブジェクト| Room オブジェクト |プロパティ|形式|必須|説明| |---|---|---|---| |id|string (UUID v4)|️✔|Room を一意に特定する値| |name|string||アプリケーション内で Room を一意に特定する値| |metadata|string||| 例 ```json { "jsonrpc": "2.0", "id": 0, "result": { "room": { "id": "6abbecae-dd86-4e8b-ab9f-8da2c7740ddc", "name": "sample-room" } }, } ``` #### 異常系 例 1. 指定した name の Room がすでに存在していた場合のレスポンスボディ ```json { "jsonrpc": "2.0", "id": 0, "error": { "code": 409, "message": "Room with name 'sample-room' already exists" } } ``` ## findOrCreateRoom 指定された name の Room が存在すればその Room 情報を取得し、そうでなければ新規作成します。 ### リクエストボディ リクエストボディ |プロパティ|形式|必須|説明| |---|---|---|---| |jsonrpc|string|️✔|`2.0` を指定する| |id|string \| integer|✔|任意の値を指定する。レスポンスボディにはリクエストボディで指定した id の値が入る| |method|string|✔|`findOrCreateRoom` を指定する| |params|object|✔|Room の name および metadata を指定する（name は必須）| params プロパティの構造 |プロパティ|形式|必須|説明| |---|---|---|---| |name|string|✔|Room の name を指定する| |metadata|string||Room の metadata を指定する| 例 ```json { "jsonrpc": "2.0", "id": 0, "method": "findOrCreateRoom", "params": { "name": "sample-room" } } ``` ### レスポンスボディ #### 正常系 レスポンスボディ |プロパティ|形式|必須|説明| |---|---|---|---| |jsonrpc|string|️✔|`2.0` が入る| |id|string \| integer|✔|リクエストボディで指定した id の値が入る| |result|object|✔|| |result.room|Room|✔|Room 情報を表すオブジェクト| Room オブジェクト |プロパティ|形式|必須|説明| |---|---|---|---| |id|string (UUID v4)|️✔|Room を一意に特定する値| |name|string||アプリケーション内で Room を一意に特定する値| |expiresAt|string|✔|Room の失効時刻（ISO 8601 形式）| |members|Member[]|✔|Member 情報を表すオブジェクトの配列| |publications|Publication[]|✔|Publication 情報を表すオブジェクトの配列| |subscriptions|Subscription[]|✔|Subscription 情報を表すオブジェクトの配列| |metadata|string||| Member オブジェクト |プロパティ|形式|必須|説明| |---|---|---|---| |id|string (UUID v4)|️✔|Member を一意に特定する値| |name|string||Room 内で Member を一意に特定する値| |metadata|string||| Publication オブジェクト |プロパティ|形式|必須|説明| |---|---|---|---| |id|string (UUID v4)|️✔|Publication を一意に特定する値| |publisher|Publisher|✔|Publish している Member の情報| |contentType|string|✔|`AUDIO`、`VIDEO` または `DATA` が入る| |isEnabled|boolean|✔|Publication が有効の場合 `true`、そうでなければ `false` が入る| |type|string|✔|`P2P` または `SFU` が入る| |metadata|string||| Publisher オブジェクト |プロパティ|形式|必須|説明| |---|---|---|---| |id|string (UUID v4)|️✔|Publisher の Member id| |name|string||Publisher の Member name| Subscription オブジェクト |プロパティ|形式|必須|説明| |---|---|---|---| |id|string (UUID v4)|️✔|Subscription を一意に特定する値| |publicationId|string (UUID v4)|️✔|subscribe している Publication の id| |subscriber|Subscriber|✔|subscribe している Member の情報| Subscriber オブジェクト |プロパティ|形式|必須|説明| |---|---|---|---| |id|string (UUID v4)|️✔|Subscriber の Member id| |name|string||Subscriber の Member name| 例 ```json { "jsonrpc": "2.0", "id": 0, "result": { "room": { "id": "6abbecae-dd86-4e8b-ab9f-8da2c7740ddc", "name": "sample-room", "expiresAt": "2025-11-25T12:34:56Z", "members": [ { "id": "1adee02b-811d-4a79-b07d-cdcb1437c7c3", "name": "user01", "metadata": "publisher" }, { "id": "504ac623-7880-49b5-855f-aa73856ae5e7", "name": "user02", "metadata": "subscriber" } ], "publications": [ { "id": "aa63b6d1-c1c5-447b-b7ea-faebe70a8b11", "contentType": "VIDEO", "isEnabled": true, "type": "SFU", "publisher": { "id": "1adee02b-811d-4a79-b07d-cdcb1437c7c3", "name": "user01" } }, { "id": "7b213f12-42ba-40f2-9b36-9eb967d263d6", "contentType": "DATA", "isEnabled": true, "type": "P2P", "publisher": { "id": "1adee02b-811d-4a79-b07d-cdcb1437c7c3", "name": "user01" } } ], "subscriptions": [ { "id": "be35b8dc-bcc3-4005-bf2a-b4d52d51f2db", "publicationId": "aa63b6d1-c1c5-447b-b7ea-faebe70a8b11", "subscriber": { "id": "504ac623-7880-49b5-855f-aa73856ae5e7", "name": "user02" } }, { "id": "4fcef9c1-3f7a-4287-92de-332c2baf3ce6", "publicationId": "7b213f12-42ba-40f2-9b36-9eb967d263d6", "subscriber": { "id": "504ac623-7880-49b5-855f-aa73856ae5e7", "name": "user02" } } ] } } } ``` #### 異常系 例 1. Room の name が指定されていない場合のレスポンスボディ ```json { "jsonrpc": "2.0", "id": 0, "error": { "code": -32602, "message": "Parameter must have required property 'name'", } } ``` ## closeRoom id または name で指定した Room を削除します。 id と name の両方が指定された場合は id に基づいて Room を削除します。 ### リクエストボディ リクエストボディ |プロパティ|形式|必須|説明| |---|---|---|---| |jsonrpc|string|️✔|`2.0` を指定する| |id|string \| integer|✔|任意の値を指定する。レスポンスボディにはリクエストボディで指定した id の値が入る| |method|string|✔|`closeRoom` を指定する| |params|object|✔|Room の id または name を指定する（id あるいは name のいずれかは必須）| params プロパティの構造 |プロパティ|形式|必須|説明| |---|---|---|---| |id|string (UUID v4)||Room の id を指定する| |name|string||Room の name を指定する| 例 1. id `6abbecae-dd86-4e8b-ab9f-8da2c7740ddc` の Room を削除する場合のリクエストボディ ```json { "jsonrpc": "2.0", "id": 0, "method": "closeRoom", "params": { "id": "6abbecae-dd86-4e8b-ab9f-8da2c7740ddc" } } ``` 例 2. name `sample-room` の Room を削除する場合のリクエストボディ ```json { "jsonrpc": "2.0", "id": 0, "method": "closeRoom", "params": { "name": "sample-room" } } ``` ### レスポンスボディ #### 正常系 レスポンスボディ |プロパティ|形式|必須|説明| |---|---|---|---| |jsonrpc|string|️✔|`2.0` が入る| |id|string \| integer|✔|リクエストボディで指定した id の値が入る| |result|object|✔|| 例 ```json { "jsonrpc": "2.0", "id": 0, "result": {} } ``` #### 異常系 例 1. 指定した id の Room が存在しなかった場合のレスポンスボディ ```json { "jsonrpc": "2.0", "id": 0, "error": { "code": 404, "message": "Room '6abbecae-dd86-4e8b-ab9f-8da2c7740ddc' not found" } } ``` 例 2. 指定した name の Room が存在しなかった場合のレスポンスボディ ```json { "jsonrpc": "2.0", "id": 0, "error": { "code": 404, "message": "Room with name 'sample-room' not found" } } ``` 例 3. Room の id および name がどちらも指定されていない場合 ```json { "jsonrpc": "2.0", "id": 0, "error": { "code": -32602, "message": "'id' or 'name' must be specified", }, } ``` ## removeMember id または name で指定した特定の Member を削除します。 id と name の両方が指定された場合は id に基づいて Member を削除します。 ### リクエストボディ リクエストボディ |プロパティ|形式|必須|説明| |---|---|---|---| |jsonrpc|string|️✔|`2.0` を指定する| |id|string \| integer|✔|任意の値を指定する。レスポンスボディにはリクエストボディで指定した id の値が入る| |method|string|✔|`removeMember` を指定する| |params|object|✔|Room および Member を指定する| params プロパティの構造 |プロパティ|形式|必須|説明| |---|---|---|---| |room|object|✔|Room の id または name を指定する（id あるいは name のいずれかは必須）| room プロパティの構造 |プロパティ|形式|必須|説明| |---|---|---|---| |id|string||Room の id を指定する| |name|string||Room の name を指定する| |member|object|✔|Member の id または name を指定する（id あるいは name のいずれかは必須）| member プロパティの構造 |プロパティ|形式|必須|説明| |---|---|---|---| |id|string||Member の id を指定する| |name|string||Member の name を指定する| 例 1. id `6abbecae-dd86-4e8b-ab9f-8da2c7740ddc` の Room から、id `1adee02b-811d-4a79-b07d-cdcb1437c7c3` の Member を削除する場合のリクエストボディ ```json { "jsonrpc": "2.0", "id": 0, "method": "removeMember", "params": { "room": { "id": "6abbecae-dd86-4e8b-ab9f-8da2c7740ddc", "member": { "id": "1adee02b-811d-4a79-b07d-cdcb1437c7c3" } } } } ``` 例 2. id `6abbecae-dd86-4e8b-ab9f-8da2c7740ddc` の Room から、name `user01` の Member を削除する場合のリクエストボディ ```json { "jsonrpc": "2.0", "id": 0, "method": "removeMember", "params": { "room": { "id": "6abbecae-dd86-4e8b-ab9f-8da2c7740ddc", "member": { "name": "user01" } } } } ``` 例 3. name `sample-room` の Room から、id `1adee02b-811d-4a79-b07d-cdcb1437c7c3` の Member を削除する場合のリクエストボディ ```json { "jsonrpc": "2.0", "id": 0, "method": "removeMember", "params": { "room": { "name": "sample-room", "member": { "id": "1adee02b-811d-4a79-b07d-cdcb1437c7c3" } } } } ``` 例 4. name `sample-room` の Room から、name `user01` の Member を削除する場合のリクエストボディ ```json { "jsonrpc": "2.0", "id": 0, "method": "removeMember", "params": { "room": { "name": "sample-room", "member": { "name": "user01" } } } } ``` ### レスポンスボディ #### 正常系 レスポンスボディ |プロパティ|形式|必須|説明| |---|---|---|---| |jsonrpc|string|️✔|`2.0` が入る| |id|string \| integer|✔|リクエストボディで指定した id の値が入る| |result|object|✔|| 例 ```json { "jsonrpc": "2.0", "id": 0, "result": {} } ``` #### 異常系 例 1. 指定した id の Room が存在しなかった場合のレスポンスボディ ```json { "jsonrpc": "2.0", "id": 0, "error": { "code": 404, "message": "Room '6abbecae-dd86-4e8b-ab9f-8da2c7740ddc' not found" } } ``` 例 2. 指定した name の Room が存在しなかった場合のレスポンスボディ ```json { "jsonrpc": "2.0", "id": 0, "error": { "code": 404, "message": "Room with name 'sample-room' not found" } } ``` 例 3. Room の id および name がどちらも指定されていない場合 ```json { "jsonrpc": "2.0", "id": 0, "error": { "code": -32602, "message": "Room 'id' or 'name' must be specified" }, } ``` 例 4. 指定した id の Member が存在しなかった場合のレスポンスボディ ```json { "jsonrpc": "2.0", "id": 0, "error": { "code": 404, "message": "Member '1adee02b-811d-4a79-b07d-cdcb1437c7c3' not found" } } ``` 例 5. 指定した name の Member が存在しなかった場合のレスポンスボディ ```json { "jsonrpc": "2.0", "id": 0, "error": { "code": 404, "message": "Member with name 'user01' not found" } } ``` 例 6. Member の id および name がどちらも指定されていない場合 ```json { "jsonrpc": "2.0", "id": 0, "error": { "code": -32602, "message": "Member 'id' or 'name' must be specified" }, } ```