通知
本站点除 Legacy 产品与方案外，已迁移至 声网新文档中心 ，当前页面不再维护
文档中心
全部产品
Console 官网 社区 技术支持
简体中文
search-icon

房间管理

更新时间 2023/06/29 09:38:40

创建房间（POST）

创建一个实时互动房间。

接口原型

  • 方法：POST
  • 接入点：https://api.netless.link/v5/rooms

请求头部

该 API 需要在 HTTP 请求头部填入以下参数：

参数 类型 是否必需 描述
token string 必需 SDK Token，可以通过以下方式获取：
  • 在声网控制台生成用于测试的 SDK Token，详见获取互动白板项目的安全密钥。
  • 调用服务端 RESTful API， 详见生成 SDK Token。
  • 在 app 服务端用代码生成，详见在 app 服务端生成 Token。
    		•
    region string 必需 指定处理该请求的数据中心，取值如下：
  • cn-hz：中国杭州，服务区覆盖中国大陆地区及其他数据中心未覆盖的区域。
  • us-sv：美国硅谷，服务区覆盖北美洲、南美洲。
  • sg：新加坡，服务区覆盖新加坡、东亚、东南亚。
  • in-mum：印度孟买，服务区覆盖印度。
  • eu：欧洲（法兰克福）,服务区覆盖欧洲。

    • 请求包体

    参数 类型 是否必需 描述
    isRecord boolean 可选 是否开启录制：
  • true：开启。
  • false: 不开启。
    仅 cn-hz 区域的 isRecord 字段默认值为 true。开启白板录制将产生费用，如果你没有录制需求，需手动传入 false。
    		•
    limit integer 可选 房间内可写人数（拥有 writer 或 admin 权限的用户）的上限。如果传 0，则表示无限制。目前推荐设置为 0。

    请求示例

    POST /v5/rooms
Host: api.netless.link
token: NETLESSSDK_YWs9xxxxxxZGM2MjRi
region: cn-hz
Content-Type: application/json

    HTTP 响应

    所有可能的响应状态码详见状态码汇总表。

    如果状态码为 201，则请求成功。响应包含返回的操作结果和数据。

    请求成功响应示例：

    "status": 201,
"body":
{
    "uuid": "4a5xxxxx6b",
    "teamUUID": "RMxxxxx5aw",
    "appUUID": "i54xxxxx1AQ",
    "isRecord": true,
    "isBan": false,
    "createdAt": "2021-01-18T06:56:29.432Z",
    "limit": 0
}

    响应包体参数：

    参数 类型 描述
    uuid string 房间的 UUID，即房间的全局唯一标识符。
    teamUUID string 互动白板控制台账号的唯一标识符。
    appUUID string 互动白板项目的唯一标识符。
    isRecord boolean 房间是否开启录制：
  • true：开启。
  • false: 不开启。
    		•
    isBan boolean 房间是否被封禁：
  • true：已封禁。
  • false: 未封禁。
    		•
    createdAt string 创建房间的 UTC 时间。
    limit integer 房间内可写人数（拥有 writer 或 admin 权限的用户）的上限。如果值为 0，则表示无限制。

    如果状态码不为 201，则请求失败。响应包体中包含 message 字段，描述失败的具体原因。

    获取房间信息（GET）

    获取指定房间的信息。

    接口原型

    • 方法：GET
    • 接入点：https://api.netless.link/v5/rooms/{uuid}

    请求头部

    该 API 需要在 HTTP 请求头部填入以下参数：

    参数 类型 是否必需 描述
    token string 必需 拥有 writer 或 admin 权限的 SDK Token 或 Room Token。
    SDK Token 可通过以下方式获取：
  • 在声网控制台生成用于测试的 SDK Token，详见获取互动白板项目的安全密钥。
  • 调用服务端 RESTful API， 详见生成 SDK Token。
  • 在 app 服务端用代码生成，详见在 app 服务端生成 Token。
    • Room Token 可以通过以下方式获取：
  • 调用服务端 RESTful API， 详见生成 Room Token。
  • 在 app 服务端用代码生成 ，详见在 app 服务端生成 Token。
    		•
    region string 必需 指定处理该请求的数据中心，取值如下：
  • cn-hz：中国杭州，服务区覆盖中国大陆地区及其他数据中心未覆盖的区域。
  • us-sv：美国硅谷，服务区覆盖北美洲、南美洲。
  • sg：新加坡，服务区覆盖新加坡、东亚、东南亚。
  • in-mum：印度孟买，服务区覆盖印度。
  • eu：欧洲（法兰克福）,服务区覆盖欧洲。

    • 请求路径

    该 API 需要在 URL 中传入以下参数：

    参数 类型 是否必需 描述
    uuid string 必需 房间的 UUID, 即房间的全局唯一标识符，可通过调用创建房间 API 或获取房间信息 API 获取。

    请求示例

    GET /v5/rooms/a7exxxxxxa69
