2024/06/27 17:32:12

房间相关

创建课堂

课堂创建后，默认保留 5 天。

接口原型：

方法：POST
接入点：/{region}/edu/apps/{appId}/v2/rooms/{roomUuid}

请求参数

URL 参数

参数类型是否必填描述

region

String

必填

服务区域，可设为如下值：

cn：中国大陆
ap：亚太
na：北美
eu：欧洲

注意

对于同一课堂，服务端接口调用的区域需要与客户端课堂创建的区域一致，否则会报告“房间不存在”的错误。

appId

String

必填

你在声网控制台创建的项目的 App ID，详见获取 App ID。

roomUuid

String

必填

课堂 UUID。这是课堂的唯一标识符，也是加入 RTC 和 RTM 时所使用的频道名。长度在 64 字符以内。若该房间需要使用页面录制，长度需在 50 字符内。

以下为支持的字符集范围（共 89 个字符）:

26 个小写英文字母 a-Z
26 个大写英文字母 A-Z
10 个数字 0-9
空格
!, #, $, %, &, (, ), +, -, :, ;, <, =, ., >, ?, @, [, ], ^, _, {, }, |, ~, ,

请求包体参数

参数	类型	是否必填	描述
`roomType`	String	必填	房间类型，可设为： `0`: 一对一 `2`: 大班课 `4`: 小班课注意该字段不可更新。
`roomName`	String	必填	房间名称，用于用户显示目的。最长不可超过 64 字符。
`roomProperties`	Object	非必填	房间属性。
`roomProperties.schedule`	Object	非必填	课程计划，包含开始时间，持续时长，拖堂时长等属性。
`roomProperties.schedule.` `startTime`	Integer	非必填	课堂开始时间戳，单位为毫秒。该字段不可更新。
`roomProperties.schedule.` `duration`	Integer	非必填	课堂持续时长，单位为秒。如果你设置了课堂持续时长和拖堂时长，当开启录制时，会按照二者之和向上取整设置最长录制时间 `maxRecordingHour` 参数。详见设置录制状态的 `maxRecordingHour` 参数说明。
`roomProperties.schedule.` `closeDelay`	Integer	非必填	拖堂时长，单位为秒。当课堂持续时长结束后，课程会进入“结束”状态（`state`= 2），此时用户仍可以正常进入和逗留在教室。当拖堂时间结束时，课堂会进入“关闭”状态（`state`= 3），并踢出所有用户。
`roomProperties.processes`	Object	非必填	申请邀请流程，包含举手等功能。
`roomProperties.processes.` `handsUp`	Object	非必填	上台设置，包含上台人数上限等。
`roomProperties.processes.` `handsUp.maxAccept`	Integer	非必填	上台人数上限。
`roomProperties.processes.` `handsUp.defaultAcceptRole`	String	非必填	默认上台角色，若需要让学生进教室默认上台，则该属性传 `"audience"`；若不需要自动上台，该属性传 `""` 或不传。
`roomProperties.flexProps`	Object	非必填	初始化房间属性。用户可以根据自己的业务需求为任何教室设置自定义属性。灵活的教室将把这些属性的更改同步到教室中的所有客户端，以实现自己的业务拓展。详见房间属性最佳实践。
`roomProperties.widgets`	Object	非必填	房间内组件设置。
`roomProperties.widgets.` `netlessBoard`	Object	非必填	房间内白板组件设置。
`roomProperties.widgets.` `netlessBoard.state`	Integer	非必填	房间内白板组件状态。可设为： `0`: 禁用 `1`: 启用
`roomProperties.widgets.` `easemobIM`	Object	非必填	房间内聊天室组件设置。
`roomProperties.widgets.` `easemobIM.state`	Integer	非必填	房间内聊天室组件状态。可设为： `0`: 禁用 `1`: 启用
`roleConfig`	Object	非必填	角色配置。
`roleConfig.2`	Object	非必填	学生角色配置。
`roleConfig.2.limit`	Integer	非必填	学生人数限制。
`roleConfig.2.defaultStream`	Object	非必填	学生默认流配置。如果配置该选项，会按 `defaultStream` 的设置为第一次进教室的学生创建一条流，流的作用详见基本概念。本设置仅适用于云课堂场景。
`roleConfig.2.defaultStream.` `state`	Integer	非必填	学生默认流状态。可设为： `0`: 禁用 `1`: 启用
`roleConfig.2.defaultStream.` `videoState`	Integer	非必填	学生默认流视频状态。可设为： `0`: 禁用 `1`: 启用
`roleConfig.2.defaultStream.` `audioState`	Integer	非必填	学生默认流音频状态。可设为： `0`: 禁用 `1`: 启用

