获取房间用户列表

更新时间：2025-04-15 17:17

1 描述

调用本接口获取房间内用户列表。

2 接口原型

请求方法：GET
请求地址：https://rtc-api.zego.im/?Action=DescribeUserList
传输协议：HTTPS
调用频率限制：
- 同一个 AppID 下：200 次/秒
- 对同一个房间：1 次/1 秒

3 请求参数

以下请求参数列表仅列出了接口请求参数和部分公共参数，完整公共参数列表请参考调用方式中的 “2.1 公共请求参数”。

参数	类型	是否必选	描述
RoomId	String	是	房间 ID。房间不存在会返回空列表。
Mode	Int32	否	用户登录房间的时间排序，默认值为 0。 0：按时间正序 1：按时间倒序
Limit	Int32	否	单次请求返回的用户个数，取值范围 0-200，即调用本接口一次最多返回 200 个用户。默认值为 200，房间内人数超过 200 时，需要根据前一次调用本接口时、返回结果中的 Marker（用户起始位标识）取值，再次调用本接口查询其余用户。例如，房间内有 450 个用户，调用本接口查询用户列表时：第一次调用本接口，入参 Marker 传空，查询第 1 ～ 200 的用户；返回结果中 Marker 值假设为 “marker1”。第二次调用本接口，入参 Marker 取值为 “marker1”，查询第 201 ～ 400 的用户；返回结果中 Marker 值假设为 “marker2”。第三次调用本接口，入参 Marker 取值为 “marker2”，查询第 401 ～ 450 的用户；查询完毕，返回结果中 Marker 为空。
Marker	String	否	查询用户起始位标识，每次请求的响应有返回，为空时从头开始返回用户信息。

4 请求示例

https://rtc-api.zego.im/?Action=DescribeUserList
&RoomId=room_demo
&Mode=0
&Limit=2
&Marker=
&<公共请求参数>

5 响应参数

参数	类型	描述
Code	Int32	返回码。
Message	String	操作结果描述。
RequestId	String	请求 ID。
Data	Object	响应数据。
Marker	String	用户起始位标识。
UserList	Array of Object	用户列表。
UserId	String	用户名。
UserName	String	用户昵称。
UserRole	UInt32	用户角色。 1：主播。 2：观众。 4：管理员，该类型用户主要存在于云录制、音视频流审核等场景中，客户端 SDK 的用户相关接口会过滤该类型用户。该返回参数，仅在接入 LiveRoom 服务时有实际意义，接入 Express 服务时请忽略此参数。

6 响应示例

{
    "Code": 0,
    "Message": "success",
    "RequestId": "TestRequestId1635940600561291000",
    "Data": {
        "Marker": "1635940599950-user2",
        "UserList": [
            {
                "UserId": "user1",
                "UserName": "user1",
                "UserRole": 1
            },
            {
                "UserId": "user2",
                "UserName": "user2",
                "UserRole": 2
            }
        ]
    }
}

7 返回码

请参考全局返回码。