Configures a data migration or synchronization task.

Note If you want to run a Data Transmission Service (DTS) task on a DTS dedicated cluster, you must configure the task before you purchase a DTS instance. In addition, DTS dedicated clusters do not support DTS tasks that are configured to migrate or synchronize data across regions.

Debugging

OpenAPI Explorer automatically calculates the signature value. For your convenience, we recommend that you call this operation in OpenAPI Explorer. OpenAPI Explorer dynamically generates the sample code of the operation for different SDKs.

Request parameters

Parameter Type Required Example Description
Action String Yes ConfigureDtsJob

The operation that you want to perform. Set the value to ConfigureDtsJob.

DtsJobName String Yes rdsmysql_to_mysql

The name of the DTS instance.

SourceEndpointInstanceType String Yes RDS

The type of the source instance. Valid values:

Alibaba Cloud database instances
  • RDS: ApsaraDB RDS for MySQL instance, ApsaraDB RDS for SQL Server instance, ApsaraDB RDS for PostgreSQL instance, or ApsaraDB RDS for MariaDB TX instance
  • PolarDB: PolarDB for MySQL cluster
  • REDIS: ApsaraDB for Redis instance
  • POLARDBX10: PolarDB-X 1.0 instance
  • POLARDBX20: PolarDB-X 2.0 instance
  • MONGODB: ApsaraDB for MongoDB instance
  • DISTRIBUTED_DMSLOGICDB: Data Management (DMS) logical database
Self-managed databases
  • OTHER: self-managed database with a public IP address
  • ECS: self-managed database hosted on an Elastic Compute Service (ECS) instance
  • EXPRESS: self-managed database connected over Express Connect
  • CEN: self-managed database connected over Cloud Enterprise Network (CEN)
  • DG: self-managed database connected over Database Gateway
Note
  • If the source instance is a PolarDB for Oracle cluster, you must set this parameter to OTHER or EXPRESS because you can use a PolarDB for Oracle cluster only as a self-managed database connected over the Internet or Express Connect.
  • For more information, see Supported databases.
  • If the source instance is a self-managed database, you must deploy the network environment for the database. For more information, see Preparation overview.
SourceEndpointInstanceID String No rm-bp1imrtn6fq7h****

The ID of the source instance.

If the source instance is an Alibaba Cloud database instance, you must specify the ID of the database instance. For example, if the source instance is an ApsaraDB RDS for MySQL instance, you must specify the ID of the ApsaraDB RDS for MySQL instance.

If the source instance is a self-managed database, the value of this parameter varies with the value of the SourceEndpointInstanceType parameter.

  • If the SourceEndpointInstanceType parameter is set to ECS, you must specify the ID of the ECS instance.
  • If the SourceEndpointInstanceType parameter is set to DG, you must specify the ID of the database gateway.
  • If the SourceEndpointInstanceType parameter is set to EXPRESS or CEN, you must specify the ID of the VPC that is connected to the source instance.
Note If the SourceEndpointInstanceType parameter is set to CEN, you must also specify the ID of the CEN instance in the Reserve parameter. For more information, see Reserve.
SourceEndpointEngineName String No MYSQL

The database engine of the source instance. Valid values:

  • MYSQL: ApsaraDB RDS for MySQL instance or self-managed MySQL database
  • MARIADB: ApsaraDB RDS for MariaDB TX instance
  • PolarDB: PolarDB for MySQL cluster
  • POLARDB_O: PolarDB for Oracle cluster
  • POLARDBX10: PolarDB-X 1.0 instance
  • POLARDBX20: PolarDB-X 2.0 instance
  • ORACLE: self-managed Oracle database
  • POSTGRESQL: ApsaraDB RDS for PostgreSQL instance or self-managed PostgreSQL database
  • MSSQL: ApsaraDB RDS for SQL Server instance or self-managed SQL Server database
  • MONGODB: ApsaraDB for MongoDB instance or self-managed MongoDB database
  • DB2: self-managed Db2 for LUW database
  • AS400: self-managed Db2 for i database
  • DMSPOLARDB: DMS logical database
  • HBASE: self-managed HBase database
  • TERADATA: Teradata database
  • TiDB: TiDB database
  • REDIS: ApsaraDB for Redis instance or self-managed Redis database