请求示例

Shell
curl -X POST 'https://api.sd-rtn.com/{region}/edu/apps/{yourAppId}/v2/rooms/test_class' \
-H 'Content-Type: application/json;charset=UTF-8' \
-H 'Authorization: agora token={educationToken}' \
--data-raw '{
  "roomName": "test_class",
  "roomType": 4,
  "roomProperties": {
    "schedule": {
      "startTime": 1655452800000,
      "duration": 600,
      "closeDelay": 300
    },
    "processes": {
      "handsUp": {
        "maxAccept": 10
      }
    }
  }
}'

响应参数

参数类型描述

code

Integer

响应状态码：

0: 请求成功。
非 0: 请求失败。详见响应状态码。

msg

String

接口响应的文字信息。

ts

Number

当前服务端的 Unix 时间戳，UTC 时间，单位为毫秒。

响应示例

JSON
{
  "msg": "Success",
  "code": 0,
  "ts": 1610167740309
}

创建云课堂房间

若要使用云课堂，需要先调用服务端接口创建房间，以下是创建云课堂房间的请求示例。

Shell
curl -X POST 'https://api.agora.io/{region}/edu/apps/{YourAppId}/v2/rooms/test_room' \
-H 'Content-Type: application/json;charset=UTF-8' \
-H 'Authorization: agora token={educationToken}' \
--data-raw '{
  "roomName": "test_class",  //(Required)
  "roomType": 4,  // (Required)
  "roleConfig": {  // (Required) The audio and video permissions of students joining the room are turned on or off by default.
    "2": {     
      "limit": 50,  
      "defaultStream": {
        "state": 1,
        "videoState": 1,
        "audioState": 1
      }
    }
  },
  "roomProperties": {
    "schedule": {
      "startTime": 1655452800000,
      "duration": 600,
      "closeDelay": 300
    },
    "flexProps": {  // (Optional) The user's backend can pass customized parameters to the room through this parameter.Users can set custom attributes for any classroom based on their own business needs. Flexible Classroom will synchronize changes in this attribute to all clients in the classroom to realize your own business expansion.
      "exampleKey": "exampleValue"
    },
    "widgets": {  // The state of the widgets in the classroom : on or off
      "netlessBoard": {  // (Required) 
        "state": 0
      },
      "easemobIM": {
        "state": 1
      }
    }
  }
}'

查询课堂

返回房间对象所有信息。

接口原型

方法：GET
接入点：/{region}/edu/apps/{appId}/v2/rooms/{roomUuid}

请求参数

URL 参数

参数类型是否必填描述

region

String

必填

服务区域，可设为如下值：

cn：中国大陆
ap：亚太
na：北美
eu：欧洲

注意

对于同一课堂，服务端接口调用的区域需要与客户端课堂创建的区域一致，否则会报告“房间不存在”的错误。

appId

String

必填

你在声网控制台创建的项目的 App ID，详见获取 App ID。

roomUuid

String

必填

课堂 UUID。这是课堂的唯一标识符，也是加入 RTC 和 RTM 时所使用的频道名。长度在 64 字符以内。若该房间需要使用页面录制，长度需在 50 字符内。

以下为支持的字符集范围（共 89 个字符）:

26 个小写英文字母 a-Z
26 个大写英文字母 A-Z
10 个数字 0-9
空格
!, #, $, %, &, (, ), +, -, :, ;, <, =, ., >, ?, @, [, ], ^, _, {, }, |, ~, ,

