Configures a data migration or data synchronization task.

Note For Data Transmission Task (DTS) instances that run on a DTS dedicated cluster, you must deploy them first. Then, you are allowed to purchase such an 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 task.

SourceEndpointInstanceType String Yes RDS

The source instance of this task. Valid values:

Alibaba Cloud database instance
  • RDS: ApsaraDB RDS for MySQL instance, ApsaraDB RDS for SQLServer instance, ApsaraDB RDS for PostgreSQL instance, or ApsaraDB RDS for MariaDB TX instance
  • PolarDB: PolarDB for MySQL cluster
  • POLARDBX20: PolarDB-X 2.0 instance
  • MONGODB: ApsaraDB for MongoDB instance
  • DISTRIBUTED_DMSLOGICDB: Data Management (DMS) logical database
Self-managed database
  • OTHER: self-managed database with a public IP address
  • ECS: self-managed database hosted on Elastic Compute Service (ECS)
  • 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 only use the PolarDB for Oracle cluster as a self-managed database connected over the Internet or Express Connect.
  • 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. For example, if the value of the SourceEndpointInstanceType parameter is set to

  • ECS, you must specify the ID of the ECS instance.
  • DG, you must specify the ID of the database gateway.
  • EXPRESS or CEN, you must specify the ID of the virtual private cloud (VPC) that is connected to the source instance.
Note If the value of 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 type of the source instance.

  • MYSQL: ApsaraDB RDS for MySQL instance or self-managed MySQL database
  • PolarDB: PolarDB for MySQL cluster
  • POLARDB_O: PolarDB for Oracle cluster
  • 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
Note
  • Default value: MYSQL.
  • If the 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 where 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 port number 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 a non-RAC architecture, 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 Resource Access Management (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 destination instance of the task. Valid values:

Alibaba Cloud database instance
  • RDS: ApsaraDB RDS for MySQL instance, ApsaraDB RDS for SQLServer instance, ApsaraDB RDS for PostgreSQL instance, or ApsaraDB RDS for MariaDB TX instance
  • PolarDB: PolarDB for MySQL cluster
  • POLARDBX20: PolarDB-X 2.0 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
  • Elasticsearch: Elasticsearch cluster
Self-managed database
  • OTHER: self-managed database with a public IP address
  • ECS: self-managed database hosted on ECS
  • 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 only use the PolarDB for Oracle cluster 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 only use the Message Queue for Apache Kafka instance as a self-managed database connected over ECS or Express Connect.
  • 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 source 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. For example, if the value of the DestinationEndpointInstanceType parameter is set to

  • ECS, you must specify the ID of the ECS instance.
  • DG, you must specify the ID of the database gateway.
  • EXPRESS or CEN, you must specify the ID of the VPC that is connected to the source database.
Note If the value of 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.
DestinationEndpointEngineName String No MySQL

The database type of the destination instance.

  • MySQL: ApsaraDB RDS for MySQL instance or self-managed MySQL database
  • PolarDB: PolarDB for MySQL cluster
  • POLARDB_O: PolarDB for Oracle cluster
  • 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
Note
  • Default value: MYSQL.
  • If the database type of the destination instance 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 where the destination instance resides. For more information, see List of supported regions.

Note If the destination instance is an Alibaba Cloud database instance, the 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 port number 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, or a MongoDB database, this parameter is available and required.
DestinationEndpointUserName String No dtstest

The database account of the destination database.

Note
DestinationEndpointPassword String No Test123456

The password of the destination database account.

StructureInitialization Boolean Yes true

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

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

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

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

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

  • true: performs incremental data migration or incremental data synchronization.
  • true: does not perform incremental data migration or incremental data 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 data 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 DTS task. Valid values:

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

The ID of the data migration, data synchronization, or change tracking 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, data synchronization, or change tracking 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 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 state-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 state. Valid values:

  • true: monitors the task state.
  • false: does not monitor the task state.
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 form 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 corresponding 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.

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, data synchronization, or change tracking task.

DtsInstanceId String dtsk2gm967v16f****

The ID of the data migration, data synchronization, or change tracking instance.

Success String true

Indicates whether the call is 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 host name instead of an IP address.

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