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

上传本地文件并创建导入任务。非结构化文件写入数据卷；CSV、XLS 和 XLSX 的数据行写入目标表。

POST https://api.moi.matrixorigin.cn/v5/connectors/upload

调用前准备¶

准备有目标工作区访问权限的个人访问令牌、目标工作区 ID和目标数据卷或数据表。

非结构化文件一次最多 20 个、每个最大 200 MiB；结构化文件一次只能上传 1 个、每个最大 200 MiB，且仅支持 CSV、XLS 和 XLSX。

请求体¶

将 $AI_STUDIO_API_KEY、$WORKSPACE_ID 和示例中的资源 ID 替换为实际值。表单中的 JSON 值以字符串提交。

输入示例

上传非结构化文件到数据卷

curl -X POST "https://api.moi.matrixorigin.cn/v5/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"}'

上传结构化文件到已有数据表

此场景先上传文件取得临时文件 ID，再将该 ID 填入 table_config.conn_file_ids。不传 file 或 VolumeID。

curl -X POST "https://api.moi.matrixorigin.cn/v5/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
      }
    ]
  }'

参数说明

上传非结构化文件到数据卷

参数	类型	是否必填	说明
`file`	file（文件数组）	是	本地文件；可重复传递。
`VolumeID`	string	是	目标数据卷 ID。
`meta`	string	否	来源文件名和路径组成的 JSON 字符串。
`meta.filename`	string	否	与对应 `file` 部件一致的文件名。
`meta.path`	string	否	文件的来源相对路径。
`path_regex`	string	否	筛选 `meta.path` 的正则表达式。
`unzip_keep_structure`	string	否	是否在解压时保留目录结构。
`dedup`	string	否	重复文件处理设置的 JSON 字符串。
`dedup.by`	array of string	否	重复文件判断字段。
`dedup.strategy`	string	否	重复文件处理策略。

上传结构化文件到已有数据表

参数	类型	是否必填	说明
`meta`	string	是	结构化文件名和路径组成的 JSON 字符串。
`meta.filename`	string	否	结构化文件名。
`meta.path`	string	否	结构化文件的来源相对路径。
`table_config`	string	是	目标表和列映射组成的 JSON 字符串。
`table_config.new_table`	boolean	是	`false` 表示使用已有表。设为 `true` 时使用 `database_id` 和 `create_table` 建新表；XLS 或 XLSX 多工作表改用 `multi_sheet` 和 `tables`，不要与单表字段同级混用。
`table_config.table_id`	integer	是	已有目标表 ID。
`table_config.conn_file_ids`	array of string	是	上传接口返回的临时文件 ID。
`table_config.isColumnName`	boolean	是	是否将指定行作为列名。
`table_config.columnNameRow`	integer	是	列名所在行，从 1 开始。
`table_config.rowStart`	integer	是	数据开始行，从 1 开始。
`table_config.csv`	object	否	CSV 解析设置。
`table_config.csv.separator`	string	否	CSV 列分隔符。
`table_config.existed_table`	array of object	是	文件列到目标列的映射。
`table_config.existed_table.tableColumn`	string	否	目标表列名。
`table_config.existed_table.column`	string	否	文件中的列名。
`table_config.existed_table.col_num_in_file`	integer	否	文件中的列序号。

成功响应¶

请求已受理不表示导入已完成。

响应示例

{
  "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`	array of string	本次成功处理的文件 ID；结构化临时文件流程中可能为空。
`data.success`	boolean	请求是否创建成功。
`data.message`	string	处理结果说明。
`data.results`	array of object	按文件返回的结果。
`data.results.success`	boolean	该文件是否成功处理。
`data.results.message`	string	该文件的处理结果说明。

错误响应¶

响应示例

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

字段说明

字段	类型	说明
`code`	string	错误代码。
`msg`	string	可读错误信息。
`data`	null	错误响应中为 `null`。

后续操作¶

使用 data.task_id 查看导入任务详情确认目标、状态和处理统计。

最后更新于 2026 年 9 月 28 日