请求示例

Shell
curl -X GET 'https://api.sd-rtn.com/{region}/edu/apps/{yourAppId}/v2/rooms/test_class' \
-H 'Content-Type: application/json;charset=UTF-8' \
-H 'Authorization: agora token={educationToken}' \

响应参数

参数	类型	描述
`code`	Integer	响应状态码： `0`: 请求成功。非 `0`: 请求失败。详见响应状态码。
`msg`	String	接口响应的文字信息。
`ts`	Number	当前服务端的 Unix 时间戳，UTC 时间，单位为毫秒。
`data`	Object	返回数据，包含以下字段： `roomUuid`: String 型，房间ID。 `roomName`: String 型，房间名。 `createTime`: Integer 型，创建房间时间戳。 `roomProperties`: Object 型，房间属性。 `roomType`: Integer 型，房间类型。 `0`: 1v1。 `2`: 大班课。 `4`: 小班课。 `schedule`: Object 型，课程计划。 `state`: Integer 型，房间状态。 `0`: 未开始。 `1`: 开始。 `2`: 结束。 `3`: 关闭。 `startTime`: Integer 型，开始时间。 `endTime`: Integer 型，结束时间。 `closeTime`: Integer 型，关闭时间。 `widgets`: Object 型，组件集合。 `netlessBoard`: Object 型，白板组件。 `extra`: Object 型，扩展信息。 `boardAppId`: String 型，白板 App ID。 `boardId`: String 型，白板房间 ID。 `boardToken`: String 型，白板房间 Token。 `boardRegion`: String 型，白板区域。 `state`: Integer 型，组件状态。 `0`: Integer 型，未激活。 `1`: Integer 型，激活。 `easemobIM`: Object 型，聊天室组件。 `extra`: Object 型，扩展信息。 `orgName`: String 型，组织名。 `appName`: String 型，app 名。 `chatRoomId`: String 型，聊天室 ID。 `appKey`: String 型，app Key。 `state`: Integer 型，组件状态。 `0`: Integer 型，未激活。 `1`: Integer 型，激活。

响应示例

JSON
{
  "msg": "Success",
  "code": 0,
  "ts": 1684231543281,
  "data": {
    "roomName": "jasoncai's Room",
    "roomUuid": "3579768dd1e1eec8522d3ed76992afd04",
    "scenario": "education",
    "roleConfig": {
      ...
    },
    "roomProperties": {
      "reward": {
        ...
      },
      "processes": {
        "handsUp": {
          ...
        },
        "openCamera": {
          ...
        },
        "remoteControl": {
          ...
        },
        "waveArm": {
          ...
        }
      },
      "im": {
        "huanxin": {
          ...
        }
      },
      "screen": {
        ...
      },
      "groups": {
        ...
      },
      "carousel": {
        ...
      },
      "widgets": {
        "netlessBoard": {
          "extra": {
            ...
          },
          "state": 1
        },
        "easemobIM": {
          "extra": {
            ...
          }
        }
      },
      "schedule": {
        "closeDelay": 600,
        "duration": 1800
      },
      "webhookConfig": {
        ...
      },
      "record": {
        ...
      },
      "state": 0,
      "board": {
        "info": {
          ...
        }
      },
      "roomType": 4
    },
    "roomTemplate": "edu_medium_v1",
    "muteChat": {},
    "muteVideo": {},
    "muteAudio": {},
    "state": 0,
    "checkState": false,
    "createTime": 1683884683422
  }
}

设置课堂状态

设置课堂状态。课堂状态可以设置为以下值：

0: 未开始。
1: 开始。
2: 结束。课堂时间结束，但在拖堂时间内，用户可以加入课堂和在课堂内逗留。
3: 关闭。拖堂时间结束，课堂关闭，所有用户被踢出并无法再进入。

详见灵动课堂有哪些课堂状态？

接口原型：

方法：PUT
接入点：/{region}/edu/apps/{appId}/v2/rooms/{roomUuid}/states/{state}

