本地上传并创建导入任务¶

上传本地文件并创建导入任务。该接口使用 multipart/form-data；与连接器来源的 JSON 创建接口不同。成功响应返回任务 ID，但不表示所有文件已经写入目标位置或全部完成解析。

POST https://moi.matrixorigin.cn/newmoi/connectors/upload

调用前准备¶

先选择数据形态和目标：

非结构化文件写入数据卷。准备可写数据卷 ID，并通过 VolumeID 指定它。
结构化文件写入数据表。当前创建页面只可选择 CSV、XLS 或 XLSX。先通过上传文件取得 conn_file_id，再通过 table_config 指定已有目标表或新建目标表。结构化文件的数据行写入表，不写入 VolumeID 指定的数据卷。

当前创建页面的本地文件选择限制如下：

非结构化文件：一次最多选择 20 个文件，单个文件最大 200 MiB。可以选择文件或文件夹；选择文件夹时，文件夹中的每个文件均计入数量。
结构化文件：一次只能选择 1 个文件，单个文件最大 200 MiB；当前只允许 CSV、XLS 或 XLSX。

下方示例使用：

$AI_STUDIO_API_KEY：实际个人访问令牌，通过 X-API-Key Header 传递。
$WORKSPACE_ID：要创建任务的工作区 ID，通过 X-Workspace-ID Header 传递。

表单字段¶

本文中，类型后的 [] 表示数组，例如 file[] 表示文件数组。

字段	类型	是否必填	说明
`file`	file[]	条件必填	非结构化本地导入时上传一个或多个文件。每个文件使用同名字段 `file` 传递。结构化文件流程已先上传为临时文件时，不重复传该字段。
`meta`	JSON array	是	与上传文件顺序对应的来源信息。每项包含 `filename` 和 `path`；`path` 用于记录和匹配来源路径，不是目标数据卷目录。
`VolumeID`	string	条件必填	非结构化导入的目标数据卷 ID。请求没有目标目录字段，文件写入该数据卷；结构化文件导入不填写。
`file_types`	JSON integer array	否	允许处理的文件类型代码。代码与查询文件列表中的 `type` 相同。包含 `0`（其他）时不按文件类型筛选。
`path_regex`	string	否	仅处理 `meta.path` 匹配该正则表达式的文件。
`unzip_keep_structure`	boolean string	否	解压时是否保留目录结构，例如 `false`。当前创建页以扁平化方式处理压缩包。
`dedup`	JSON object	否	重复文件处理设置。对象包含 `by`（`name`、`md5` 或两者）和 `strategy`（`skip` 或 `overwrite`）。
`table_config`	JSON object	条件必填	结构化文件导入的目标表设置。可包含 `sheet_name`、`new_table`、`table_id`、`database_id`、`conn_file_ids`、`isColumnName`、`columnNameRow`、`rowStart`、`csv`、`conflict`、`existed_table`、`create_table` 和 `existed_table_opts`。已有表时填写 `new_table:false`、`table_id`、表头/起始行和 `existed_table` 列映射；新建表时填写 `new_table:true`、`database_id` 和 `create_table`。支持多工作表时使用 `multi_sheet:true` 和 `tables`。各字段含义见创建连接器文件导入任务。

请求示例¶

非结构化文件导入到数据卷¶

下例将本地文件上传到 <VOLUME_ID> 数据卷。路径正则作用于 meta.path，因此可以用它排除不需要的文件；它不控制数据卷内的目标目录。

curl -X POST "https://moi.matrixorigin.cn/newmoi/connectors/upload" \
  -H "X-API-Key: $AI_STUDIO_API_KEY" \
  -H "X-Workspace-ID: $WORKSPACE_ID" \
  -F 'file=@./manuals/product.pdf' \
  -F 'file=@./manuals/guide.docx' \
  -F 'VolumeID=<VOLUME_ID>' \
  -F 'meta=[{"filename":"product.pdf","path":"manuals/product.pdf"},{"filename":"guide.docx","path":"manuals/guide.docx"}]' \
  -F 'path_regex=^manuals/.*' \
  -F 'unzip_keep_structure=false' \
  -F 'dedup={"by":["name","md5"],"strategy":"skip"}'

本地 CSV 导入到已有数据表¶

先上传文件取得 <CONN_FILE_ID>，再提交表配置。示例将第 1 行作为表头，从第 2 行开始读取数据，并把文件列映射到已有目标表。

curl -X POST "https://moi.matrixorigin.cn/newmoi/connectors/upload" \
  -H "X-API-Key: $AI_STUDIO_API_KEY" \
  -H "X-Workspace-ID: $WORKSPACE_ID" \
  -F 'meta=[{"filename":"orders.csv","path":"orders.csv"}]' \
  -F 'table_config={"new_table":false,"table_id":<TARGET_TABLE_ID>,"conn_file_ids":["<CONN_FILE_ID>"],"isColumnName":true,"columnNameRow":1,"rowStart":2,"csv":{"separator":","},"existed_table":[{"tableColumn":"<TARGET_COLUMN>","column":"<FILE_COLUMN>","col_num_in_file":1}],"existed_table_opts":{"method":"append"}}'

成功响应¶

当响应中的 code 为 OK 时，任务已受理。

{
  "code": "OK",
  "msg": "OK",
  "data": {
    "task_id": "task_01",
    "file_ids": ["file_01"],
    "success": true,
    "message": "OK",
    "results": [
      {"success": true, "message": "OK"}
    ]
  }
}

响应字段如下。

字段	类型	说明
`code`	string	成功时为 `OK`。
`msg`	string	成功时为 `OK`。
`data.task_id`	string	创建的导入任务 ID。
`data.file_ids`	string（字符串数组）	本次新上传并成功处理的文件 ID；结构化临时文件流程中可能为空。
`data.success`	boolean	请求是否创建成功。
`data.message`	string	处理结果说明。
`data.results`	object（对象数组）	按文件返回的处理结果。每项包含 `success` 和 `message`。

错误响应¶

{
  "code": "ErrParamInvalid",
  "msg": "invalid upload parameters",
  "data": null
}

常见 HTTP 错误¶

HTTP 状态码	错误代码	常见原因	建议操作
`400`	`ErrParamInvalid`	multipart 表单无效，或 `VolumeID`、`table_config`、路径正则不符合要求。	检查字段名、JSON 字符串、目标资源 ID 和正则表达式。
`403`	`ErrForbidden`	调用者无权向目标数据卷或目标表写入数据。	检查工作区、数据卷和数据表授权。
`200`	`ErrServer`	服务未能创建或调度任务。	同时检查 HTTP 状态和 `code`，稍后重试或查询任务状态。

后续操作¶

记录 data.task_id。使用该 ID 查询任务详情确认目标、状态和处理统计；必要时再查询任务文件或查询运行记录。

最后更新于 2026 年 8 月 22 日