Host: api.netless.link
Content-Type: application/json
region: cn-hz
token: NETLESSSDK_YWs9xxxxxxM2MjRi

    HTTP 响应

    所有可能的响应状态码详见状态码汇总表。

    如果状态码为 200，则请求成功。响应包含返回的操作结果和数据。

    请求成功响应示例：

    "status": 200,
"body":
{
    "uuid": "4axxxxx96b",
    "teamUUID": "RMmxxxxx5aw",
    "appUUID": "i5xxxxx1AQ",
    "isRecord": true,
    "isBan": false,
    "createdAt": "2021-01-18T06:56:29.432Z",
    "limit": 0
}

    响应包体参数：

    参数 类型 描述
    uuid string 房间的 UUID，即房间的全局唯一标识符。
    teamUUID string 互动白板控制台账号的唯一标识符。
    appUUID string 互动白板项目的唯一标识符。
    isRecord boolean 房间是否开启录制：
  • true：开启。
  • false: 不开启。
    		•
    isBan boolean 房间是否被封禁：
  • true：已封禁。
  • false: 未封禁。
    		•
    createdAt string 创建房间的 UTC 时间。
    limit integer 房间内可写人数（拥有 writer 或 admin 权限的用户）的上限。如果值为 0，则表示无限制。

    如果状态码不为 200，则请求失败。响应包体中包含 message 字段，描述失败的具体原因。

    获取房间列表（GET）

    获取房间列表。

    接口原型

    • 方法：GET
    • 接入点：https://api.netless.link/v5/rooms

    请求头部

    该 API 需要在 HTTP 请求头部填入以下参数：

    参数 类型 是否必需 描述
    token string 必需 拥有 writer 或 admin 权限的 SDK Token，可通过以下方式获取：
  • 在声网控制台生成用于测试的 SDK Token，详见获取互动白板项目的安全密钥。
  • 调用服务端 RESTful API， 详见生成 SDK Token。
  • 在 app 服务端用代码生成，详见在 app 服务端生成 Token。
    		•
    region string 必需 指定处理该请求的数据中心，取值如下：
  • cn-hz：中国杭州，服务区覆盖中国大陆地区及其他数据中心未覆盖的区域。
  • us-sv：美国硅谷，服务区覆盖北美洲、南美洲。
  • sg：新加坡，服务区覆盖新加坡、东亚、东南亚。
  • in-mum：印度孟买，服务区覆盖印度。
  • eu：欧洲（法兰克福）,服务区覆盖欧洲。

    • 查询参数

    该 API 可以传入以下查询参数：

    参数 类型 是否必需 描述
    beginUUID string 可选 查询的起始房间的 UUID。
    limit integer 可选 返回的房间列表的最大长度，取值范围为 (0,1000]。如果不填，则最多返回 100 条房间信息。

    请求示例

    
GET /v5/rooms/?beginUUID=0e6exxxxxx4d95&limit=2
Host: api.netless.link
region: cn-hz
Content-Type: application/json
token: NETLESSSDK_YWs9QlxxxxxxM2MjRi

    HTTP 响应

    所有可能的响应状态码详见状态码汇总表。

    如果状态码为 200，则请求成功。响应包含返回的操作结果和数据。

    请求成功响应示例：

    "status": 200,
