---
title: "创建任务 | OceanBase 文档中心"
description: 创建任务 本文为您介绍 OceanBase 迁移服务（OceanBase Migration Service，OMS）社区版提供的 OpenAPI：创建任务 CreateProject。 功能说明 本接口用于创建数据迁移或数据同步任务。 调用说明 接口约束 本接口适用于 OMS 社区版 V4.1.1-CE 及之后版本…
---
切换语言

- 中文站 - 简体中文
- International - English
- 日本站 - 日本語

文档反馈![](https://mdn.alipayobjects.com/huamei_22khvb/afts/img/A*L03BS6f-o40AAAAAAAAAAAAADiGDAQ/original) 迁移服务 OMSV 4.2.8 社区版

# 创建任务

更新时间：2026-04-14 15:40:47

[编辑](https://github.com/oceanbase/oms-doc/edit/V4.2.8/zh-CN/1200.reference-guide/100.api-reference/200.create-project.md)  

本文为您介绍 OceanBase 迁移服务（OceanBase Migration Service，OMS）社区版提供的 OpenAPI：创建任务 CreateProject。

## 功能说明

本接口用于创建数据迁移或数据同步任务。

## 调用说明

### 接口约束

本接口适用于 OMS 社区版 V4.1.1-CE 及之后版本。

### 请求路径

`POST /api/v2?Action=CreateProject`

### 请求参数

| 参数 | 类型 | 描述 |
| --- | --- | --- |
| name | string | 任务的名称，不能包含空格。 |
| type | string | 任务的类型，包括 `MIGRATION`（表示数据迁移任务）和 `SYNC`（表示数据同步任务）。 |
| labelIds | array | 标签 ID 的集合，最多支持 5 个。 |
| sourceEndpointId | string | 源端数据源的 ID。您需要调用 `ListDataSource` 接口获取 ID，格式为 `e_****`。 |
| sinkEndpointId | string | 目标端数据源的 ID。您需要调用 `ListDataSource` 接口获取 ID，格式为 `e_****`。 |
| transferMapping | object | 传输对象的映射信息。 |
| ├─ mode | string | 传输对象映射模式，包括 `SPECIFIC`（表示指定对象）和 `WILDCARD`（表示匹配规则）。 |
| ├─ databases | array | 数据库对象列表。具体包含的信息请参见《databases/databasesBlack 数据结构》。 |
| ├─ databasesBlack | array | 匹配规则模式：数据库对象黑名单列表。具体包含的信息请参见《databases/databasesBlack 数据结构》。 |
| ├─ tableAndViewWhiteList | array | 匹配规则模式：表和视图的通配白名单列表。 |
| ├─ tableAndViewBlackList | array | 匹配规则模式：表和视图的通配黑名单列表。 |
| commonTransferConfig | object | 通用的传输配置。 |
| ├─ tableCategory | string | 支持的表类型。包括 ALL（所有表）、WITH_UNIQUE_ROW_ID（有唯一行标识的表）和 WITHOUT_UNIQUE_ROW_ID（无唯一行标识的表），默认值为 ALL。 |
| ├─ activeActive | boolean | 是否为容灾双活场景。 |
| ├─ mqSerializerType | string | 投递至消息队列时，数据 JSON 序列化类型。包括 DEFAULT、CANAL、DATAWORKS_V2、SHAREPLEX、DEFAULT_WITH_SCHEMA、 DEBEZIUM、DEBEZIUMFLATTEN 和 DEBEZIUMSMT。 |
| ├─ mqPartitionMode | string | 投递至消息队列时，分区路由方式。包括 ONE（指定分区投递）、HASH（根据主键/分片列值进行 HASH 分区投递、TABLE（根据库表名进行 HASH 分区投递）。 |
| ├─ mqPartition | integer | 当 `partitionMode` 为 `ONE` 时，该参数表示投递的分区在当前 topic 下的位置。 |
| ├─ datahubTopicType | string | 投递至消息队列 DataHub 时，指定 Topic 的类型。类型包括 `TUPLE` 和 `BLOB`。 |
| ├─ rocketMqProducerGroup | string | 指定生产组名（目标端为 RocketMQ 时生效），默认值为 OMS。 |
| ├─ rocketMqMsgTags | string | 设置消息 tag（目标端为 RocketMQ 时生效）。默认 default->default_tag，即值为 `default` 时，会默认添加一个 `_tag` 的后缀。 |
| ├─ rocketMqEnableMsgTrace | boolean | 是否开启消息追踪，仅目标端为 RocketMQ 时生效。 |
| ├─ rocketMqSendMsgTimeout | long | 设置消息投递超时时间，仅目标端为 RocketMQ 时生效。 |
| ├─ dataWorksBusinessName | string | 业务系统标识。 |
| enableStructTransfer | boolean | 是否允许结构传输。 |
| structTransferConfig | object | 结构传输的配置。 |
| ├─ byteCharConvertStrategy | string | byte/char 转换方案，包括 `IGNORE_BYTE_IF_BYTE_USED`、`FORCE_CHAR_IF_BYTE_USED`、`EXPAND_LEN_IF_BYTE_USED` 和 `DO_NOTHING_IF_BYTE_USED`（默认值）。 |
| ├─ deferIndexCreation | boolean | 是否允许索引后置，默认值为不允许。 |
| enableFullTransfer | boolean | 是否启用全量传输。 |
| enableFullVerify | boolean | 是否启用全量校验。 |
| fullTransferConfig | object | 全量传输的配置。 |
| ├─ nonePkUkTruncateDstTable | boolean | 处理源端无唯一索引表的全量迁移时，是否清空目标表。 |
| ├─ allowDestTableNotEmpty | string | 目标端表对象存在记录时处理策略，包括 **忽略** 和 **停止迁移**。   - 设置为 true 时，表示选择忽略：当目标端表对象存在数据时，OMS 社区版将采用忽略或者覆盖的策略进行数据写入。仅目标端为 MySQL 数据库或 OceanBase 社区版时支持覆盖。     #### 注意      选择 **忽略**，全量校验将使用 IN 模式拉取数据，无法校验目标端存在源端没有的数据的场景，并且校验性能会有一定程度降级。 - 设置为 false 时，表示选停止迁移：当目标端表对象存在数据时，全量迁移会报错不允许迁移，请处理好目标端数据后再继续迁移。     #### 注意      如果出错后单击恢复，OMS 社区版将忽略该配置选项，继续迁移表数据，请谨慎操作。 |
| ├─ fullTransferSpeedMode | string | 全量迁移并发速度，包括 STEADY、NORMAL 和 FAST。   ​如果有全量迁移步骤，则 FullTransferSpeedMode 必传，可以传 NORMAL。 |
| ├─ fullVerifySpeedMode | string | 全量校验并发速度，包括 STEADY、NORMAL 和 FAST。   如果有全量校验步骤，则 FullVerifySpeedMode 必传，可以传 NORMAL。 |
| enableIncrTransfer | boolean | 是否启用增量同步。 |
| enableReverseIncrTransfer | boolean | 是否启用反向增量同步。 |
| incrTransferConfig | object | 增量同步的配置。 |
| ├─ startTimestamp | string | 增量同步起始位点。仅启用增量同步但未启用全量传输时，支持设置该参数。 |
| ├─ recordTypeWhiteList | array | 有增量同步阶段时，同步的增量数据类型。包括 HEARTBEAT、INSERT、UPDATE、DELETE、BEGIN、COMMIT、ROLLBACK、DDL 和 ROW。 |
| ├─ storeLogKeptHour | integer | 有增量同步阶段且增量日志拉取组件为 Store 时，日志的保存时间。单位为小时，默认 7 天，最长支持 365 天。 |
| ├─ enableSequencingWithinTxn | boolean | 有增量同步阶段且增量日志拉取组件为 Store 时，是否开启事务内序号编排。 |
| ├─ incrSyncConcurrency | integer | 增量同步的线程数，默认值为 64。 |
| ├─ enableIncrSyncStatistics | boolean | 是否开启增量记录（DML、DDL）统计。 |

- **databases/databasesBlack 数据结构**

  | 参数 | 类型 | 描述 |
  | --- | --- | --- |
  | mappedName | string | 目标端数据库的名称。 |
  | name | string | 源端数据库的名称。 |
  | id | string | 数据库的 ID。 |
  | tables | array | 当前数据库中传输表对象的配置列表。`Mode` 为 `WILDCARD` 时，该参数表示具体黑名单或白名单的配置，表和视图共用。 |
  | ├─ mappedName | string | 表的映射名称。 |
  | ├─ name | string | 表的名称。 |
  | ├─ id | string | 表的 ID。 |
  | ├─ whereClause | string | 通过标准的 SQL 语句中的 `WHERE` 子句，用于配置行过滤。 |
  | ├─ filterColumns | array | 过滤列集合。 |
  | ├─ shardColumns | array | 分片列集合。 |
  | views | array | 当前数据库中传输视图对象的配置。 |
  | ├─ mappedName | string | 视图的映射名称。 |
  | ├─ name | string | 视图的名称。 |
  | ├─ id | string | 视图的 ID。 |
  | ├─ whereClause | string | 标准的 SQL 语句中的 `WHERE` 子句，用于配置行过滤。 |
  | ├─ filterColumns | array | 过滤列集合。 |
  | ├─ shardColumns | array | 分片列集合。 |
  | specificTables | array | 具体表对象的配置列表。`mode` 为 `WILDCARD` 时，该参数表示具体表对象的重命名、行过滤配置。 |
  | ├─ mappedName | string | 表的映射名称。 |
  | ├─ name | string | 表的名称。 |
  | ├─ id | string | 表的 ID。 |
  | ├─ whereClause | string | 通过标准的 SQL 语句中的 `WHERE` 子句，用于配置行过滤。 |
  | ├─ filterColumns | array | 过滤列集合。 |
  | ├─ shardColumns | array | 分片列集合。 |
  | specificViews | array | 具体视图对象的配置列表。`mode` 为 `WILDCARD` 时，该参数表示具体视图对象的重命名配置。 |
  | ├─ mappedName | string | 视图的映射名称。 |
  | ├─ name | string | 视图的名称。 |
  | ├─ id | string | 视图的 ID。 |
  | ├─ whereClause | string | 标准的 SQL 语句中的 `WHERE` 子句，用于配置行过滤。 |
  | ├─ filterColumns | array | 过滤列集合。 |
  | ├─ shardColumns | array | 分片列集合。 |
  | procedures | array | 当前数据库中存储过程的配置。 |
  | ├─ name | string | 存储过程的名称。 |
  | ├─ mappedName | string | 存储过程的映射名称。 |
  | functions | array | 当前数据库中函数的配置。 |
  | ├─ name | string | 函数的名称。 |
  | ├─ mappedName | string | 函数的映射名称。 |

### 返回结果

| 参数 | 类型 | 描述 |
| --- | --- | --- |
| success | boolean | 是否调用成功。 |
| errorDetail | object | 错误详情。 |
| code | string | 错误码。 |
| message | string | 描述信息。 |
| advice | string | 建议。 |
| requestId | string | 请求 ID。 |
| pageNumber | integer[int32] | 页序号，分页查询时生效。 |
| pageSize | integer[int32] | 页大小，分页查询时生效。 |
| totalCount | integer[int64] | 总数，分页查询时生效。 |
| cost | string | 请求耗时，单位为秒。 |
| data | string | 任务的 ID。 |

## 示例

### 请求示例

```JSON
{
    "name":"test",
    "type":"MIGRATION",
    "labelIds":[
        "l_4w****wygjk"
    ],
    "sourceEndpointId":"e_4wg07f****",
    "sinkEndpointId":"e_4wfy2****",
    "transferMapping":{
        "mode":"SPECIFIC",
        "databases":[
            {
                "mappedName":"gez3***",
                "name":"ion1****bmysql",
                "id":null,
                "tables":[
                    {
                        "mappedName":"tion12***20obmysql2",
                        "name":"GRATION129****",
                        "id":null,
                        "whereClause":null,
                        "filterColumns":null,
                        "shardColumns":null,
                    }
                ],
                "views":null,
                "procedures":[
                    {
                        "name": "baxxx_crxxx_user",
                        "mappedName": "baxxx_crxxx_user_rename"
                    }
                ],
                "functions":[
                    {
                        "name": "rand_string",
                        "mappedName": "rand_string_rename"
                    }
                ],
                "specificTables":null,
                "specificViews":null
            }
        ],
        "databasesBlack":null,
        "tableAndViewWhiteList":null,
        "tableAndViewBlackList":null
    },
    "commonTransferConfig":{
        "tableCategory":null,
        "activeActive":false,
        "mqSerializerType":null,
        "mqPartitionMode":null,
        "mqPartition":0,
        "datahubTopicType":null,
        "rocketMqProducerGroup":null,
        "rocketMqMsgTags":null,
        "rocketMqEnableMsgTrace":null,
        "rocketMqSendMsgTimeout":null,
        "dataWorksBusinessName":null
    },
    "enableStructTransfer":true,
    "structTransferConfig":{
        "byteCharConvertStrategy":"DO_NOTHING_IF_BYTE_USED",
        "deferIndexCreation":true
    },
    "enableFullTransfer":true,
    "enableFullVerify":true,
    "fullTransferConfig":{
        "nonePkUkTruncateDstTable":null,
        "allowDestTableNotEmpty":true,
        "fullTransferSpeedMode":"NORMAL",
        "fullVerifySpeedMode":"NORMAL"
    },
    "enableIncrTransfer":true,
    "enableReverseIncrTransfer":true,
    "incrTransferConfig":{
        "startTimestamp":1689201369,
        "recordTypeWhiteList":[
            "DELETE",
            "INSERT",
            "UPDATE"
        ],
        "storeLogKeptHour":120,
        "enableSequencingWithinTxn":true,
        "incrSyncConcurrency":64,
        "enableIncrSyncStatistics":true
    }
}

```

### 返回示例

```JSON
{
    "Success":true,
    "ErrorDetail":{
        "Code":"CM-RES***11",
        "Level":"WARN",
        "Message":"A system error occurred.",
        "Proposal":"Contact the administrator."
    },
    "Code":"INNER_ERROR",
    "Message":"A system error occurred.",
    "Advice":"Contact the administrator.",
    "RequestId":"XCVSADG****DSGDS",
    "PageNumber":1,
    "PageSize":1,
    "TotalCount":1,
    "Cost":"27 ms",
    "Data":"np_****"
}

```

 上一篇 下一篇 ![有帮助](https://gw.alipayobjects.com/mdn/ob_asset/afts/img/A*y6ocSqN8cqsAAAAAAAAAAAAAARQnAQ)![无帮助](https://gw.alipayobjects.com/mdn/ob_asset/afts/img/A*BG9IQJyLHF8AAAAAAAAAAAAAARQnAQ)![反馈](https://gw.alipayobjects.com/mdn/ob_asset/afts/img/A*eTWdQKCRKHwAAAAAAAAAAAAAARQnAQ)[AI](https://www.oceanbase.com/obi) 咨询热线