创建任务

通过连接器创建非结构化或结构化文件导入任务。成功响应只返回任务 ID；后续通过查询详情、文件和运行记录确认实际处理结果。

本接口只适用于连接器来源。本地文件上传使用 multipart 请求，参见本地上传并创建导入任务；数据库中的结构化数据使用 config_type: 3，参见创建数据库结构化载入任务。

POST https://moi.matrixorigin.cn/newmoi/task

调用前准备

创建前，先确认导入目标：

• 导入非结构化文件时，准备可写的数据卷、连接器 ID，以及待处理文件或目录的 URI。

• 导入结构化文件时，当前创建页面只可从连接器中选择 CSV、XLS 或 XLSX。准备连接器 ID、文件 URI、目标表；也可以在指定数据库中创建目标表。

• 连接器必须具备“导入”用途，且调用者应具有连接器和目标资源的访问权限。

下方示例使用：

• $AI_STUDIO_API_KEY：实际个人访问令牌，通过 X-API-Key Header 传递。

• $WORKSPACE_ID：要创建任务的工作区 ID，通过 X-Workspace-ID Header 传递。

请求体

字段	类型	是否必填	说明
source_connector_id	string 或 integer	是	来源连接器 ID。
name	string	是	任务名称。
config_type	integer	是	文件导入固定为 1。
source_config	object	是	文件来源和处理设置，必须包含 common_file_task_config。
volume_id	string	条件必填	非结构化文件导入时填写目标数据卷 ID。该请求没有目标目录字段，文件写入所选数据卷；结构化文件写入数据表时留空字符串。

source_config.common_file_task_config 的字段如下。

字段	类型	是否必填	说明
uris	string（字符串数组）	是	待导入的连接器文件或目录 URI。周期导入只能指定目录。
load_mode_config	object	是	导入周期设置。一次性任务填写 {"load_interval_type":4}。
load_mode_config.load_interval_type	integer	是	1 表示每天、2 表示按小时、3 表示按分钟、4 表示一次性。按天、小时或分钟时同时填写 interval。
load_mode_config.interval	integer	条件必填	周期导入的间隔：分钟和小时模式填写间隔值；每天模式填写执行小时（0 至 23）。
file_filter_config	object	否	文件筛选条件。
file_filter_config.filename_globs	string（字符串数组）	否	文件名 glob 筛选条件。
file_filter_config.min_file_size	integer	否	文件大小下限，单位为字节。
file_filter_config.max_file_size	integer	否	文件大小上限，单位为字节。
file_filter_config.min_create_time	integer	否	文件创建时间下限。
file_filter_config.max_create_time	integer	否	文件创建时间上限。
file_filter_config.file_types	integer（整数数组）	否	允许处理的文件类型代码。
file_filter_config.path_regex	string	否	来源路径正则表达式。
unzip_keep_structure	boolean	否	解压时是否保留目录结构。创建页当前以扁平化方式处理压缩包。
dedup	object	否	写入数据卷时的重复文件处理策略。
dedup.by	string（字符串数组）	否	判断重复的依据：name、md5 或两者。
dedup.strategy	string	否	重复时的策略：skip 或 overwrite。
table_config	object	条件必填	结构化文件导入目标表的设置；非结构化文件导入不填写。
multi_table_config	object	否	多工作表结构化文件的表配置；包含 multi_sheet:true 和 tables，其中每一项均为一个 table_config 对象。
csv	object	否	文件级 CSV 解析设置，字段与 table_config.csv 相同。
table_config.sheet_name	string	否	XLS 或 XLSX 的工作表名称。
table_config.new_table	boolean	是（结构化）	是否创建目标表。
table_config.table_id	integer	条件必填	写入已有表时的目标表 ID。
table_config.database_id	integer	条件必填	新建表时的目标数据库 ID。
table_config.conn_file_ids	string（字符串数组）	否	已上传临时文件的 ID。连接器来源通常使用 uris；本地结构化文件流程使用此字段。
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.csv.delimiter	string	否	CSV 字符串定界符。
table_config.csv.isEscape	boolean	否	是否启用转义处理。
table_config.conflict	integer	否	导入冲突处理代码。
table_config.existed_table	object（对象数组）	条件必填	写入已有表时的列映射。每项包含 tableColumn（目标列）、column（文件列）和 col_num_in_file（文件列序号）。
table_config.existed_table_opts.method	string	否	已有表的初始写入方式。
table_config.existed_table_opts.table_name	string	否	已有表名称。
table_config.create_table	object	条件必填	新建表定义；包含 name、description 和 tableColumn。
table_config.create_table.tableColumn	object（对象数组）	条件必填	新建表列定义；每项包含 column、dataType、precision、isKey、defaultValue、description 和 col_num_in_file。