"body":
[
    {
        "uuid": "0e6exxxxxxd95",
        "teamUUID": "RMmxxxxxxaw",
        "appUUID": "vVxxxxzJF-A",
        "isRecord": true,
        "isBan": false,
        "createdAt": "2020-12-20T14:02:54.846Z",
        "limit": 0
    },
    {
        "uuid": "1d4xxxxxxca69",
        "teamUUID": "RMmxxxxxx5aw",
        "appUUID": "vVsxxxxzJF-A",
        "isRecord": true,
        "isBan": false,
        "createdAt": "2020-12-20T14:10:29.265Z",
        "limit": 0
    }
]

    响应包体参数：

    参数 类型 描述
    uuid string 房间的 UUID，即房间的全局唯一标识符。
    teamUUID string 互动白板控制台账号的唯一标识符。
    appUUID string 互动白板项目的唯一标识符。
    isRecord boolean 房间是否开启录制：
  • true：开启。
  • false: 不开启。
    • isBan boolean 房间是否被封禁：
  • true：已封禁。
  • false: 未封禁。
    • createdAt string 创建房间的 UTC 时间。
    limit integer 房间内可写人数（拥有 writer 或 admin 权限的用户）上限。如果值为 0，表示无限制。

    如果状态码不为 200，则请求失败。响应包体中包含 message 字段，描述失败的具体原因。

    封禁房间 （PATCH）

    封禁或取消封禁指定的房间。

    房间被封禁后，互动白板服务会移除房间内的用户并禁止新用户加入该房间。

    你可以再次调用该 API，并在请求包体中将 isBan 设为 false，取消对房间的封禁。

    接口原型

    • 方法：PATCH
    • 接入点：https://api.netless.link/v5/rooms/{uuid}

    请求头部

    该 API 需要在 HTTP 请求头部填入以下参数：

    参数 类型 是否必需 描述
    token string 必需 拥有 admin 权限的 SDK Token 或 Room Token。
    SDK Token 可通过以下方式获取：
  • 在声网控制台生成用于测试的 SDK Token，详见获取互动白板项目的安全密钥。
  • 调用服务端 RESTful API， 详见生成 SDK Token。
  • 在 app 服务端用代码生成，详见在 app 服务端生成 Token。
    • Room Token 可以通过以下方式获取：
  • 调用服务端 RESTful API， 详见生成 Room Token。
  • 在 app 服务端用代码生成，详见在 app 服务端生成 Token。
    		•
    region string 必需 指定处理该请求的数据中心，取值如下：
  • cn-hz：中国杭州，服务区覆盖中国大陆地区及其他数据中心未覆盖的区域。
  • us-sv：美国硅谷，服务区覆盖北美洲、南美洲。
  • sg：新加坡，服务区覆盖新加坡、东亚、东南亚。
  • in-mum：印度孟买，服务区覆盖印度。
  • eu：欧洲（法兰克福）,服务区覆盖欧洲。

    • 请求路径

    该 API 需要在 URL 中传入以下参数：

    参数 类型 是否必需 描述
    uuid string 必需 房间的 UUID, 即房间的全局唯一标识符，可通过调用创建房间 API 或获取房间信息 API 获取。

    请求包体

    参数 类型 是否必需 描述
    isBan boolean 必需 是否封禁房间：
  • true：封禁。
  • false: （默认值）不封禁。
    		•

    请求示例

    PATCH /v5/rooms/0e6exxxxxx4d95
Host: api.netless.link
region: cn-hz
Content-Type: application/json
token: NETLESSSDK_YWs9xxxxxx5ZGM2MjRi

{
  "isBan": true
}

    HTTP 响应

    所有可能的响应状态码详见状态码汇总表。

    如果状态码为 201，则请求成功。响应包含返回的操作结果和数据。

    请求成功响应示例：

    "status": 201,
"body":
{
    "uuid": "0e6xxxxxx95",
    "teamUUID": "RMxxxxxaw",
    "appUUID": "vVxxxxxJF-A",
    "isRecord": true,
    "isBan": true,
    "createdAt": "2020-12-20T14:02:54.846Z",
    "limit": 0
}

    响应包体参数：

    参数 类型 描述
    参数 类型 描述
    uuid string 房间的 UUID，即房间的全局唯一标识符。
    teamUUID string 互动白板控制台账号的唯一标识符。
    appUUID string 互动白板项目的唯一标识符。
    isRecord boolean 房间是否开启录制：
  • true：开启。
  • false: 不开启。
    • isBan boolean 房间是否被封禁：
  • true：已封禁。
  • false: 未封禁。
    • createdAt string 创建房间的 UTC 时间。
    limit integer 房间内可写人数（拥有 writer 或 admin 权限的用户）的上限。如果值为 0，则表示无限制。

    如果状态码不为 201，则请求失败。响应包体中包含 message 字段，描述失败的具体原因。