# 查询文件列表

按卷筛选并分页查询文件。请求必须包含且只能包含一个 `volume_id` 筛选条件。

```text
POST https://moi.matrixorigin.cn/newmoi/catalog/file/list
```

## 调用前准备

先[查询数据库中的对象](list-database-objects.md)取得目标卷 ID。准备有目标工作区访问权限的个人访问令牌、目标工作区 ID 和卷 ID。

下方示例使用：

- `$AI_STUDIO_API_KEY`：实际个人访问令牌，通过 `X-API-Key` Header 传递。
- `$WORKSPACE_ID`：目标工作区 ID，通过 `X-Workspace-ID` Header 传递。
- `$VOLUME_ID`：要列出文件的卷 ID，通过 `filters` 中的 `volume_id` 传递。

调用者需要目标根卷的读取权限。

## 请求体

本文中，类型后的 `[]` 表示数组，例如 `string[]` 是字符串数组；字段路径中的 `[]` 表示数组中的每一项，例如 `filters[].name` 表示 `filters` 数组中每一项的 `name` 字段。

| 参数 | 类型 | 是否必填 | 说明 |
| --- | --- | --- | --- |
| `filters` | array | 是 | 筛选条件数组，必须包含一个 `name` 为 `volume_id` 的条件。 |
| `filters[].name` | string | 是 | 筛选字段名。`volume_id` 必须出现一次。 |
| `filters[].values` | array[string] | 是 | 筛选值。`volume_id` 必须为单个正整数值。 |
| `filters[].fuzzy` | boolean | 否 | `name` 为 `file_name` 时，是否使用模糊匹配。 |
| `page` | integer | 否 | 页码。 |
| `page_size` | integer | 否 | 每页条数。 |
| `order` | string | 否 | 排序方向：`asc` 或 `desc`。 |
| `order_by` | string | 否 | 排序字段。 |

## 请求示例

```bash
curl -X POST "https://moi.matrixorigin.cn/newmoi/catalog/file/list" \
  -H "X-API-Key: $AI_STUDIO_API_KEY" \
  -H "X-Workspace-ID: $WORKSPACE_ID" \
  -H 'Content-Type: application/json' \
  -d '{
    "filters": [
      {
        "name": "volume_id",
        "values": ["'"$VOLUME_ID"'"]
      }
    ],
    "page": 1,
    "page_size": 20
  }'
```

## 成功响应

成功时返回 `200` 和文件列表。调用者需要目标根卷的读取权限。

```json
{
  "code": "OK",
  "msg": "OK",
  "data": {
    "total": 1,
    "list": [
      {
        "id": "file-123",
        "name": "orders.csv",
        "file_type": "file",
        "file_ext": "csv",
        "size": 2048,
        "parent_id": "",
        "volume_id": "789",
        "volume_name": "sales_files",
        "created_at": "2026-01-01T00:00:00Z"
      }
    ]
  }
}
```

响应字段如下。

| 字段 | 类型 | 说明 |
| --- | --- | --- |
| `code` | string | 成功时为 `OK`。 |
| `msg` | string | 成功时为 `OK`。 |
| `data.total` | integer | 匹配筛选条件的条目总数。 |
| `data.list` | array | 文件和文件夹条目列表。 |
| `data.list[].id` | string | 条目 ID。 |
| `data.list[].name` | string | 条目名称。 |
| `data.list[].file_type` | string | 条目类型：`file` 或 `folder`。 |
| `data.list[].workflow_role` | string | 工作流产物角色；工作流输出为 `output`，其他条目为空字符串。 |
| `data.list[].file_ext` | string | 文件扩展名。 |
| `data.list[].origin_file_name` | string | 原始文件名；适用时返回。 |
| `data.list[].origin_file_ext` | string | 原始文件扩展名；适用时返回。 |
| `data.list[].size` | integer | 文件大小，单位为字节。 |
| `data.list[].parent_id` | string | 父级 ID。 |
| `data.list[].volume_id` | string | 所属卷 ID。 |
| `data.list[].volume_name` | string | 所属卷名称。 |
| `data.list[].volume_reserved` | boolean | 所属卷是否为保留卷。 |
| `data.list[].created_at` | string | 创建时间，采用 RFC 3339 格式。 |
| `data.list[].created_by` | string | 创建者标识。 |
| `data.list[].ref_file_id` | string | 关联的源文件 ID；适用时返回。 |
| `data.list[].parsed_file_id` | string | 可下载解析产物的文件 ID；适用时返回。 |
| `data.list[].ref_workflow_id` | string | 关联工作流 ID；适用时返回。 |

## 错误响应

```json
{
  "code": "ErrParamInvalid",
  "msg": "必须提供唯一的 volume_id 筛选条件",
  "data": null
}
```

### 常见 HTTP 错误

```{list-table}
:header-rows: 1
:widths: 12 22 32 34

* - HTTP 状态码
  - 错误代码
  - 常见原因
  - 建议操作
* - `400`
  - `ErrParamInvalid`
  - 未传入唯一的正整数 `volume_id` 筛选条件。
  - 在 `filters` 中仅保留一个 `volume_id`。
* - `403`
  - `ErrForbidden`
  - 当前身份没有目标根卷读取权限。
  - 检查工作区和卷授权。
* - `404`
  - `ErrNotFound`
  - 目标卷不存在。
  - 检查 `volume_id`。
* - `500`
  - `ErrServer`
  - 服务无法读取文件列表。
  - 记录请求时间和错误信息后重试；持续失败时联系支持人员。
```

## 后续操作

使用 `data.list[].id` [查询文件详情](get-file.md)。