# 创建任务

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

本接口只适用于**连接器来源**。本地文件上传使用 multipart 请求，参见[本地上传并创建导入任务](create-local-import-task.md)；数据库中的结构化数据使用 `config_type: 3`，参见[创建数据库结构化载入任务](create-structured-load-task.md)。

```text
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` 用于匹配连接器来源路径，不控制数据卷内的目标目录；任务创建成功只代表任务已受理。

```bash
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` 为空字符串，也不提供目标目录字段。

```bash
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` 时，导入任务已受理，不表示数据已导入完成。

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

响应字段如下。

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

## 错误响应

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

### 常见 HTTP 错误

```{list-table}
:header-rows: 1
:widths: 12 25 30 33

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

## 后续操作

记录 `data.task_id`。创建成功只表示任务已受理，不表示数据已导入完成。用该 ID [查询任务详情](get-import-task.md)跟踪进度与文件统计；出现失败时再[查询任务文件](list-import-task-files.md)或[查询运行记录](list-import-task-runs.md)。