请求示例

连接器文件导入到数据卷

下面的请求从连接器中的目录读取文件，并写入 <VOLUME_ID> 指定的数据卷。path_regex 用于匹配连接器来源路径，不控制数据卷内的目标目录；任务创建成功只代表任务已受理。

curl -X POST "https://moi.matrixorigin.cn/newmoi/task" \
  -H "X-API-Key: $AI_STUDIO_API_KEY" \
  -H "X-Workspace-ID: $WORKSPACE_ID" \
  -H 'Content-Type: application/json' \
  -d '{
    "source_connector_id":"<CONNECTOR_ID>",
    "name":"<TASK_NAME>",
    "config_type":1,
    "volume_id":"<VOLUME_ID>",
    "source_config":{
      "common_file_task_config":{
        "uris":["<CONNECTOR_DIRECTORY_URI>"],
        "load_mode_config":{"load_interval_type":4},
        "file_filter_config":{"path_regex":".*\\.(pdf|docx)$"},
        "unzip_keep_structure":false,
        "dedup":{"by":["name","md5"],"strategy":"skip"}
      }
    }
  }'

连接器 CSV 导入到已有数据表

下面的请求从连接器读取 CSV，并将数据写入 <TARGET_TABLE_ID> 指定的已有表。结构化文件导入的目标是数据表，因此 volume_id 为空字符串，也不提供目标目录字段。

curl -X POST "https://moi.matrixorigin.cn/newmoi/task" \
  -H "X-API-Key: $AI_STUDIO_API_KEY" \
  -H "X-Workspace-ID: $WORKSPACE_ID" \
  -H 'Content-Type: application/json' \
  -d '{
    "source_connector_id":"<CONNECTOR_ID>",
    "name":"<TASK_NAME>",
    "config_type":1,
    "volume_id":"",
    "source_config":{
      "common_file_task_config":{
        "uris":["<CONNECTOR_FILE_URI>"],
        "load_mode_config":{"load_interval_type":4},
        "table_config":{
          "new_table":false,
          "table_id":<TARGET_TABLE_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"}
        }
      }
    }
  }'

创建目标表时，将 new_table 设为 true，使用 database_id 指定目标数据库，并填写 create_table。创建出的表不会随着任务删除而自动回滚。

成功响应

当响应中的 code 为 OK 时，导入任务已受理，不表示数据已导入完成。

{
  "code": "OK",
  "msg": "OK",
  "data": {
    "task_id": "task_01"
  }
}

响应字段如下。

字段	类型	说明
code	string	成功时为 OK。
msg	string	成功时为 OK。
data.task_id	string	新建导入任务 ID，用于后续查询详情、文件和运行记录。

错误响应

{
  "code": "ErrParamInvalid",
  "msg": "source_config is required",
  "data": null
}

常见 HTTP 错误

HTTP 状态码	错误代码	常见原因	建议操作
403	ErrForbidden	调用者没有创建任务或访问依赖对象的权限。	检查工作区、连接器和目标资源授权。
409	IAM_ERROR_CODE_IDEMPOTENCY_CONFLICT	同一 IAM 生命周期请求发生冲突。	使用新的请求关联 ID 后重试。
503	ErrCoreAuthorizeUnavailable	服务暂时无法完成授权检查。	稍后重试。
200	ErrParamInvalid	缺少导入设置，或请求 JSON 无效。	根据错误响应提示修正请求字段后重试。
200	ErrServer	服务未能创建任务。	同时检查 HTTP 状态和 code。

后续操作

记录 data.task_id。创建成功只表示任务已受理，不表示数据已导入完成。用该 ID 查询任务详情跟踪进度与文件统计；出现失败时再查询任务文件或查询运行记录。

最后更新于 2026 年 8 月 22 日