CreateProject|V4.2.11|OceanBase Migration Service| docs|Distributed Database

CreateProject

Last Updated：2025-10-30 08:37:50 Updated

This topic describes the CreateProject operation provided by OceanBase Migration Service (OMS) Community Edition.

Description

You can call this operation to create a data migration or synchronization task.

Call description

Limitations

This operation is supported in OMS Community Edition V4.1.1 and later.

Request path

POST /api/v2?Action=CreateProject

Request parameters

Parameter	Type	Description
name	string	The name of the task, which cannot contain spaces.
type	string	The type of the task. Valid values: `MIGRATION` and `SYNC`.
labelIds	array	The tag IDs. You can specify up to five tag IDs.
sourceEndpointId	string	The ID of the source data source. You must call the `ListDataSource` operation to obtain the ID, which is in the `e_****` format.
sinkEndpointId	string	The ID of the target data source. You must call the `ListDataSource` operation to obtain the ID, which is in the `e_****` format.
transferMapping	object	The mapping information about the objects to be transferred.
├─ mode	string	The mapping mode for the objects to be transferred. Valid values: `SPECIFIC` and `WILDCARD`, which indicate specifying specific objects and matching objects by using a rule, respectively.
├─ databases	array	The list of database objects. For more information, see the Parameters in databases/databasesBlack section.
├─ databasesBlack	array	The blocklist of database objects used for the `WILDCARD` mode. For more information, see the Parameters in databases/databasesBlack section.
├─ tableAndViewWhiteList	array	The wildcard-based allowlist of tables and views used for the `WILDCARD` mode.
├─ tableAndViewBlackList	array	The wildcard-based blocklist of tables and views used for the `WILDCARD` mode.
commonTransferConfig	object	The common settings for transfer.
├─ tableCategory	string	The supported table types. Valid values: `ALL` (all tables), `WITH_UNIQUE_ROW_ID` (tables with a unique row ID), and `WITHOUT_UNIQUE_ROW_ID` (tables without a unique row ID). Default value: `ALL`.
├─ activeActive	boolean	Indicates whether active-active disaster recovery is enabled.
├─ mqSerializerType	string	The JSON data serialization type for delivering data to message queues. Valid values: `DEFAULT`, `CANAL`, `DATAWORKS_V2`, `SHAREPLEX`, `DEFAULT_WITH_SCHEMA`, `DEBEZIUM`, `DEBEZIUMFLATTEN`, and `DEBEZIUMSMT`.
├─ mqPartitionMode	string	The partition routing mode for delivering data to message queues. Valid values: `ONE`, `HASH`, and `TABLE`. `ONE` specifies to deliver data to a specified partition. `HASH` specifies to deliver data to HASH partitions based on the primary key column or sharding columns. `TABLE` specifies to deliver data to HASH partitions based on database and table names.
├─ mqPartition	integer	When the value of the `partitionMode` parameter is `ONE`, this parameter indicates the location of the partition to which data is delivered in the current topic.
├─ datahubTopicType	string	The type of the topic for delivering data to DataHub. Valid values: `TUPLE` and `BLOB`.
├─ rocketMqProducerGroup	string	The name of the producer group. This parameter takes effect when the type of the target is RocketMQ. The default value is `OMS`.
├─ rocketMqMsgTags	string	The tag of the message. This parameter takes effect when the type of the target is RocketMQ. For example, when the value is `default`, the `_tag` suffix is added to the value by default.
├─ rocketMqEnableMsgTrace	boolean	Indicates whether message tracing is enabled. This parameter takes effect when the type of the target is RocketMQ.
├─ rocketMqSendMsgTimeout	long	The message delivery timeout period. This parameter takes effect when the type of the target is RocketMQ.
├─ dataWorksBusinessName	string	The ID of the business system.
enableStructTransfer	boolean	Indicates whether schema transfer is allowed.
structTransferConfig	object	The settings for schema transfer.
├─ byteCharConvertStrategy	string	The BYTE/CHAR conversion scheme. Valid values: `IGNORE_BYTE_IF_BYTE_USED`, `FORCE_CHAR_IF_BYTE_USED`, `EXPAND_LEN_IF_BYTE_USED`, and `DO_NOTHING_IF_BYTE_USED`. The default value is `DO_NOTHING_IF_BYTE_USED`.
├─ deferIndexCreation	boolean	Indicates whether post-indexing is allowed. The default value is `false`.
├─ shardsCount	integer	The number of index shards.
├─ replicasCount	integer	The number of index replicas.
├─ dateFormat	string	The date format. For example, `yyyy-MM-dd HH:mm:ss`.
enableFullTransfer	boolean	Indicates whether full transfer is enabled.
enableFullVerify	boolean	Indicates whether full verification is enabled.
fullTransferConfig	object	The settings for full transfer.
├─ nonePkUkTruncateDstTable	boolean	Indicates whether the target table is cleared during full migration from a table without a unique index.
├─ allowDestTableNotEmpty	string	The processing strategy to apply when the target table has records, including Ignore and Stop Migration. The value `true` indicates that Ignore is selected. If the target is a MySQL database or OceanBase Database Community Edition, OMS Community Edition overwrites the existing data in the target table. Notice If you set the value to true, data is pulled in IN mode for full verification. In this case, the scenario where the target table contains more data than the source table cannot be verified, and the verification efficiency will be decreased. The value `false` indicates that Stop Migration is selected. If the target table has records, an error is returned during full migration. In this case, clear the existing data in the target table and try again. Notice After an error is returned, if you click Resume in the dialog box, OMS Community Edition ignores this error and continues to migrate data. Proceed with caution.
├─ fullTransferSpeedMode	string	The concurrency for full migration. Valid values: `STEADY`, `NORMAL`, and `FAST`. If full migration is involved, the `fullTransferSpeedMode` parameter is required and can be set to `NORMAL`.
├─ fullVerifySpeedMode	string	The concurrency for full verification. Valid values: `STEADY`, `NORMAL`, and `FAST`. If full verification is involved, the `fullVerifySpeedMode` parameter is required and can be set to `NORMAL`.
enableIncrTransfer	boolean	Specifies whether to enable incremental synchronization.
enableReverseIncrTransfer	boolean	Specifies whether to enable reverse increment.
incrTransferConfig	object	The settings for incremental synchronization.
├─ startTimestamp	string	The start timestamp for incremental synchronization. This parameter is available only when incremental synchronization is enabled and full transfer is disabled.
├─ recordTypeWhiteList	array	The data types of incremental data synchronized in incremental synchronization. Supported data types are HEARTBEAT, INSERT, UPDATE, DELETE, BEGIN, COMMIT, ROLLBACK, DDL, and ROW.
├─ storeLogKeptHour	integer	The retention period of logs when incremental synchronization is enabled and the Store component is used to pull incremental logs. Unit: hours. The default retention period is seven days. The maximum retention period is 365 days.
├─ enableSequencingWithinTxn	boolean	Indicates whether intra-transaction sequencing is enabled when incremental synchronization is enabled and the Store component is used to pull incremental logs.
├─ incrSyncConcurrency	integer	The number of threads for incremental synchronization. Default value: `64`.
├─ enableIncrSyncStatistics	boolean	Indicates whether statistics collection is enabled for incremental DML and DDL operation records.

