用户相关

查询指定用户

接口原型：

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

请求参数

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 空格 !, #, $, %, &, (, ), +, -, :, ;, <, =, ., >, ?, @, [, ], ^, _, {, }, |, ~, ,
userUuid	String	必填	用户 UUID。这是用户的唯一标识符，也是登录 RTM 系统时所使用的用户 ID。长度在 64 字符以内。 以下为支持的字符集范围（共 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/users/test_user' \
-H 'Authorization: agora token={educationToken}' 

响应参数

参数	类型	描述
code	Integer	响应状态码： 0: 请求成功。 非 0: 请求失败。详见响应状态码。
msg	String	接口响应的文字信息。
ts	Number	当前服务端的 Unix 时间戳，UTC 时间，单位为毫秒。
data	Object	返回数据，包含以下字段： userUuid: 用户 ID。 userName: 用户名称。 role: 用户角色： 1: 老师 2: 学生 3: 助教 streamUuid: 流 ID。 state: 该用户是否在线： 0：不在线 1：在线 userProperties: 用户属性。 updateTime: 更新时间。

响应示例

JSON

{
  "msg": "Success",
  "code": 0,
  "ts": 1658126805245,
  "data": {
    "userName": "jasoncai",
    "userUuid": "681d9aca4924e9a84ad301e8cca438a71",
    "role": "1",
    "userProperties": {},
    "updateTime": 1658126782174,
    "streamUuid": "1417753684",
    "state": 1
  }
}

更新用户自定义属性

新增或更新指定用户的自定义属性。

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

接口原型：

• 方法：PUT
• 接入点：/{region}/edu/apps/{appId}/v2/rooms/{roomUuid}/users/{userUuid}/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 空格 !, #, $, %, &, (, ), +, -, :, ;, <, =, ., >, ?, @, [, ], ^, _, {, }, |, ~, ,
userUuid	String	必填	用户 UUID。这是用户的唯一标识符，也是登录 RTM 系统时所使用的用户 ID。长度在 64 字符以内。 以下为支持的字符集范围（共 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/users/test_user/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}/users/{userUuid}/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 空格 !, #, $, %, &, (, ), +, -, :, ;, <, =, ., >, ?, @, [, ], ^, _, {, }, |, ~, ,
userUuid	String	必填	用户 UUID。这是用户的唯一标识符，也是登录 RTM 系统时所使用的用户 ID。长度在 64 字符以内。 以下为支持的字符集范围（共 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/users/test_user/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
}

踢人

将指定用户从课堂中踢出。成功调用此接口后，服务端会触发一个用户进出课堂事件。你可通过该接口的 dirty 参数设置该用户后续是否还能再加入课堂。

接口原型：

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

请求参数

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 空格 !, #, $, %, &, (, ), +, -, :, ;, <, =, ., >, ?, @, [, ], ^, _, {, }, |, ~, ,
userUuid	String	必填	用户 UUID。这是用户的唯一标识符，也是登录 RTM 系统时所使用的用户 ID。长度在 64 字符以内。 以下为支持的字符集范围（共 89 个字符）: 26 个小写英文字母 a-Z 26 个大写英文字母 A-Z 10 个数字 0-9 空格 !, #, $, %, &, (, ), +, -, :, ;, <, =, ., >, ?, @, [, ], ^, _, {, }, |, ~, ,

请求包体参数

参数	类型	是否必填	描述
dirty	Object	非必填	用户踢人标记，包含以下字段： state: Integer 型，踢人状态： 1: 被踢，无法进入课堂。 0: 未被踢，可以进入课堂。 duration: Number 型，临时踢人持续时间，单位为秒。该字段仅在 state 为 1 时生效。从被踢出时开始计时，过了 duration 设置的时长后，用户自动恢复为未被踢状态。若不传该参数，则用户被永久踢出。

请求示例

Shell

curl -X POST 'https://api.sd-rtn.com/{region}/edu/apps/{yourAppId}/v2/rooms/test_class/users/test_user/exit' \
-H 'Content-Type: application/json;charset=UTF-8' \
-H 'Authorization: agora token={educationToken}' \
--data-raw '{
  "dirty": {
    "state": 1,
    "duration": 600
  }
}'

响应参数

参数	类型	描述
code	Integer	响应状态码： 0: 请求成功。 非 0: 请求失败。详见响应状态码。
msg	String	接口响应的文字信息。
ts	Number	当前服务端的 Unix 时间戳，UTC 时间，单位为毫秒。

响应示例

JSON

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