# 创建任务 创建导出任务，将选定文件或处理结果写入对象存储或 MatrixOne。成功响应表示任务已受理；使用返回的任务 ID 查询各文件的实际处理情况。 ```text POST https://moi.matrixorigin.cn/newmoi/export/task/create ``` ## 调用前准备 先[查询可导出文件](list-exportable-files.md)或在创建页面选择文件，并确认目标连接器可用。准备有目标工作区访问权限的个人访问令牌、目标工作区 ID、目标连接器信息和待导出的文件信息。 下方示例使用： - `$AI_STUDIO_API_KEY`：实际个人访问令牌，通过 `X-API-Key` Header 传递。 - `$WORKSPACE_ID`：目标工作区 ID，通过 `X-Workspace-ID` Header 传递。 - `$CONNECTOR_ID`：目标连接器 ID，填写请求体的 `connector_id` 字段。 页面会将目标连接器、`type` 和 `config` 自动配对。直接调用 API 时也应保持三者属于同一目标类型，否则任务可能无法正确执行。`files` 至少包含一个文件；每个文件都需要提供文件 ID 和完整路径。 ## 请求体 本文中，字段路径中的 `[]` 表示数组中的每一项。例如，`files[].file_id` 表示 `files` 数组中每一项的 `file_id` 字段。 | 字段 | 类型 | 是否必填 | 说明 | | --- | --- | --- | --- | | `task_name` | string | 是 | 导出任务名称。 | | `creator` | string | 是 | 创建者标识。 | | `connector_id` | string | 是 | 目标连接器 ID。 | | `connector_name` | string | 是 | 目标连接器名称。 | | `type` | integer | 是 | 导出目标类别：`3` 为 MatrixOne，`4` 为 OSS，`5` 为标准 S3。页面会根据所选连接器生成该值。 | | `config` | object | 是 | 目标配置，不能为 `null`。仅填写与 `type` 对应的配置对象。 | | `files` | object（对象数组） | 是 | 要导出的文件列表。 | | `files[].file_id` | string | 是 | 源文件 ID。 | | `files[].full_path` | string（字符串数组） | 是 | 源文件完整路径。 | | `files[].ref_file_id` | string | 否 | 原始文件对应的引用文件 ID。导出向量化处理结果时可用于关联原始文件。 | | `files[].parsed_file_id` | string | 否 | 已解析产物文件 ID。导出已解析或已向量化的处理结果时填写。 | | `files[].is_raw` | boolean | 否 | `true` 表示导出原始文件；`false` 表示导出处理结果。当前创建页面会明确传递该字段。 | ### 按目标填写 `config` 对象存储和 MatrixOne 使用不同的配置对象；一次请求只填写与 `type` 对应的一个对象。表中的“条件必填”表示选择对应导出目标时必须提供；子字段是当前创建页面完成该目标配置时需要填写的内容。 | 字段 | 类型 | 是否必填 | 说明 | | --- | --- | --- | --- | | `config.s3_config` | object | 条件必填 | OSS 或标准 S3 的目标配置。 | | `config.s3_config.path` | string | 条件必填 | 目标存储桶内的导出路径。当前创建页面要求以 `/` 结尾。 | | `config.s3_config.need_compress` | boolean | 条件必填 | 是否将本次文件打包压缩后导出。 | | `config.s3_config.compress_method` | string | 条件必填 | 当前创建页面使用 `gzip` 或 `no`；选择 `gzip` 时设置为 `gzip`。 | | `config.mo_config` | object | 条件必填 | MatrixOne 的目标表配置。 | | `config.mo_config.database_name` | string | 条件必填 | 目标数据库名称。 | | `config.mo_config.table_name` | string | 条件必填 | 目标表名称；新建表时为新表名称。 | | `config.mo_config.new_table` | boolean | 条件必填 | 是否新建目标表。 | | `config.mo_config.duplicated_strategy` | integer | 条件必填 | 重复数据处理方式：`1` 覆盖、`2` 跳过、`3` 保留。当前页面新建表时使用 `3`。 | | `config.mo_config.column` | object | 条件必填 | 导出列和列映射配置。 | | `config.mo_config.column.export_column` | object（对象数组） | 条件必填 | 要写入的列映射。每项包含 `source_column` 和 `mapping_column`。 | | `config.mo_config.column.export_column[].source_column` | string | 条件必填 | 处理结果中的源列名。 | | `config.mo_config.column.export_column[].mapping_column` | string | 条件必填 | 目标表中的列名。 | | `config.mo_config.column.combine_column` | string（字符串数组） | 条件必填 | 要合并处理的源列名；不合并时传空数组。 | ## 请求示例 ### 导出处理结果到 MatrixOne ```bash curl -X POST "https://moi.matrixorigin.cn/newmoi/export/task/create" \ -H "X-API-Key: $AI_STUDIO_API_KEY" \ -H "X-Workspace-ID: $WORKSPACE_ID" \ -H 'Content-Type: application/json' \ -d '{ "task_name": "export-orders", "creator": "data-engineer", "connector_id": "'$CONNECTOR_ID'", "connector_name": "target-mo", "type": 3, "config": { "mo_config": { "database_name": "analytics", "table_name": "orders", "new_table": true, "duplicated_strategy": 3, "column": { "export_column": [ { "source_column": "content", "mapping_column": "content" } ], "combine_column": [] } } }, "files": [ { "file_id": "file_01", "full_path": [ "volume_01", "orders.csv" ], "is_raw": false } ] }' ``` ### 导出原始文件到标准 S3 下例将一个原始文件导出到标准 S3 连接器的 `exports/` 路径，并使用 Gzip 压缩。 ```bash curl -X POST "https://moi.matrixorigin.cn/newmoi/export/task/create" \ -H "X-API-Key: $AI_STUDIO_API_KEY" \ -H "X-Workspace-ID: $WORKSPACE_ID" \ -H 'Content-Type: application/json' \ -d '{ "task_name": "export-to-s3", "creator": "data-engineer", "connector_id": "'$CONNECTOR_ID'", "connector_name": "target-s3", "type": 5, "config": { "s3_config": { "path": "exports/", "need_compress": true, "compress_method": "gzip" } }, "files": [ { "file_id": "file_01", "full_path": [ "volume_01", "orders.csv" ], "is_raw": true } ] }' ``` ## 成功响应 成功时返回 `200`。`data` 是新建的任务对象；任务创建后开始运行。请求成功仅表示任务已受理，并不表示文件已导出完成。 ```json { "code": "OK", "msg": "OK", "data": { "id": "export-task-123", "name": "export-to-matrixone", "connector_name": "target-mo", "type": 3, "status": 1, "export_source": [["volume-001", "reports", "summary.csv"]], "create_time": "2026-08-18T10:00:00Z", "end_time": null, "fileSuccess": 0, "fileFail": 0 } } ``` 响应字段如下。 | 字段 | 类型 | 说明 | | --- | --- | --- | | `code` | string | 成功时为 `OK`。 | | `msg` | string | 成功时为 `OK`。 | | `data.id` | string | 新建任务 ID，用于后续查询、重试或删除。 | | `data.name` | string | 任务名称。 | | `data.connector_name` | string | 目标连接器名称。 | | `data.type` | integer | 导出目标类别：`3` 为 MatrixOne，`4` 为 OSS，`5` 为标准 S3。 | | `data.status` | integer | 任务状态：`0` 待处理、`1` 运行中、`2` 已完成、`3` 失败。 | | `data.export_source` | string（二维字符串数组） | 待导出文件的来源路径集合。 | | `data.create_time` | string 或 null | 创建时间。 | | `data.end_time` | string 或 null | 结束时间；未结束时为 `null`。 | | `data.fileSuccess` | integer | 已成功导出的文件数。 | | `data.fileFail` | integer | 导出失败的文件数。 | ## 错误响应 参数或业务校验失败时，当前兼容接口可能仍返回 HTTP `200`，因此必须同时检查响应的 `code`。 ```json { "code": "ErrParamInvalid", "msg": "请求参数无效", "data": null } ``` ### 常见 HTTP 错误 ```{list-table} :header-rows: 1 :widths: 12 24 36 28 * - HTTP 状态码 - 错误代码 - 常见原因 - 建议操作 * - `200` - `ErrParamInvalid` - 请求体无法解析，或导出配置、来源文件不符合要求。 - 检查 `config`、连接器标识和每个文件的 `file_id`、`full_path`。 * - `200` - `ErrServer` - 目标连接器不可用、来源文件无法解析，或任务创建失败。 - 确认连接器可用、来源文件仍可访问后重试。 * - `403` - `ErrForbidden` - 当前身份没有创建导出任务或使用目标连接器的权限。 - 请求授予相应工作区和连接器权限。 * - `503` - `ErrCoreAuthorizeUnavailable` - 授权服务暂时不可用。 - 稍后重试；持续失败时联系管理员。 ``` ## 后续操作 记录 `data.id`，作为后续查询使用的任务 ID。创建成功只表示任务已受理。用该 ID [查询任务状态](get-export-task-state.md)：仍有文件等待或处理中时继续查询；等待与处理中数量都为 0 时，本次处理已结束。全部成功时无需再操作；存在失败时[查询导出文件](list-export-task-files.md)定位失败项。