查询文件记录

按条件分页查询工作空间内的文件记录（来自文件元数据表，非实时对象存储扫描），支持按文件类型筛选、多字段排序与分页。

• 接口路径：POST /v1/openapi/app/files/query

请求头

参数名	必填	说明
Content-Type	是	application/json
Authorization	是	鉴权凭证，格式 Bearer sk_xxx

请求参数

{
  "user_id": "user123",
  "file_types": [".csv", ".txt"],
  "sort_by": "created_at",
  "sort_order": "desc",
  "page": 1,
  "page_size": 20
}

参数名	类型	必填	说明
user_id	string	是	业务方用户 ID，用于确定所属工作空间
file_types	string[]	否	文件类型筛选，按扩展名匹配，如 [".pdf", ".txt"]；不传则返回全部
sort_by	string	否	排序字段，可选 name / created_at / size，默认 created_at
sort_order	string	否	排序方向，可选 asc / desc，默认 desc
page	int	是	页码，从 1 开始
page_size	int	否	每页条数，默认 20，上限 100（超出范围或 ≤0 时取默认值）

响应示例

{
  "code": 200,
  "data": {
    "record": [
      {
        "id": "01965de1-1920-7fe4-aa38-2e6836c46f22",
        "file_path": "/data/report.csv",
        "file_name": "report.csv",
        "file_type": ".csv",
        "file_size": 10240,
        "created_at": "2026-05-09T08:00:00Z",
        "updated_at": "2026-05-09T08:00:00Z"
      },
      {
        "id": "01965de2-3a51-7b9c-bd12-4f7e9a0b1c2d",
        "file_path": "/data/notes.txt",
        "file_name": "notes.txt",
        "file_type": ".txt",
        "file_size": 512,
        "created_at": "2026-05-08T12:30:00Z",
        "updated_at": "2026-05-08T12:30:00Z"
      }
    ],
    "total": 2
  },
  "message": "",
  "trace_id": "abc123"
}

字段	类型	说明
record	array	当前页文件记录列表
total	number	满足条件的文件总数

record 字段结构：

字段	类型	说明
id	string	文件记录 ID
file_path	string	文件完整路径
file_name	string	文件名
file_type	string	文件扩展名（含 .，如 .csv）
file_size	number	文件大小（字节）
created_at	string	创建时间，RFC 3339 格式
updated_at	string	更新时间，RFC 3339 格式

TIP

此接口基于文件元数据记录查询，返回结构（record / total）与列出目录等基于对象存储实时扫描的接口不同，字段也不同。适用于需要对文件做分页、排序、按类型筛选的管理类场景。