Note
  • Default value: MYSQL.
  • If the SourceEndpointEngineName parameter is set to MONGODB, you must also specify the architecture type of the MongoDB database in the Reserve parameter. For more information, see Reserve.
SourceEndpointRegion String No cn-hangzhou

The ID of the region in which the source instance resides. For more information, see List of supported regions.

Note If the source instance is an Alibaba Cloud database instance, this parameter is required.
SourceEndpointIP String No 172.16.**.***

The IP address of the source instance.

Note If the SourceEndpointInstanceType parameter is set to OTHER, EXPRESS, DG, or CEN, this parameter is available and required.
SourceEndpointPort String No 3306

The database service port of the source instance.

Note If the source instance is a self-managed database, this parameter is available and required.
SourceEndpointOracleSID String No testsid

The system ID (SID) of the Oracle database.

Note If the SourceEndpointEngineName parameter is set to ORACLE and the Oracle database is deployed in an architecture that is not a Real Application Cluster (RAC), this parameter is available and required.
SourceEndpointDatabaseName String No dtstestdatabase

The name of the database to which the objects to be migrated in the source instance belong.

Note If the source instance is a PolarDB for Oracle cluster, a PostgreSQL database, or a MongoDB database, this parameter is available and required.
SourceEndpointUserName String No dtstest

The database account of the source database.

Note
SourceEndpointPassword String No Test123456

The password of the source database account.

SourceEndpointOwnerID String No 140692647406****

The ID of the Alibaba Cloud account to which the source instance belongs.

Note You can specify this parameter to migrate or synchronize data across different Alibaba Cloud accounts. In this case, you must specify the SourceEndpointRole parameter.
SourceEndpointRole String No ram-for-dts

The name of the RAM role configured for the Alibaba Cloud account that owns the source instance.

Note This parameter is required when you migrate or synchronize data across different Alibaba Cloud accounts. For information about the permissions and authorization methods of the RAM role, see Configure RAM authorization for cross-account data migration and synchronization.
DestinationEndpointInstanceType String Yes EXPRESS

The type of the destination instance. Valid values:

Alibaba Cloud database instances
  • RDS: ApsaraDB RDS for MySQL instance, ApsaraDB RDS for SQL Server instance, ApsaraDB RDS for PostgreSQL instance, or ApsaraDB RDS for MariaDB TX instance
  • PolarDB: PolarDB for MySQL cluster
  • POLARDBX10: PolarDB-X 1.0 instance
  • POLARDBX20: PolarDB-X 2.0 instance
  • REDIS: ApsaraDB for Redis instance
  • ADS: AnalyticDB for MySQL V2.0 cluster or AnalyticDB for MySQL V3.0 cluster
  • MONGODB: ApsaraDB for MongoDB instance
  • GREENPLUM: AnalyticDB for PostgreSQL instance
  • DATAHUB: DataHub project
  • ELK: Elasticsearch cluster
  • Tablestore: Tablestore instance
  • ODPS: MaxCompute project
Self-managed databases
  • OTHER: self-managed database with a public IP address
  • ECS: self-managed database hosted on an ECS instance
  • EXPRESS: self-managed database connected over Express Connect
  • CEN: self-managed database connected over CEN
  • DG: self-managed database connected over Database Gateway
Note
  • If the destination instance is a PolarDB for Oracle cluster, you must set this parameter to OTHER or EXPRESS because you can use a PolarDB for Oracle cluster only as a self-managed database connected over the Internet or Express Connect.
  • If the destination instance is a Message Queue for Apache Kafka instance, you must set this parameter to ECS or EXPRESS because you can use a Message Queue for Apache Kafka instance only as a self-managed database connected over ECS or Express Connect.
  • For more information, see Supported databases.
  • If the destination instance is a self-managed database, you must deploy the network environment for the database. For more information, see Preparation overview.
DestinationEndpointInstanceID String No vpc-bp1opxu1zkhn00gzv****

The ID of the destination instance.

If the destination instance is an Alibaba Cloud database instance, you must specify the ID of the database instance. For example, if the destination instance is an ApsaraDB RDS for MySQL instance, you must specify the ID of the ApsaraDB RDS for MySQL instance.

