# 查询文件列表

列出一个连接器可访问的文件。先从响应中取得文件 `uri`，再预览该文件。

```text
GET https://moi.matrixorigin.cn/newmoi/connectors/files/list
```

## 调用前准备

准备有目标工作区访问权限的个人访问令牌、目标工作区 ID 和连接器 ID。只有支持文件列举的连接器可以调用此接口。

下方示例使用：

- `$AI_STUDIO_API_KEY`：实际个人访问令牌，通过 `X-API-Key` Header 传递。
- `$WORKSPACE_ID`：要查询的工作区 ID，通过 `X-Workspace-ID` Header 传递。
- `$CONNECTOR_ID`：要列举文件的连接器 ID，通过 `connector_id` 查询参数传递。

## 查询参数

| 参数 | 类型 | 是否必填 | 说明 |
| --- | --- | --- | --- |
| `connector_id` | string | 是 | 连接器 ID。 |
| `cursor` | string | 否 | 上一页返回的游标。 |
| `limit` | integer | 否 | 本页返回数量。默认值为 `20`。 |
| `dir` | string | 否 | 相对于连接器配置根目录的目录。 |
| `file_types` | integer（整数数组） | 否 | 仅筛选普通文件的文件类型代码。重复传递该参数，例如 `file_types=7&file_types=25`。目录始终返回，不受此参数筛选。 |

### 文件类型代码

`file_types` 和响应中的 `type` 使用下列代码：

| 代码 | 类型 | 代码 | 类型 |
| --- | --- | --- | --- |
| `0` | 未识别 | `1` | TXT |
| `2` | PDF | `3` | 通用图像 |
| `4` | PPT | `5` | Word |
| `6` | Markdown | `7` | CSV |
| `8` | Parquet | `9` | SQL |
| `10` | 目录 | `11` | DOCX |
| `12` | PPTX | `13` | WAV |
| `14` | MP3 | `15` | AAC |
| `16` | FLAC | `17` | MP4 |
| `18` | MOV | `19` | MKV |
| `20` | PNG | `21` | JPG |
| `22` | JPEG | `23` | BMP |
| `24` | XLS | `25` | XLSX |
| `27` | HTM | `28` | HTML |
| `29` | EML | `30` | MSG |
| `31` | P7S | `32` | DWG |
| `33` | DXF | `34` | FAS |
| `35` | DOC | `101` | ZIP |
| `102` | RAR | `103` | 7Z |
| `104` | TAR | `105` | TAR.GZ |
| `106` | TAR.BZ2 | `107` | GZ |
| `108` | BZ2 |  |  |

`limit` 是连接器读取一页时使用的数量。应用 `file_types` 筛选后，本页实际返回的普通文件数可能小于 `limit`。支持游标分页的连接器在 `has_more` 为 `true` 时返回下一页游标；不支持分页的连接器返回空游标和 `has_more=false`。

## 请求示例

```bash
curl "https://moi.matrixorigin.cn/newmoi/connectors/files/list?connector_id=$CONNECTOR_ID&limit=20" \
  -H "X-API-Key: $AI_STUDIO_API_KEY" \
  -H "X-Workspace-ID: $WORKSPACE_ID"
```

## 成功响应

成功时返回 `200`。

```json
{
  "code": "OK",
  "msg": "OK",
  "data": {
    "files": [
      {
        "uri": "/orders.csv",
        "filename": "orders.csv",
        "size": 1024,
        "type": 1,
        "path": "/",
        "create_time": 0,
        "update_time": 0
      }
    ],
    "cursor": "next_cursor",
    "has_more": true
  }
}
```

响应字段如下。

字段路径中的 `[]` 表示数组中的每一项。例如，`data.files[].uri` 表示 `data.files` 数组中每一项的 `uri` 字段。

| 字段 | 类型 | 说明 |
| --- | --- | --- |
| `code` | string | 成功时为 `OK`。 |
| `msg` | string | 成功时为 `OK`。 |
| `data.files` | object（对象数组） | 当前页文件；没有文件时可能省略或为空数组。 |
| `data.files[].uri` | string | 文件 URI，可用于后续预览。 |
| `data.files[].filename` | string | 文件名。 |
| `data.files[].size` | integer | 文件大小，单位为字节。 |
| `data.files[].type` | integer | 文件类型代码。 |
| `data.files[].path` | string | 连接器内的文件路径。 |
| `data.files[].create_time` | integer | 文件创建时间的 Unix 时间戳。当前文件列表实现返回 `0`。 |
| `data.files[].update_time` | integer | 文件更新时间的 Unix 时间戳。当前文件列表实现返回 `0`。 |
| `data.cursor` | string | 下一页游标。仅在 `data.has_more` 为 `true` 时用于下一次请求。 |
| `data.has_more` | boolean | 是否仍有下一页。 |

## 错误响应

```json
{
  "code": "ErrServer",
  "msg": "server error",
  "data": null
}
```

### 常见 HTTP 错误

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

* - HTTP 状态码
  - 错误代码
  - 常见原因
  - 建议操作
* - `400`
  - `—`
  - 查询参数格式无效。响应使用 `error` 字段，不使用标准 `code` 字段。
  - 修正 `connector_id`、游标或 `limit` 后重试。
* - `500`
  - `ErrServer`
  - 连接器不存在、不可访问、不支持列举文件，或服务未能读取文件列表。
  - 检查连接器 ID 和访问权限；确认该连接器支持文件列举后重试。
```

## 后续操作

保存目标文件的 `uri` 与连接器 ID。需要确认文件内容时，使用这两个值[预览文件](preview-file.md)。