创建连接器文件导入任务¶

从连接器中选择已有文件或目录并创建导入任务。非结构化文件写入数据卷；CSV、XLS 和 XLSX 的数据行写入目标表。

POST https://api.moi.matrixorigin.cn/v5/task

调用前准备¶

准备有目标工作区访问权限的个人访问令牌、目标工作区 ID、具有导入用途的连接器、连接器文件 URI，以及目标数据卷或数据表。

要上传本地文件，请使用本地上传并创建导入任务。要从数据库对象读取数据，请使用创建数据库结构化导入任务。

请求体¶

将 $AI_STUDIO_API_KEY、$WORKSPACE_ID 和示例中的连接器、目标资源及字段值替换为实际值。

输入示例

导入文件到数据卷

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

导入 CSV 到已有数据表

结构化文件写入数据表。

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

参数说明

导入文件到数据卷

参数	类型	是否必填	说明
`source_connector_id`	string 或 integer	是	来源连接器 ID。
`name`	string	是	任务名称。
`config_type`	integer	是	文件导入固定为 `1`。
`source_config`	object	是	文件来源和处理设置。
`source_config.common_file_task_config.uris`	array of string	是	连接器中的文件或目录 URI。
`source_config.common_file_task_config.load_mode_config.load_interval_type`	integer	是	执行频率；`4` 表示一次性。
`source_config.common_file_task_config.file_filter_config.path_regex`	string	否	来源路径筛选正则表达式。
`source_config.common_file_task_config.unzip_keep_structure`	boolean	否	解压时是否保留目录结构。
`source_config.common_file_task_config.dedup.by`	array of string	否	重复文件判断字段。
`source_config.common_file_task_config.dedup.strategy`	string	否	重复文件处理策略。
`volume_id`	string	是	目标数据卷 ID。

导入 CSV 到已有数据表

参数	类型	是否必填	说明
`source_connector_id`	string 或 integer	是	来源连接器 ID。
`name`	string	是	任务名称。
`config_type`	integer	是	文件导入固定为 `1`。
`source_config`	object	是	文件来源和目标表设置。
`source_config.common_file_task_config.uris`	array of string	是	连接器中的 CSV 文件 URI。
`source_config.common_file_task_config.load_mode_config.load_interval_type`	integer	是	执行频率；`4` 表示一次性。
`source_config.common_file_task_config.table_config.new_table`	boolean	是	`false` 表示使用已有表。新建单表时改为 `true`；XLS 或 XLSX 多工作表改用 `multi_table_config.tables`，不要与单表配置混用。
`source_config.common_file_task_config.table_config.table_id`	integer	是	已有目标表 ID。
`source_config.common_file_task_config.table_config.isColumnName`	boolean	是	是否将指定行作为列名。
`source_config.common_file_task_config.table_config.columnNameRow`	integer	是	列名所在行，从 1 开始。
`source_config.common_file_task_config.table_config.rowStart`	integer	是	数据开始行，从 1 开始。
`source_config.common_file_task_config.table_config.csv.separator`	string	否	CSV 列分隔符。
`source_config.common_file_task_config.table_config.existed_table`	array of object	是	文件列到目标列的映射。
`source_config.common_file_task_config.table_config.existed_table.tableColumn`	string	否	目标表列名。
`source_config.common_file_task_config.table_config.existed_table.column`	string	否	文件中的列名。
`source_config.common_file_task_config.table_config.existed_table.col_num_in_file`	integer	否	文件中的列序号。
`volume_id`	string	是	结构化文件导入传入空字符串。

成功响应¶

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

响应示例

{
  "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
}

字段说明

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

后续操作¶

使用返回的 data.task_id 查看导入任务详情、查看导入任务文件列表和查看导入任务运行记录列表。

最后更新于 2026 年 9 月 11 日