Configures a data migration, synchronization, or verification task.
- When you configure a task in the Data Transmission Service (DTS) console, you can move the pointer over Next: Save Task Settings and Precheck in the Advanced Settings step and click Preview OpenAPI parameters to view the parameters that are used to configure the task by calling an API operation.
- If you want to run a 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 cross-region DTS tasks.
Debugging
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 instance
Note
|
SourceEndpointInstanceID | String | No | rm-bp1imrtn6fq7h**** | The source instance ID. If the source instance is an Alibaba Cloud database instance, you must specify the database instance ID. 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 SourceEndpointInstanceType.
Note If SourceEndpointInstanceType is set to CEN, you must also specify the ID of the CEN instance in Reserve. For more information, see Reserve parameter. |
SourceEndpointEngineName | String | No | MYSQL | The database type of the source instance.
Note
|
SourceEndpointRegion | String | No | cn-hangzhou | The ID of the region in which the source instance resides. For more information, see 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 This parameter is valid and required only if SourceEndpointInstanceType is set to OTHER, EXPRESS, DG, or CEN. |
SourceEndpointPort | String | No | 3306 | The port number of the source instance. Note This parameter is required only if the source instance is a self-managed database. |
SourceEndpointOracleSID | String | No | testsid | The SID of the Oracle database. Note This parameter is valid and required only if SourceEndpointEngineName is set to ORACLE and the Oracle database is deployed in a non-Real Application Cluster (RAC) architecture. |
SourceEndpointDatabaseName | String | No | dtstestdatabase | The name of the database from which the objects are migrated or synchronized in the source instance. Note This parameter is valid and required only if the source instance is a PolarDB for PostgreSQL (Compatible with Oracle) cluster, a PostgreSQL database, or a MongoDB database. |
SourceEndpointUserName | String | No | dtstest | The username of the account that is used to log on to the source database. Note
|
SourceEndpointPassword | String | No | Test123456 | The password of the account that is used to log on to the source database. |
SourceEndpointOwnerID | String | No | 140692647406**** | The ID of the Alibaba Cloud account to which the source database belongs. Note You can specify this parameter to migrate or synchronize data across different Alibaba Cloud accounts. In this case, you must specify SourceEndpointRole. |
SourceEndpointRole | String | No | ram-for-dts | The name of the Resource Access Management (RAM) role configured for the Alibaba Cloud account to which the source instance belongs. Note This parameter is required if 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 DTS tasks. |
DestinationEndpointInstanceType | String | Yes | EXPRESS | The type of the destination instance. Valid values: Alibaba Cloud database instance
Note
|
DestinationEndpointInstanceID | String | No | vpc-bp1opxu1zkhn00gzv**** | The destination instance ID. If the destination instance is an Alibaba Cloud database instance, you must specify the database instance ID. 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 DestinationEndpointInstanceType.
Note If DestinationEndpointInstanceType is set to CEN, you must also specify the ID of the CEN instance in Reserve. For more information, see Reserve parameter. |
DestinationEndpointEngineName | String | No | MYSQL | The type of the destination database. Valid values:
Note
|
DestinationEndpointRegion | String | No | cn-hangzhou | The ID of the region in which the destination instance resides. For more information, see 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 This parameter is valid and required only if DestinationEndpointInstanceType is set to OTHER, EXPRESS, DG, or CEN. |
DestinationEndpointPort | String | No | 3306 | The port number of the destination instance. Note This parameter is valid and required only if the destination instance is a self-managed database. |
DestinationEndpointDataBaseName | String | No | dtstestdata | The name of the database to which the objects are migrated or synchronized in the destination instance. Note
|
DestinationEndpointUserName | String | No | dtstest | The username of the account that is used to log on to the destination database. Note
|
DestinationEndpointPassword | String | No | Test123456 | The password of the account that is used to log on to the destination database. 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 an AccessKey pair, see Create an AccessKey pair. |
DestinationEndpointOwnerID | String | No | 140692647406**** | The ID of the Alibaba Cloud account to which the destination ApsaraDB RDS for MySQL instance belongs. Note
|
DestinationEndpointRole | String | No | ram-for-dts | The name of the RAM role configured for the Alibaba Cloud account to which the destination instance belongs. Note This parameter is required if you migrate or synchronize data across Alibaba Cloud accounts. For information about the permissions and authorization methods of the RAM role, see Configure RAM authorization for cross-account DTS tasks. |
StructureInitialization | Boolean | Yes | true | Specifies whether to perform schema migration or schema synchronization. Valid values:
Note If JobType is set to CHECK, set this parameter to false. |
DataInitialization | Boolean | Yes | true | Specifies whether to perform full data migration or full data synchronization. Valid values:
Note If JobType is set to CHECK, set this parameter to false. |
DataSynchronization | Boolean | Yes | true | Specifies whether to perform incremental data migration or incremental data synchronization. Valid values:
Note If JobType is set to CHECK, set this parameter to false. |
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 CEN instance ID. For more information, see Reserve parameter. |
Checkpoint | String | No | 1610540493 | The start offset of incremental data migration or incremental data synchronization. The value is a UNIX timestamp. Unit: seconds. |
DestinationEndpointOracleSID | String | No | testsid | The SID of the Oracle database. Note This parameter is valid and required only if DestinationEndpointEngineName is set to ORACLE and the Oracle database is deployed in a non-RAC architecture. |
JobType | String | Yes | SYNC | The type of the task. Valid values:
Note If you set this parameter to MIGRATION or SYNC, you can also enable data verification in the data migration or synchronization task. |
DtsJobId | String | No | k2gm967v16f**** | The ID of the data migration or synchronization task. Note 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 can call the DescribeDtsJobs operation to query the instance ID. |
DelayPhone | String | No | 1361234****,1371234**** | The mobile phone numbers to which latency-related alerts are sent. Separate multiple mobile phone numbers with commas (,). Note
|
DelayRuleTime | Long | No | 10 | The threshold for latency alerts. Unit: seconds. The value must be an integer. You can set the threshold based on your business requirements. To prevent unstable latency caused by network and database overloads, we recommend that you set the threshold to more than 10 seconds. Note If DelayNotice is set to true, this parameter is required. |
DelayNotice | Boolean | No | true | Specifies whether to monitor task latency. Valid values:
|
ErrorPhone | String | No | 1361234****,1371234**** | The mobile phone numbers to which status-related alerts are sent. Separate multiple mobile phone numbers with commas (,). Note
|
ErrorNotice | Boolean | No | true | Specifies whether to monitor task status. Valid values:
|
SynchronizationDirection | String | No | Forward | The synchronization direction. Valid values:
Note
|
RegionId | String | No | cn-hangzhou | The ID of the region in which the DTS instance resides. For more information, see 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 parameters for data verification, including the configurations for data verification and alerts. The value is a JSON string. For more information, see DataCheckConfigure parameter description. |
DisasterRecoveryJob | Boolean | No | true | Specifies whether the instance is a disaster recovery instance. Valid values:
|
SourceEndpointVSwitchID | String | No | vsw-bp10df3mxae6lpmku**** | The ID of the vSwitch that is used for data shipping. |
DtsBisLabel | String | No | normal | The environment tag of the DTS instance. Valid values:
|
SrcCaCertificateOssUrl | String | No | **** | The path of the certificate authority (CA) certificate that is used if the connection to the source database is encrypted by using SSL. Note This feature is not supported. Do not specify this parameter. |
SrcCaCertificatePassword | String | No | **** | The key of the CA certificate that is used if the connection to the source database is encrypted by using SSL. Note This feature is not supported. Do not specify this parameter. |
DestCaCertificateOssUrl | String | No | **** | The path of the CA certificate that is used if the connection to the destination database is encrypted by using SSL. Note This feature is not supported. Do not specify this parameter. |
DestCaCertificatePassword | String | No | **** | The key of the CA certificate that is used if the connection to the destination database is encrypted by using SSL. Note This feature is not supported. Do not specify this parameter. |
MinDu | double | No | 1 | The minimum number of DTS Units (DUs). Note This parameter is supported only for serverless instances. |
MaxDu | double | No | 16 | The maximum number of DUs. Note This parameter is supported only for serverless instances. |
SrcClientCertOssUrl | String | No | **** | The path to the client certificate that is used if the connection to the source database is encrypted by using SSL. Note This feature is not supported. Do not specify this parameter. |
SrcClientKeyOssUrl | String | No | **** | The path to the private key of the client certificate that is used if the connection to the source database is encrypted by using SSL. Note This feature is not supported. Do not specify this parameter. |
SrcClientPassword | String | No | **** | The password of the private key of the client certificate that is used if the connection to the source database is encrypted by using SSL. Note This feature is not supported. Do not specify this parameter. |
DestClientCertOssUrl | String | No | **** | The path to the client certificate that is used if the connection to the destination database is encrypted by using SSL. Note This feature is not supported. Do not specify this parameter. |
DestClientKeyOssUrl | String | No | **** | The path to the private key of the client certificate that is used if the connection to the destination database is encrypted by using SSL. Note This feature is not supported. Do not specify this parameter. |
DestClientPassword | String | No | **** | The password of the private key of the client certificate that is used if the connection to the destination database is encrypted by using SSL. Note This feature is not supported. Do not specify this parameter. |
ResourceGroupId | String | No | rg-acfmzawhxxc**** | The resource group ID. |
Response parameters
Parameter |
Type |
Example |
Description |
HttpStatusCode | String | 200 | The returned HTTP status codes. |
RequestId | String | 224DB9F7-3100-4899-AB9C-C938BCCB**** | The request ID. |
ErrCode | String | InternalError | The error code returned if the request 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 is successful. |
ErrMessage | String | The request processing has failed due to some unknown error. | The error message returned if the request 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 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 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 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 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 shard 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 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. | 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. | 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 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 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 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 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 shard 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 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. | 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. | 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 signature expired. Use a new signature. |
400 | Throttling.User | Request was denied due to user flow control. | The number of requests exceeded the limit, and the request was rejected. Try again later. |
500 | ServiceUnavailable | The request has failed due to a temporary failure of the server. | 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, see Service error codes.