DescribeUsers

GET

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

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

调用频率限制

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

Request

Query Parameters

Action stringrequired

Possible values: [DescribeUsers]

接口原型参数

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

AppId uint32required

💡公共参数。AppId，ZEGO 分配的用户唯一凭证。

SignatureNonce stringrequired

💡公共参数。随机字符串。

Timestamp int64required

💡公共参数。Unix 时间戳，单位为秒。最多允许 10 分钟的误差。

Signature stringrequired

💡公共参数。签名，用于验证请求的合法性。

SignatureVersion stringrequired

Possible values: [2.0]

Default value: 2.0

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

IsTest string

Possible values: [true, false]

Default value: false

💡公共参数。是否为测试环境。设为 true 表示使用测试环境。2021-11-16 及之前在 ZEGO 控制台创建的项目默认是测试环境，可根据业务需求设置此参数；而之后创建的项目默认是正式环境。

RoomId stringrequired

房间 ID。

UserId string[]required

Possible values: >= 1, <= 10

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

Responses

操作成功

application/json

Schema
Example (from schema)
Example

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

RESPONSEClear

Click the "Send" button above and see the response here!

DescribeUsers

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

Request

Query Parameters

Responses​

Responses