Parameters in databases/databasesBlack

Parameter	Type	Description
mappedName	string	The name of the target database.
name	string	The name of the source database.
id	string	The ID of the database.
tables	array	The settings for the table objects to be transferred in the current database. When the value of the `mode` parameter is `WILDCARD`, this parameter indicates the settings for a specific blocklist or allowlist of tables and views.
├─ mappedName	string	The mapped-to table name.
├─ name	string	The name of the table.
├─ id	string	The ID of the table.
├─ whereClause	string	The `WHERE` clause in the standard SQL syntax that is used to configure row filtering.
├─ filterColumns	array	The filter columns.
├─ shardColumns	array	The sharding columns.
views	array	The settings for the view objects to be transferred in the current database.
├─ mappedName	string	The mapped-to view name.
├─ name	string	The name of the view.
├─ id	string	The ID of the view.
├─ whereClause	string	The `WHERE` clause in the standard SQL syntax that is used to configure row filtering.
├─ filterColumns	array	The filter columns.
├─ shardColumns	array	The sharding columns.
specificTables	array	The settings for the matched table objects. When the value of the `mode` parameter is `WILDCARD`, this parameter indicates the renaming and row filtering settings for the matched table objects.
├─ mappedName	string	The mapped-to table name.
├─ name	string	The name of the table.
├─ id	string	The ID of the table.
├─ whereClause	string	The `WHERE` clause in the standard SQL syntax that is used to configure row filtering.
├─ filterColumns	array	The filter columns.
├─ shardColumns	array	The sharding columns.
specificViews	array	The settings for the matched view objects. When the value of the `mode` parameter is `WILDCARD`, this parameter indicates the renaming settings for the matched view objects.
├─ mappedName	string	The mapped-to view name.
├─ name	string	The name of the view.
├─ id	string	The ID of the view.
├─ whereClause	string	The `WHERE` clause in the standard SQL syntax that is used to configure row filtering.
├─ filterColumns	array	The filter columns.
├─ shardColumns	array	The sharding columns.
procedures	array	The settings for stored procedures in the current database.
├─ name	string	The name of the stored procedure.
├─ mappedName	string	The mapped-to stored procedure name.
functions	array	The settings for functions in the current database.
├─ name	string	The name of the function.
├─ mappedName	string	The mapped-to function name.

Response parameters

Parameter	Type	Description
success	boolean	Indicates whether the call is successful.
errorDetail	object	The error details.
code	string	The error code.
message	string	The error description.
advice	string	The suggestions.
requestId	string	The ID of the request.
pageNumber	integer[int32]	The number of the page returned.
pageSize	integer[int32]	The number of records returned on each page.
totalCount	integer[int64]	The total number of records returned.
cost	string	The time spent in processing the request, in seconds.
data	string	The ID of the task.

Examples

Sample request

{
    "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,
        "shardsCount": 1,
        "replicasCount": 1,
        "dateFormat": "yyyy-MM-dd HH:mm:ss"
    },
    "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
    }
}

Sample response

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

Enterprise Edition

Community Edition