服务端 API v2
  • API概览
  • 快速开始
  • 调用方式
  • 房间信令接口
  • 混流接口
  • 媒体服务接口
  • 媒体文件接口
  • 音视频流审核接口
  • 场景服务接口
  • 回调说明
  • 全局返回码
  • 使用 Postman 调试

获取房间用户列表

更新时间:2022-11-25 15:18

1 描述

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

2 接口原型

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

3 请求参数

以下请求参数列表仅列出了接口请求参数和部分公共参数,完整公共参数列表请参考 调用方式 - 公共请求参数

参数 类型 是否必选 描述
RoomId
String
房间 ID。房间不存在会返回空列表。
Mode
Int
用户登录房间的时间排序,默认值为 0。
  • 0:按时间正序
  • 1:按时间倒序
Limit
Int
单次请求返回的用户个数,取值范围 0-200,即调用本接口一次最多返回 200 个用户。房间内人数超过 200 时,需要根据前一次调用本接口时、返回结果中的 Marker(用户起始位标识)取值,再次调用本接口查询其余用户。

例如,房间内有 450 个用户,调用本接口查询用户列表时:

  1. 第一次调用本接口,入参 Marker 传空,查询第 1 ~ 200 的用户;返回结果中 Marker 值假设为  “marker1”。
  2. 第二次调用本接口,入参 Marker 取值为 “marker1”,查询第 201 ~ 400 的用户;返回结果中 Marker 值假设为 “marker2”。
  3. 第三次调用本接口,入参 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
Number
返回码。
Message
String
操作结果描述。
RequestId
String
请求 ID。
Data
Object
响应数据。
└ Marker
String
用户起始位标识。
└ UserList
Array of Object
用户列表。
  └ UserId
String
用户名。
  └ UserName
String
用户昵称。

6 响应示例

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

7 返回码

请参考 全局返回码