服务端 API

搜索日志记录

使用 搜索日志记录 从可信后端调用 OpenIM 日志接口。按关键字、时间范围和分页参数检索业务方已登记的客户端本地日志记录，用于后台排障、客服定位和问题反馈跟进。请先在接入准备中配置 API 地址和 Token；接口参数通过请求头和 JSON 请求体传递。

HTTP 请求

POST {API_ADDRESS}/third/logs/search

请求示例

curl --request POST "${API_ADDRESS}/third/logs/search" \
  --header "Content-Type: application/json; charset=utf-8" \
  --header "operationID: ${OPERATION_ID}" \
  --header "token: ${ADMIN_TOKEN}" \
  --data-raw '{
  "keyword": "user_001",
  "startTime": 1719800000000,
  "endTime": 1719886400000,
  "pagination": {
    "pageNumber": 1,
    "showNumber": 20
  }
}'

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

参数

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

请求头

Header	是否必填	类型	说明
operationID	是	string	每次请求的唯一链路追踪 ID，建议由后端生成并写入日志。
token	是	string	APP 管理员 Token 或具备对应权限的用户 Token；仅保存在可信后端服务中。
Content-Type: application/json	是	string	请求体为 JSON 时必须设置。

请求体

{
  "keyword": "user_001",
  "startTime": 1719800000000,
  "endTime": 1719886400000,
  "pagination": {
    "pageNumber": 1,
    "showNumber": 20
  }
}

参数名	是否必填	类型	说明
keyword	否	string	搜索关键字，可匹配日志相关字段。
startTime	否	int	起始时间，Unix 毫秒时间戳；与 `endTime` 同时为 0 时服务端使用默认范围。
endTime	否	int	结束时间，Unix 毫秒时间戳。
pagination	是	object	分页参数。
pagination.pageNumber	是	int	页码，从 1 开始。
pagination.showNumber	是	int	每页数量，必须大于 0。

响应

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

{
  "errCode": 0,
  "errMsg": "",
  "errDlt": "",
  "data": {
    "logsInfos": [
      {
        "userID": "user_001",
        "platform": "Android",
        "url": "https://example.com/logs/openim.log",
        "createTime": 1719800000000,
        "nickname": "Tom",
        "logID": "1234567890",
        "filename": "openim.log",
        "systemType": "",
        "ex": "",
        "version": "1.0.0"
      }
    ],
    "total": 1
  }
}

响应参数

参数名	类型	说明
errCode	int	业务错误码，0 表示成功。
errMsg	string	错误简要信息，成功时通常为空。
errDlt	string	错误详细信息，成功时通常为空。
data	object	接口返回数据。
data.logsInfos	array	日志记录列表。
data.logsInfos[].userID	string	上传日志的用户 ID。
data.logsInfos[].platform	string	日志来源平台名称。
data.logsInfos[].url	string	日志文件 URL。
data.logsInfos[].createTime	int	日志记录创建时间，Unix 毫秒时间戳。
data.logsInfos[].nickname	string	上传用户昵称。
data.logsInfos[].logID	string	日志 ID。
data.logsInfos[].filename	string	日志文件名。
data.logsInfos[].systemType	string	系统类型。
data.logsInfos[].ex	string	扩展字段。
data.logsInfos[].version	string	客户端或应用版本号。
data.total	int	符合条件的日志总数。

错误

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

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

错误场景	可能原因	处理方式
鉴权失败	`token` 缺失、过期，或调用账号没有该接口权限。	重新获取有效 Token，并在可信后端调用接口。
链路追踪困难	`operationID` 缺失或在大量请求中重复使用。	为每次请求生成独立 `operationID`，并在服务端日志中保留。
参数校验失败	请求体字段类型、必填字段或枚举值不符合接口要求。	对照请求体参数表和限制说明检查字段。

权限和限制

只读查询，不删除或修改日志记录。
必须使用 APP 管理员 Token 调用。
startTime 不能大于 endTime。
pagination 必填。
所有数组型请求参数建议控制在 1000 个元素以内。

HTTP 请求

请求示例

参数

请求头

请求体

响应

响应参数

错误

权限和限制

相关页面