If the destination instance is a self-managed database, the value of this parameter varies with the value of the DestinationEndpointInstanceType parameter.

  • If the DestinationEndpointInstanceType parameter is set to ECS, you must specify the ID of the ECS instance.
  • If the DestinationEndpointInstanceType parameter is set to DG, you must specify the ID of the database gateway.
  • If the DestinationEndpointInstanceType parameter is set to EXPRESS or CEN, you must specify the ID of the VPC that is connected to the source instance.
Note If the DestinationEndpointInstanceType parameter is set to CEN, you must also specify the ID of the CEN instance in the Reserve parameter. For more information, see Reserve.
DestinationEndpointEngineName String No MySQL

The database engine of the destination instance. Valid values:

  • MySQL: ApsaraDB RDS for MySQL instance or self-managed MySQL database
  • MARIADB: ApsaraDB RDS for MariaDB TX instance
  • PolarDB: PolarDB for MySQL cluster
  • POLARDB_O: PolarDB for Oracle cluster
  • POLARDBX10: PolarDB-X 1.0 instance
  • POLARDBX20: PolarDB-X 2.0 instance
  • ORACLE: self-managed Oracle database
  • POSTGRESQL: ApsaraDB RDS for PostgreSQL instance or self-managed PostgreSQL database
  • MSSQL: ApsaraDB RDS for SQL Server instance or self-managed SQL Server database
  • ADS: AnalyticDB for MySQL V2.0 cluster
  • ADB30: AnalyticDB for MySQL V3.0 cluster
  • MONGODB: ApsaraDB for MongoDB instance or self-managed MongoDB database
  • GREENPLUM: AnalyticDB for PostgreSQL instance
  • KAFKA: Message Queue for Apache Kafka instance or self-managed Kafka cluster
  • DATAHUB: DataHub project
  • DB2: self-managed Db2 for LUW database
  • AS400: self-managed Db2 for i database
  • ODPS: MaxCompute project
  • Tablestore: Tablestore instance
  • ELK: Elasticsearch cluster
  • REDIS: ApsaraDB for Redis instance or self-managed Redis database
Note
  • Default value: MYSQL.
  • If the DestinationEndpointEngineName parameter is set to KAFKA or MONGODB, you must also specify the database information in the Reserve parameter. For more information, see Reserve.
DestinationEndpointRegion String No cn-hangzhou

The ID of the region in which the destination instance resides. For more information, see List of supported regions.

Note If the destination instance is an Alibaba Cloud database instance, this parameter is required.
DestinationEndpointIP String No 172.16.**.***

The IP address of the destination instance.

Note If the DestinationEndpointInstanceType parameter is set to OTHER, EXPRESS, DG, or CEN, this parameter is available and required.
DestinationEndpointPort String No 3306

The database service port of the destination instance.

Note If the destination instance is a self-managed database, this parameter is available and required.
DestinationEndpointDataBaseName String No dtstestdata

The name of the database to which the objects migrated to the destination instance belong.

Note
  • If the destination instance is a PolarDB for Oracle cluster, an AnalyticDB for PostgreSQL instance, a PostgreSQL database, a MaxCompute project, or a MongoDB database, this parameter is available and required.
  • If the destination instance is a MaxCompute project, you must specify the ID of the MaxCompute project.
DestinationEndpointUserName String No dtstest

The database account of the destination database.

Note
DestinationEndpointPassword String No Test123456

The password of the destination database account.

Note If the destination database is a MaxCompute project, you must specify the AccessKey secret of your Alibaba Cloud account. For information about how to obtain your AccessKey pair, see Create an AccessKey pair.
StructureInitialization Boolean Yes true

Specifies whether to perform schema migration or synchronization. Default value: true. Valid values:

  • true: performs schema migration or synchronization.
  • false: does not perform schema migration or synchronization.
DataInitialization Boolean Yes true

Specifies whether to perform full data migration or synchronization. Default value: true. Valid values:

  • true: performs full data migration or synchronization.
  • false: does not perform full data migration or synchronization.
DataSynchronization Boolean Yes true

