服务端 API

查询用户列表

使用 查询用户列表 从可信后端分页读取 OpenIM 已注册用户。请求体中的 pagination.pageNumber 表示页码，从 1 开始；pagination.showNumber 表示每页数量；响应中的 data.total 是用户总数，data.users 是当前页用户列表。

HTTP 请求

POST {API_ADDRESS}/user/get_users

请求示例

curl --request POST "${API_ADDRESS}/user/get_users" \
  --header "Content-Type: application/json; charset=utf-8" \
  --header "operationID: 1646445464564" \
  --header "token: ${ADMIN_TOKEN}" \
  --data-raw '{
  "pagination": {
    "pageNumber": 1,
    "showNumber": 100
  }
}'

安全提示：管理员 Token 只能保存在可信后端服务中，不能下发到客户端或写入前端代码。客户端登录应使用服务端签发的用户 Token。

参数

此接口通过请求头传入链路追踪信息和鉴权凭证，通过 JSON 请求体传递业务参数。

请求头

请求头	示例值	是否必填	类型	说明
operationID	1646445464564	必填	string	用于全局链路追踪，建议使用时间戳，在每个请求中独立
token	eyJhbxxxx3Xs	必填	string	管理员 token

请求体参数

{
  "pagination": {
    "pageNumber": 1,
    "showNumber": 100
  }
}

参数名	是否必填	类型	说明
pagination	必填	object	分页参数结构体
pagination.pageNumber	必填	int	当前页码，从 1 开始
pagination.showNumber	必填	int	当前页请求数量
statuses 商业版	选填	int[]	按用户账号状态筛选，元素参见用户模块的 `UserStatus`。

响应

请求被 OpenIM 正常处理时通常返回 200 OK。业务是否成功以响应体中的 errCode 为准；errCode === 0 表示成功，非 0 表示业务错误。

{
  "errCode": 0,
  "errMsg": "",
  "errDlt": "",
  "data": {
    "total": 47,
    "users": [
      {
        "userID": "user_001",
        "nickname": "Alice",
        "faceURL": "https://cdn.example.com/avatar/u_001.png",
        "ex": "",
        "createTime": 0,
        "appMangerLevel": 18,
        "globalRecvMsgOpt": 0
      },
      {
        "userID": "user_002",
        "nickname": "Bob",
        "faceURL": "",
        "ex": "",
        "createTime": 1688381391965,
        "appMangerLevel": 18,
        "globalRecvMsgOpt": 0
      }
    ]
  }
}

响应属性列表

参数名	类型	说明
errCode	int	错误码，0 表示成功
errMsg	string	错误简要信息，为空
errDlt	errDlt	错误详细信息，为空
data	object	通用数据对象，具体结构见下方
total	int	用户总数
users	array	用户模块的 `UserInfo` 列表

分页读取建议

从 pagination.pageNumber = 1 开始请求，并用 pagination.showNumber 控制每页数量。响应中的 data.total 表示总用户数，业务后端可以用 Math.ceil(data.total / pagination.showNumber) 计算总页数，并在当前页码小于总页数时继续请求下一页。

错误

如果请求失败，OpenIM 返回错误对象。更多错误码说明见错误码。

{
  "errCode": 1004,
  "errMsg": "RecordNotFoundError",
  "errDlt": ": [1004]RecordNotFoundError"
}

参数名	类型	说明
errCode	int	错误码，具体查看全局错误码文档
errMsg	string	错误简要信息
errDlt	errDlt	错误详细信息

常见错误场景

错误场景	可能原因	处理方式
鉴权失败	`token` 缺失、过期，或不是可调用管理端接口的管理员 Token。	重新获取 APP 管理员 Token，并只在可信后端保存。
链路追踪困难	`operationID` 缺失或在大量请求中重复使用。	为每次请求生成独立 `operationID`，并在服务端日志中保留。
参数校验失败	请求体字段类型、必填字段或枚举值不符合接口要求。	对照请求体参数表检查字段类型和必填项。
分页参数错误	`pagination.pageNumber` 小于 1，或 `pagination.showNumber` 超出服务端允许范围。	从第 1 页开始读取，并把每页数量限制在服务端允许范围内。

这个页面有帮助吗？