查询文件列表

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

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。

请求示例

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。

{
  "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	是否仍有下一页。

错误响应

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

常见 HTTP 错误

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

后续操作

保存目标文件的 uri 与连接器 ID。需要确认文件内容时，使用这两个值预览文件。

最后更新于 2026 年 8 月 22 日