请求参数

URL 参数

参数	类型	是否必填	描述
`region`	String	必填	服务区域，可设为如下值： `cn`：中国大陆 `ap`：亚太 `na`：北美 `eu`：欧洲注意对于同一课堂，服务端接口调用的区域需要与客户端课堂创建的区域一致，否则会报告“房间不存在”的错误。
`appId`	String	必填	你在声网控制台创建的项目的 App ID，详见获取 App ID。
`roomUuid`	String	必填	课堂 UUID。这是课堂的唯一标识符，也是加入 RTC 和 RTM 时所使用的频道名。长度在 64 字符以内。若该房间需要使用页面录制，长度需在 50 字符内。以下为支持的字符集范围（共 89 个字符）: 26 个小写英文字母 a-Z 26 个大写英文字母 A-Z 10 个数字 0-9 空格 `!`, `#`, `$`, `%`, `&`, `(`, `)`, `+`, `-`, `:`, `;`, `<`, `=`, `.`, `>`, `?`, `@`, `[`, `]`, `^`, `_`, `{`, `}`, `\|`, `~`, `,`
`state`	Integer	必填	课堂状态，可以设置为以下值： `0`: 未开始。 `1`: 开始。 `2`: 结束。课堂时间结束，但在拖堂时间内，用户可以加入课堂和在课堂内逗留。 `3`: 关闭。拖堂时间结束，课堂关闭，所有用户被踢出并无法再进入。

请求示例

Shell
curl -X PUT 'https://api.sd-rtn.com/{region}/edu/apps/{yourAppId}/v2/rooms/test_class/states/1' \
-H 'Authorization: agora token={educationToken}'

响应参数

参数类型描述

code

Integer

响应状态码：

0: 请求成功。
非 0: 请求失败。详见响应状态码。

msg

String

接口响应的文字信息。

ts

Number

当前服务端的 Unix 时间戳，UTC 时间，单位为毫秒。

响应示例

JSON
{
  "code": 0,
  "msg": "Success",
  "ts": 1610450153520
}

更新课堂自定义属性

新增或更新指定课堂的自定义属性。

你可以结合自身的业务需求，设置任意课堂自定义属性，灵动课堂会将这个属性的变更同步到所有端，以此来实现你自己的扩展业务。详见如何设置自定义用户属性和课堂属性？

接口原型：

方法：PUT
接入点：/{region}/edu/apps/{appId}/v2/rooms/{roomUuid}/properties

请求参数

URL 参数

参数类型是否必填描述

region

String

必填

服务区域，可设为如下值：

cn：中国大陆
ap：亚太
na：北美
eu：欧洲

注意

对于同一课堂，服务端接口调用的区域需要与客户端课堂创建的区域一致，否则会报告“房间不存在”的错误。

appId

String

必填

你在声网控制台创建的项目的 App ID，详见获取 App ID。

roomUuid

String

必填

课堂 UUID。这是课堂的唯一标识符，也是加入 RTC 和 RTM 时所使用的频道名。长度在 64 字符以内。若该房间需要使用页面录制，长度需在 50 字符内。

以下为支持的字符集范围（共 89 个字符）:

26 个小写英文字母 a-Z
26 个大写英文字母 A-Z
10 个数字 0-9
空格
!, #, $, %, &, (, ), +, -, :, ;, <, =, ., >, ?, @, [, ], ^, _, {, }, |, ~, ,

请求包体参数

参数	类型	是否必填	描述
`properties`	Object	必填	本次设置的课堂自定义属性。
`cause`	Object	非必填	本次设置原因。

请求示例

Shell
curl -X PUT 'https://api.sd-rtn.com/{region}/edu/apps/{yourAppId}/v2/rooms/test_class/properties' \
-H 'Content-Type: application/json;charset=UTF-8' \
-H 'Authorization: agora token={educationToken}' \
--data-raw '{
  "properties": {
    "key1": "value1",
    "key2": "value2"
  },
  "cause": {}
}'

响应参数

参数类型描述

