DescribeUsers

GET

https://rtc-api.zego.im/

调用本接口，可以查询某一房间内的用户的基本状态，包括用户是否在房间、用户的角色、登录房间的时间等。

调用频率限制

同一个 AppID 下所有房间：10 次/秒

Request

Query Parameters

Action string必填

可选值: [DescribeUsers]

接口原型参数

https://rtc-api.zego.im?Action=DescribeUsers

AppId uint32必填

💡公共参数。应用 Id，由 ZEGO 分配的用户唯一凭证。可从 ZEGO 控制台获取。

SignatureNonce string必填

💡公共参数。16 位 16 进制随机字符串（8 字节随机数的 hex 编码）。生成算法可参考签名示例。

Timestamp int64必填

💡公共参数。当前 Unix 时间戳，单位为秒。生成算法可参考签名示例，最多允许 10 分钟的误差。

Signature string必填

💡公共参数。签名，用于验证请求的合法性。请参考签名机制生成。

SignatureVersion string必填

可选值: [2.0]

默认值: 2.0

💡公共参数。签名版本号。

RoomId string必填

房间 ID。

UserId string[]必填

可选值: >= 1, <= 10

需要查询状态的用户 ID 列表，最大支持 10 个用户 ID。

Responses

操作成功

application/json

数据结构
按数据结构生成的示例
示例

Schema

Code int32

返回码。以下仅列出了接口业务逻辑相关的部分返回码，完整返回码请参考全局返回码。

返回码	说明	处理建议
2	输入参数错误。	-
3	输入参数长度过长。	请重新输入参数。
206	App 请求 QPS 过高被限制。	降低请求频率，或联系 ZEGO 技术支持提高 QPS 限制阈值。
50001	房间不存在。 📌说明: 1. 当房间内没有用户时，房间会被服务端自动销毁。 2. 当房间内只有一个用户时，该用户退出房间或被踢出房间，房间会被服务端自动销毁。 3. 当用户心跳请求超时 100 秒后，用户会掉线；所有用户都不在房间后，房间会被服务端自动销毁。	请确认请求房间 RoomId 是否存在。

Message string

操作结果描述。

RequestId string

请求 ID。

Data object

UserStatusList object[]

用户状态列表。

Array[

UserId string

用户 ID。

Status uint32

用户状态。0：不在房间。1：在房间内。

LoginTime int64

该用户登录房间的时间，Unix 毫秒时间戳。

UserRole uint32

用户角色。

1：主播。
2：观众。
4：管理员，该类型用户主要存在于云录制、音视频流审核等场景中，客户端 SDK 的用户相关接口会过滤该类型用户。

该返回参数，仅在接入 LiveRoom 服务时有实际意义，接入 Express 服务时请忽略此参数。

]

{
  "Code": 0,
  "Message": "string",
  "RequestId": "string",
  "Data": {
    "UserStatusList": [
      {
        "UserId": "string",
        "Status": 0,
        "LoginTime": 0,
        "UserRole": 0
      }
    ]
  }
}

{
  "Code": 0,
  "Message": "string",
  "RequestId": "string",
  "Data": {
    "UserStatusList": [
      {
        "UserId": "string",
        "Status": 0,
        "LoginTime": 0,
        "UserRole": 0
      }
    ]
  }
}

{
  "Code": 0,
  "Data": {
    "UserStatusList": [
      {
        "UserId": "a",
        "Status": 1,
        "LoginTime": 1675674019365,
        "UserRole": 1
      },
      {
        "UserId": "b",
        "Status": 1,
        "LoginTime": 1675674019455,
        "UserRole": 1
      }
    ]
  },
  "Message": "success",
  "RequestId": "TestRequestId1675674022729915000"
}

{
  "Code": 0,
  "Data": {
    "UserStatusList": [
      {
        "UserId": "a",
        "Status": 1,
        "LoginTime": 1675674019365,
        "UserRole": 1
      },
      {
        "UserId": "b",
        "Status": 1,
        "LoginTime": 1675674019455,
        "UserRole": 1
      }
    ]
  },
  "Message": "success",
  "RequestId": "TestRequestId1675674022729915000"
}

CURL

ZEGO 签名生成器

AppId

ServerSecret

RESPONSE清除

点击上方 “发送” 按钮，在此处查看响应。

DescribeUsers

https://rtc-api.zego.im/

Request

Query Parameters

Responses​

Responses