创建任务

创建导出任务，将选定文件或处理结果写入对象存储或 MatrixOne。成功响应表示任务已受理；使用返回的任务 ID 查询各文件的实际处理情况。

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

调用前准备

先查询可导出文件或在创建页面选择文件，并确认目标连接器可用。准备有目标工作区访问权限的个人访问令牌、目标工作区 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

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 压缩。

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 是新建的任务对象；任务创建后开始运行。请求成功仅表示任务已受理，并不表示文件已导出完成。

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

{
  "code": "ErrParamInvalid",
  "msg": "请求参数无效",
  "data": null
}

常见 HTTP 错误

HTTP 状态码	错误代码	常见原因	建议操作
200	ErrParamInvalid	请求体无法解析，或导出配置、来源文件不符合要求。	检查 config、连接器标识和每个文件的 file_id、full_path。
200	ErrServer	目标连接器不可用、来源文件无法解析，或任务创建失败。	确认连接器可用、来源文件仍可访问后重试。
403	ErrForbidden	当前身份没有创建导出任务或使用目标连接器的权限。	请求授予相应工作区和连接器权限。
503	ErrCoreAuthorizeUnavailable	授权服务暂时不可用。	稍后重试；持续失败时联系管理员。

后续操作

记录 data.id，作为后续查询使用的任务 ID。创建成功只表示任务已受理。用该 ID 查询任务状态：仍有文件等待或处理中时继续查询；等待与处理中数量都为 0 时，本次处理已结束。全部成功时无需再操作；存在失败时查询导出文件定位失败项。

最后更新于 2026 年 8 月 22 日