Specifies whether to perform incremental data migration or synchronization. Default value: false. Valid values:

  • false: does not perform incremental data migration or synchronization.
  • true: performs incremental data migration or synchronization.
DbList String Yes {"dtstest":{"name":"dtstest","all":true}}

The objects that you want to migrate or synchronize. The value is a JSON string. For more information, see Objects of DTS tasks.

Reserve String No { "srcInstanceId": "cen-9kqshqum*******" }

The reserved parameter of DTS. The value is a JSON string. You can specify this parameter to add more configurations of the source or destination instance to the DTS task. For example, you can specify the data storage format of the destination Kafka database and the ID of the CEN instance. For more information, see Reserve.

Checkpoint String No 1610540493

The start offset of incremental data migration or synchronization. The value is a UNIX timestamp. Unit: seconds.

DestinationEndpointOracleSID String No testsid

The SID of the Oracle database.

Note If the DestinationEndpointEngineName parameter is set to ORACLE and the Oracle database is deployed in a non-RAC architecture, this parameter is available and required.
JobType String Yes SYNC

The type of the task. Valid values:

  • MIGRATION: data migration task
  • SYNC: data synchronization task
DtsJobId String No k2gm967v16f****

The ID of the data migration or synchronization task.

Note You must specify at least one of the DtsJobId and DtsInstanceId parameters. You can call the DescribeDtsJobs operation to query the task ID.
DtsInstanceId String No dtsk2gm967v16f****

The ID of the data migration or synchronization instance.

Note You must specify at least one of the DtsJobId and DtsInstanceId parameters. You can call the DescribeDtsJobs operation to query the instance ID.
DelayPhone String No 1361234****,1371234****

The mobile numbers that receive latency-related alerts. Separate multiple mobile numbers with commas (,).

Note
  • This parameter is available only for China site (aliyun.com) users. Only mobile numbers in the Chinese mainland are supported. Up to 10 mobile numbers can be specified.
  • International site (alibabacloud.com) users cannot receive alerts by using mobile phones, but can set alert rules for DTS tasks in the CloudMonitor console.
DelayRuleTime Long No 10

The threshold for triggering latency-related alerts. Unit: seconds. The value must be an integer. You can set the threshold based on your business needs. To prevent jitters caused by network and database overloads, we recommend that you set the threshold to more than 10 seconds.

Note If the DelayNotice parameter is set to true, this parameter is required.
DelayNotice Boolean No true

Specifies whether to monitor the task latency. Valid values:

  • true: monitors the task latency.
  • false: does not monitor the task latency.
ErrorPhone String No 1361234****,1371234****

The mobile numbers that receive status-related alerts. Separate multiple mobile numbers with commas (,).

Note
  • This parameter is available only for China site (aliyun.com) users. Only mobile numbers in the Chinese mainland are supported. Up to 10 mobile numbers can be specified.
  • International site (alibabacloud.com) users cannot receive alerts by using mobile phones, but can set alert rules for DTS tasks in the CloudMonitor console.
ErrorNotice Boolean No true

Specifies whether to monitor the task status. Valid values:

  • true: monitors the task status.
  • false: does not monitor the task status.
SynchronizationDirection String No Forward

The synchronization direction. Valid values:

  • Forward: Data is synchronized from the source database to the destination database.
  • Reverse: Data is synchronized from the destination database to the source database.
Note
  • Default value: Forward.
  • The value Reverse takes effect only if the topology of the data synchronization task is two-way synchronization.
RegionId String No cn-hangzhou

The ID of the region in which the DTS instance resides. For more information, see List of supported regions.

DedicatedClusterId String No dtscluster_atyl3b5214uk***

The ID of the DTS dedicated cluster on which the task runs.

Note If this parameter is specified, the task is scheduled to the specified DTS dedicated cluster.
FileOssUrl String No http://db-list-os-file.oss-cn-shanghai.aliyuncs.com/8e42_121852**********_79dd3aeabe2f43cdb**************

The URL of the Object Storage Service (OSS) bucket that stores the files related to the DTS task.

