# 查询可导出文件

列出一个卷中可用于创建导出任务的已处理文件。

```text
POST https://moi.matrixorigin.cn/newmoi/export/volumes/$VOLUME_ID/files
```

## 调用前准备

先确认目标卷中已有可导出的处理结果。准备有目标工作区访问权限的个人访问令牌、目标工作区 ID 和卷 ID。

下方示例使用：

- `$AI_STUDIO_API_KEY`：实际个人访问令牌，通过 `X-API-Key` Header 传递。
- `$WORKSPACE_ID`：目标工作区 ID，通过 `X-Workspace-ID` Header 传递。
- `$VOLUME_ID`：要查询的卷 ID，填写请求地址中的卷 ID 位置。

该接口只返回具有向量化处理结果的卷中文件。当前创建页面的 MatrixOne 文件树还可以显示已解析的处理结果；需要按页面选择文件时，请以页面文件树为准。

## 路径参数

| 参数 | 类型 | 是否必填 | 说明 |
| --- | --- | --- | --- |
| `volume_id` | string | 是 | 要查询的卷 ID。 |

## 请求体

| 字段 | 类型 | 是否必填 | 说明 |
| --- | --- | --- | --- |
| `filters.types` | integer（整数数组） | 否 | 按文件类型筛选。 |
| `filters.exclude_status` | integer（整数数组） | 否 | 排除的处理状态。 |
| `sorter.sort_by` | string | 否 | 传入非空值时按文件创建时间排序。 |
| `sorter.is_desc` | boolean | 否 | `true` 为创建时间降序；不传或 `false` 为升序。 |
| `offset` | integer | 否 | 分页偏移量。 |
| `limit` | integer | 否 | 本页返回条数；不传时为 `30`。 |

## 请求示例

```bash
curl -X POST "https://moi.matrixorigin.cn/newmoi/export/volumes/$VOLUME_ID/files" \
  -H "X-API-Key: $AI_STUDIO_API_KEY" \
  -H "X-Workspace-ID: $WORKSPACE_ID" \
  -H 'Content-Type: application/json' \
  -d '{
  }'
```

## 成功响应

本文中，字段路径中的 `[]` 表示数组中的每一项。例如，`data.items[].id` 表示 `data.items` 数组中每一项的 `id` 字段。

成功时返回 `200`。`data.items` 是可导出的已处理文件；使用 `id` 作为创建导出任务时 `files[].file_id` 的值。

```json
{
  "code": "OK",
  "msg": "OK",
  "data": {
    "total": 1,
    "items": [{
      "id": "file-001",
      "file_name": "summary.csv",
      "file_status": 2,
      "file_type": 1
    }]
  }
}
```

响应字段如下。

| 字段 | 类型 | 说明 |
| --- | --- | --- |
| `code` | string | 成功时为 `OK`。 |
| `msg` | string | 成功时为 `OK`。 |
| `data.total` | integer | 符合当前筛选条件的文件总数。 |
| `data.items` | object（对象数组） | 可导出文件列表。 |
| `data.items[].id` | string | 文件 ID。 |
| `data.items[].file_name` | string | 文件名称。 |
| `data.items[].file_status` | integer | 文件当前处理状态。 |
| `data.items[].file_type` | integer | 文件类型标识。 |

## 错误响应

```json
{
  "code": "ErrServer",
  "msg": "服务器内部错误",
  "data": null
}
```

### 常见 HTTP 错误

```{list-table}
:header-rows: 1
:widths: 12 24 36 28

* - HTTP 状态码
  - 错误代码
  - 常见原因
  - 建议操作
* - `400`
  - —
  - `volume_id` 无效或请求体无法解析；该兼容路径返回 `error` 字段。
  - 使用正整数卷 ID，并检查筛选和排序字段类型。
* - `200`
  - `ErrServer`
  - 卷不存在，或依赖的处理、文件列表服务不可用。
  - 核对卷和依赖服务后重试；没有匹配文件时成功响应返回空列表。
* - `403`
  - `ErrForbidden`
  - 当前身份没有读取该卷的权限。
  - 请求授予卷读取权限。
* - `503`
  - `ErrCoreAuthorizeUnavailable`
  - 授权服务暂时不可用。
  - 稍后重试。
```

## 后续操作

选定可导出文件后，前往[创建任务](create-export-task.md)提交导出。