code

Integer

响应状态码：

0: 请求成功。
非 0: 请求失败。详见响应状态码。

msg

String

接口响应的文字信息。

ts

Number

当前服务端的 Unix 时间戳，UTC 时间，单位为毫秒。

响应示例

JSON
{
  "msg": "Success",
  "code": 0,
  "ts": 1610167740309
}

删除课堂自定义属性

删除指定课堂的自定义属性。

你可以删除任意课堂自定义属性，灵动课堂会将这个属性的变更同步到所有端，以此来实现你自己的扩展业务。详见如何设置自定义用户属性和课堂属性？

接口原型：

方法：DELETE
接入点：/{region}/edu/apps/{appId}/v2/rooms/{roomUuid}/properties

请求参数

URL 参数

参数类型是否必填描述

region

String

必填

服务区域，可设为如下值：

cn：中国大陆
ap：亚太
na：北美
eu：欧洲

注意

对于同一课堂，服务端接口调用的区域需要与客户端课堂创建的区域一致，否则会报告“房间不存在”的错误。

appId

String

必填

你在声网控制台创建的项目的 App ID，详见获取 App ID。

roomUuid

String

必填

课堂 UUID。这是课堂的唯一标识符，也是加入 RTC 和 RTM 时所使用的频道名。长度在 64 字符以内。若该房间需要使用页面录制，长度需在 50 字符内。

以下为支持的字符集范围（共 89 个字符）:

26 个小写英文字母 a-Z
26 个大写英文字母 A-Z
10 个数字 0-9
空格
!, #, $, %, &, (, ), +, -, :, ;, <, =, ., >, ?, @, [, ], ^, _, {, }, |, ~, ,

请求包体参数

参数	类型	是否必填	描述
`properties`	String[]	必填	本次删除的课堂自定义属性对应的 key。
`cause`	Object	非必填	本次删除原因。

请求示例

Shell
curl -X DELETE 'https://api.sd-rtn.com/{region}/edu/apps/{yourAppId}/v2/rooms/test_class/properties' \
-H 'Content-Type: application/json;charset=UTF-8' \
-H 'Authorization: agora token={educationToken}' \
--data-raw '{
  "properties": ["key1", "key2"],
  "cause": {}
}'

响应参数

参数类型描述

code

Integer

响应状态码：

0: 请求成功。
非 0: 请求失败。详见响应状态码。

msg

String

接口响应的文字信息。

ts

Number

当前服务端的 Unix 时间戳，UTC 时间，单位为毫秒。

响应示例

JSON
{
  "msg": "Success",
  "code": 0,
  "ts": 1610167740309
}

开启/关闭分组讨论

开启或关闭课堂分组讨论功能。

接口原型：

方法：PUT
接入点：/{region}/edu/apps/{appId}/v2/rooms/{roomUUid}/groups/states/{state}

请求参数

URL 参数

参数	类型	是否必填	描述
`region`	String	必填	服务区域，可设为如下值： `cn`：中国大陆 `ap`：亚太 `na`：北美 `eu`：欧洲注意对于同一课堂，服务端接口调用的区域需要与客户端课堂创建的区域一致，否则会报告“房间不存在”的错误。
`appId`	String	必填	你在声网控制台创建的项目的 App ID，详见获取 App ID。
`roomUUid`	String	必填	课堂 UUID。这是课堂的唯一标识符，也是加入 RTC 和 RTM 时所使用的频道名。长度在 64 字符以内。若该房间需要使用页面录制，长度需在 50 字符内。以下为支持的字符集范围（共 89 个字符）: 26 个小写英文字母 a-Z 26 个大写英文字母 A-Z 10 个数字 0-9 空格 `!`, `#`, `$`, `%`, `&`, `(`, `)`, `+`, `-`, `:`, `;`, `<`, `=`, `.`, `>`, `?`, `@`, `[`, `]`, `^`, `_`, `{`, `}`, `\|`, `~`, `,`
`state`	Integer	必填	是否开启分组讨论： `1`: 开启。 `0`: 关闭。

