创建任务

创建任务

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

编辑

本文为您介绍 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。

示例

请求示例

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

返回示例

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