DataCheckConfigure String No {"fullCheckModel":1,"fullCheckRatio":20,"checkMaximumHourEnable":1,"checkMaximumHour":1,"fullCheckErrorNotice":true,"fullCheckValidFailNotice":true,"fullCheckNoticeValue":8,"incrementalCheckErrorNotice":true,"incrementalCheckValidFailNotice":true,"incrementalCheckValidFailNoticeTimes":2,"incrementalCheckValidFailNoticePeriod":1,"incrementalCheckValidFailNoticeValue":1,"incrementalCheckDelayNotice":true,"incrementalCheckDelayNoticeTimes":2,"incrementalCheckDelayNoticePeriod":1,"incrementalCheckDelayNoticeValue":60,"fullDataCheck":true,"incrementalDataCheck":true,"dataCheckNoticePhone":"13126800****","dataCheckDbList":"{"dts":{"name":"dts","all":true}}"}

The data verification task for a data migration or synchronization instance. The value is a JSON string that indicates parameter limits or alert configurations. For more information, see DataCheckConfigure.

DisasterRecoveryJob Boolean No true

Specifies whether the instance is a disaster recovery instance.

  • true: The instance is a disaster recovery instance.
  • false: The instance is not a disaster recovery instance.

Response parameters

Parameter Type Example Description
HttpStatusCode String 200

The HTTP status code.

RequestId String 224DB9F7-3100-4899-AB9C-C938BCCB****

The ID of the request.

ErrCode String InternalError

The error code returned if the call failed.

DtsJobId String k2gm967v16f****

The ID of the data migration or synchronization task.

DtsInstanceId String dtsk2gm967v16f****

The ID of the data migration or synchronization instance.

Success String true

Indicates whether the request was successful.

ErrMessage String The request processing has failed due to some unknown error.

The error message returned if the call failed.

Examples

Sample requests

http(s)://dts.aliyuncs.com/?Action=ConfigureDtsJob
&RegionId=cn-hangzhou
&SourceEndpointInstanceType=RDS
&DestinationEndpointInstanceType=EXPRESS
&StructureInitialization=true
&DataInitialization=true
&DataSynchronization=true
&DbList={"dtstest":{"name":"dtstest","all":true}}
&JobType=SYNC
&SourceEndpointInstanceID=rm-bp1imrtn6fq7h****
&SourceEndpointEngineName=MYSQL
&SourceEndpointRegion=cn-hangzhou
&SourceEndpointUserName=dtstest
&SourceEndpointPassword=Test123456
&DestinationEndpointInstanceID=vpc-bp1opxu1zkhn00gzv****
&DestinationEndpointEngineName=MYSQL
&DestinationEndpointIP=172.16.**.***
&DestinationEndpointRegion=cn-hangzhou
&DestinationEndpointPort=3306
&DestinationEndpointUserName=dtstest
&DestinationEndpointPassword=Test123456
&DtsJobId=k2gm967v16f****
&DtsInstanceId=dtsk2gm967v16f****
&DtsJobName=ApsaraDB RDS for MySQL to self-managed MySQL database connected over Express Connect
&<Common request parameters>

Sample success responses

XML format 

HTTP/1.1 200 OK
Content-Type:application/xml

<ConfigureDtsJobResponse>
    <DtsJobId>k2gm967v16f****</DtsJobId>
    <RequestId>224DB9F7-3100-4899-AB9C-C938BCCB****</RequestId>
    <HttpStatusCode>200</HttpStatusCode>
    <DtsInstanceId>dtsk2gm967v16f****</DtsInstanceId>
    <Success>true</Success>
</ConfigureDtsJobResponse>

JSON format 

HTTP/1.1 200 OK
Content-Type:application/json

{
  "DtsJobId" : "k2gm967v16f****",
  "RequestId" : "224DB9F7-3100-4899-AB9C-C938BCCB****",
  "HttpStatusCode" : 200,
  "DtsInstanceId" : "dtsk2gm967v16f****",
  "Success" : true
}

Error codes