请求包体参数

开启分组讨论时需要在请求包体中传入以下参数；关闭分组讨论时不需要传任何参数。

参数类型是否必填描述

参数	类型	是否必填	描述
`groups`	Array	必填	待创建的分组列表。包含： `groupUuid`: （选填）待创建的分组 ID，String 型。如果不填，系统会自动分配一个 ID。 `groupName`: （选填）分组名，String 型。 `users`：（必填）分组内用户列表，Array 型。包含： `userUuid`：（必填）用户 UUID。这是用户的唯一标识符，也是登录 RTM 系统时所使用的用户 ID。长度在 64 字符以内。以下为支持的字符集范围（共 89 个字符）: 26 个小写英文字母 a-Z 26 个大写英文字母 A-Z 10 个数字 0-9 空格 `!`, `#`, `$`, `%`, `&`, `(`, `)`, `+`, `-`, `:`, `;`, `<`, `=`, `.`, `>`, `?`, `@`, `[`, `]`, `^`, `_`, `{`, `}`, `\|`, `~`, `,`

groups

Array

必填

待创建的分组列表。包含：

groupUuid: （选填）待创建的分组 ID，String 型。如果不填，系统会自动分配一个 ID。
groupName: （选填）分组名，String 型。
users：（必填）分组内用户列表，Array 型。包含：
- userUuid：（必填）
  用户 UUID。这是用户的唯一标识符，也是登录 RTM 系统时所使用的用户 ID。长度在 64 字符以内。
  
  以下为支持的字符集范围（共 89 个字符）:
  - 26 个小写英文字母 a-Z
  - 26 个大写英文字母 A-Z
  - 10 个数字 0-9
  - 空格
  - !, #, $, %, &, (, ), +, -, :, ;, <, =, ., >, ?, @, [, ], ^, _, {, }, |, ~, ,

请求示例

Shell
curl -X PUT 'https://api.sd-rtn.com/{region}/edu/apps/{yourAppId}/v2/rooms/test_class/states/1' \
-H 'Authorization: agora token={educationToken}' \
--data-raw '{
  "groups": [
    {
      "groupUuid": "group1",
      "groupName": "Group 01",
      "users": [
        {
          "userUuid": "user1"
        }
      ]
    }
  ]
}'

响应参数

参数类型描述

code

Integer

响应状态码：

0: 请求成功。
非 0: 请求失败。详见响应状态码。

msg

String

接口响应的文字信息。

ts

Number

当前服务端的 Unix 时间戳，UTC 时间，单位为毫秒。

响应示例

JSON
{
  "msg": "Success",
  "code": 0,
  "ts": 1672989034831
}

创建课堂​

请求参数​

URL 参数​

请求包体参数​

请求示例​

响应参数​

响应示例​

创建云课堂房间​

查询课堂​

接口原型​

请求参数​

URL 参数​

请求示例​

响应参数​

响应示例​

设置课堂状态​

请求参数​

URL 参数​

请求示例​

响应参数​

响应示例​

更新课堂自定义属性​

请求参数​

URL 参数​

请求包体参数​

请求示例​

响应参数​

响应示例​

删除课堂自定义属性​

请求参数​

URL 参数​

请求包体参数​

请求示例​

响应参数​

响应示例​

开启/关闭分组讨论​

请求参数​

URL 参数​

请求包体参数​

请求示例​

响应参数​

响应示例​

创建课堂

请求参数

URL 参数

请求包体参数

请求示例

响应参数

响应示例

创建云课堂房间

查询课堂

接口原型

请求参数

URL 参数

请求示例

响应参数

响应示例

设置课堂状态

请求参数

URL 参数

请求示例

响应参数

响应示例

更新课堂自定义属性

请求参数

URL 参数

请求包体参数

请求示例

响应参数

响应示例

删除课堂自定义属性

请求参数

URL 参数

请求包体参数

请求示例

响应参数

响应示例

开启/关闭分组讨论

请求参数

URL 参数

请求包体参数

请求示例

响应参数

响应示例