HttpCode Error code Error message Description
403 InvalidParameter.KafkaBrokerInvalid kafka broker configuration must be intranet IP The error message returned because the node name of a self-managed Kafka cluster hosted on ECS is set to a hostname instead of an IP address.
403 InvalidParameter.KafkaHostInvalid kafaka host name should be intranet IP The error message returned because the Kafka hostname must be an IP address accessed over an internal network.
403 UpdateJob.OperationDenied.InitStatus The operation is not permitted due to Dts job status is init. The error message returned because the task is already started and cannot be modified. Reconfigure the task or modify the objects to be synchronized. If you reconfigure the task, the old task configurations are deleted.
403 GetMongoDbShardInfo.NoShardAddress MongoDb has not yet opened the shard connection address, please try again after opening. The error message returned because the shard connection information cannot be obtained. Check the parameter settings. Make sure that the database is an ApsaraDB for MongoDB sharded cluster instance and that an endpoint is applied for a shard node.
403 GetMongoDbShardInfo.EmptyInstances Failed to get MongoDb shard information, the return is empty. The error message returned because the shard connection information cannot be obtained. Check the parameter settings and make sure that the database is an ApsaraDB for MongoDB sharded cluster instance.
403 CheckJobFailed.ServerUnAvailable Unable to check whether the node can connect to the database because the node service is unavailable. The error message returned because the connection to specific DTS servers cannot be established. Try again. If the error persists, contact technical support.
403 DbTypeNotSupport.PolarDBRDS The current rds instance is of type PolarDB, which is not supported for the time being. Only rds instances under drds are supported. The error message returned because DTS does not support data synchronization that involves a PolarDB-X 1.0 instance with a PolarDB for MySQL database shard.
403 DbTypeNotSupport.OnlyReadRDS Synchronization is not currently supported due to latency issues with read-only DRDS instances. The error message returned because DTS does not support data synchronization that involves a PolarDB-X 1.0 instance with a read-only database shard.
403 DTS.Msg.InvalidParameter.KafkaBrokerInvalid kafka broker configuration must be intranet IP The error message returned because the node name of a self-managed Kafka cluster hosted on ECS is set to a hostname instead of an IP address.
403 DTS.Msg.InvalidParameter.KafkaHostInvalid kafaka host name should be intranet IP The error message returned because the Kafka hostname must be an IP address accessed over an internal network.
403 DTS.Msg.UpdateJob.OperationDenied.InitStatus The operation is not permitted due to Dts job status is init. The error message returned because the task is already started and cannot be modified. Reconfigure the task or modify the objects to be synchronized. If you reconfigure the task, the old task configurations are deleted.
403 DTS.Msg.GetMongoDbShardInfo.NoShardAddress MongoDb has not yet opened the shard connection address, please try again after opening. The error message returned because the shard connection information cannot be obtained. Check the parameter settings. Make sure that the database is an ApsaraDB for MongoDB sharded cluster instance and that an endpoint is applied for a shard node.
403 DTS.Msg.GetMongoDbShardInfo.EmptyInstances Failed to get MongoDb shard information, the return is empty. The error message returned because the shard connection information cannot be obtained. Check the parameter settings and make sure that the database is an ApsaraDB for MongoDB sharded cluster instance.
403 DTS.Msg.CheckJobFailed.ServerUnAvailable Unable to check whether the node can connect to the database because the node service is unavailable. The error message returned because the connection to specific DTS servers cannot be established. Try again. If the error persists, contact technical support.
403 DTS.Msg.DbTypeNotSupport.PolarDBRDS The current rds instance is of type PolarDB, which is not supported for the time being. Only rds instances under drds are supported. The error message returned because DTS does not support data synchronization that involves a PolarDB-X 1.0 instance with a PolarDB for MySQL database shard.
403 DTS.Msg.DbTypeNotSupport.OnlyReadRDS Synchronization is not currently supported due to latency issues with read-only DRDS instances. The error message returned because DTS does not support data synchronization that involves a PolarDB-X 1.0 instance with a read-only database shard.
403 InvalidSecurityToken.Expired Specified SecurityToken is expired. The error message returned because the signature expired. Use a new signature.
400 Throttling.User Request was denied due to user flow control. The error message returned because the number of requests exceeds the limit, and the request is rejected. Try again later.
500 ServiceUnavailable The request has failed due to a temporary failure of the server. The error message returned because the response of the server timed out or the server was unavailable. Try again. If the error persists, contact technical support.

For a list of error codes, visit the API Error Center.