Help Center/ Data Replication Service/ API Reference/ History API/ APIs V3.0/ Public API Management/ Creating Tasks in Batches

Updated on 2026-09-07 GMT+08:00

View PDF

Creating Tasks in Batches

Function

This API is used to create real-time migration, real-time synchronization, real-time DR, and verification tasks in batches based on different request parameters.

Debugging

You can debug the API in API Explorer to support automatic authentication. API Explorer can automatically generate and debug example SDK code.

Authorization Information

Each account has all the permissions required to call all APIs, but IAM users must be assigned the required permissions. For details about the required permissions, see Permissions and Supported Actions.

Constraints

To ensure API performance, it is recommended that a single batch contain no more than 10 tasks.

URI

POST /v3/{project_id}/jobs/batch-creation

**Table 1** URI parameters
Parameter	Mandatory	Type	Description
project_id	Yes	String	Definition Project ID of a tenant in a region. For details about how to obtain the project ID, see Obtaining a Project ID. Constraints N/A Range N/A Default Value N/A

Request Parameters

**Table 2** Request header parameters
Parameter	Mandatory	Type	Description
Content-Type	Yes	String	Definition MIME type of the request body. Use the default value application/json. For APIs used to upload objects or images, the value varies depending on the flow type. Constraints N/A Range application/json Default Value application/json
X-Auth-Token	Yes	String	Definition User token obtained from IAM. It is a response to the API for obtaining a user token. This API is the only one that does not require authentication. The token is the value of X-Subject-Token in the response header. Constraints N/A Range N/A Default Value N/A
X-Language	No	String	Definition Request language type. Constraints N/A Range en-us: English zh-cn: Chinese Default Value en-us

**Table 3** Request body parameters
Parameter	Mandatory	Type	Description
jobs	Yes	Array of objects	Definition Request body list for creating tasks. For details, see Table 4.

**Table 4** Data structure description of field **jobs**
Parameter	Mandatory	Type	Description
name	Yes	String	Definition Task name. Constraints The value must start with a letter. Only letters (case-insensitive), digits, hyphens (-), and underscores (_) are allowed. Range The value can contain 4 to 50 characters. Default Value N/A
db_use_type	Yes	String	Definition Service scenario type of the migration task. Constraints N/A Range migration: real-time migration sync: real-time synchronization cloudDataGuard: real-time disaster recovery verify: verification task Default Value N/A
engine_type	Yes	String	Definition Engine type of the DRS task. Constraints N/A Range mysql: migration and synchronization from MySQL to MySQL mongodb: migration and synchronization from MongoDB to DDS cloudDataGuard-mysql: DR from MySQL to MySQL gaussdbv5: GaussDB synchronization mysql-to-kafka: synchronization from MySQL to Kafka taurus-to-kafka: synchronization from TaurusDB to Kafka gaussdbv5ha-to-kafka: synchronization from GaussDB Centralized to Kafka postgresql: synchronization from PostgreSQL to PostgreSQL oracle-to-gaussdbv5: synchronization from Oracle to GaussDB Distributed oracle-to-gaussdbv5ha: synchronization from Oracle to GaussDB Centralized gaussdbv5-to-oracle: synchronization from GaussDB Distributed to Oracle gaussdbv5ha-to-oracle: synchronization from GaussDB Centralized to Oracle gaussdbv5-to-kafka: synchronization from GaussDB Distributed to Kafka For details, see Engine Types. Default Value N/A
job_direction	Yes	String	Definition Migration direction of the task. Constraints N/A Range up: to-the-cloud scenarios and DR scenarios where the current cloud is the standby down: out-of-cloud scenarios and DR scenarios where the current cloud is the active non-dbs: between self-built databases Default Value N/A
bind_eip	No	Boolean	Definition Whether to bind an EIP. Constraints This parameter is mandatory and set to true when the network type is EIP. Range true: An EIP is bound. false: No EIP is bound. Default Value false
customize_sutnet_id	Yes	String	Definition The ID of the subnet where the DRS instance is located, which corresponds to the network ID of the subnet created in the VPC of the destination database. Constraints N/A Range N/A Default Value N/A
product_id	No	String	Definition Product ID. Constraints N/A Range N/A Default Value N/A
is_target_readonly	No	Boolean	Definition Whether the destination instance is restricted to read-only. Constraints This parameter is valid only when job_direction is set to up during MySQL migration and DR. In the DR scenario, this parameter is mandatory and set to true if the current cloud is the standby in single-active DR. If this parameter is not specified, the default value is true. Range true: The instance is restricted to read-only. false: The instance is not restricted to read-only. Default Value N/A
net_type	Yes	String	Definition Type of the network used by the task. Constraints The VPC network cannot be selected in the DR scenario. Range vpn vpc eip Default Value N/A
node_type	Yes	String	Definition Specification code of the DRS instance, which determines the compute resource size of the replication instance. Constraints N/A Range micro: micro specifications small: small specifications medium: medium specifications high: large specifications xlarge: ultra-large specifications 2xlarge: macro specifications The values supported in a specific scenario can be obtained through the API for querying available node specifications. Default Value N/A
node_num	No	Integer	Definition The number of nodes. For a MongoDB database, this parameter indicates the number of source shards. This parameter is mandatory when the source database is a cluster. For MySQL dual-active DR, the default value is 2. Constraints N/A Range 1–32. For MySQL dual-active DR, the default value is 2. Default Value N/A
source_endpoint	Yes	Object	Definition Source database information. For details, see Table 5.
target_endpoint	Yes	Object	Definition Destination database information. For details, see Table 5.
task_type	Yes	String	Definition Task mode, which specifies the execution mode of the data replication task. Constraints In the single-active DR scenario, only FULL_INCR_TRANS is available. Range FULL_TRANS: Full migration. Only historical data is migrated. FULL_INCR_TRANS: Full+incremental migration. Historical data is migrated first, and then incremental data is continuously synchronized. INCR_TRANS: Incremental migration. Only data changes are synchronized. Default Value FULL_INCR_TRANS
tags	No	Array of object	Definition Tag information list. For details, see Table 7. Constraints A maximum of 20 tags can be added.
description	No	String	Definition Task description. Constraints The task description can contain a maximum of 256 characters and cannot contain the following special characters: !<>'&"\ Range N/A Default Value N/A
multi_write	No	Boolean	Definition Whether the DR type is dual-active. Constraints This parameter is mandatory when db_use_type is set to cloudDataGuard. If the DR type is dual-active, the value of multi_write is true. Otherwise, the value is false. If db_use_type is set to other values, this parameter is optional. Range true: dual-active DR false: not dual-active DR Default Value false
sys_tags	No	Array of object	Definition Enterprise project tag list. Constraints If this parameter is left blank, default is used. The key must be _sys_enterprise_project_id, and the value is the enterprise project ID. Only one enterprise project is allowed. For details, see Table 7.
expired_days	No	String	Definition Number of days after which an abnormal task automatically stops. Constraints N/A Range 14–100 Default Value 14
master_az	No	String	Definition AZ where the primary task is located. You can obtain the value by calling the API for querying AZs where flavors are not sold out. If this parameter is not specified, the task is a single-AZ task by default. Constraints This parameter takes effect when both master_az and slave_az are specified. MySQL and gaussdbv5ha-to-kafka scenarios are supported. Range N/A Default Value N/A
slave_az	No	String	Definition AZ where the standby task is located. You can obtain the value by calling the API for querying AZs where flavors are not sold out. If this parameter is not specified, the task is a single-AZ task by default. Constraints This parameter takes effect when both master_az and slave_az are specified. MySQL and gaussdbv5ha-to-kafka scenarios are supported. Range N/A Default Value N/A
charging_mode	No	String	Definition Billing mode of the task. Constraints If db_use_type is set to migration, yearly/monthly billing is not supported. The engine_type can be set to mysql, cloudDataGuard-mysql, postgresql, or gaussdbv5ha-to-kafka. Range period: yearly/monthly billing on_demand: pay-per-use billing Default Value on_demand
period_order	No	Object	Definition Yearly/Monthly information. For details, see Table 8. Constraints This parameter is mandatory when charging_mode is set to period.
public_ip_list	No	Array of objects	Definition Information about a specified EIP. For details, see Table 9.
is_open_fast_clean	No	Boolean	Definition Whether to enable binlog clearing for RDS for MySQL or RDS for MariaDB. Constraints N/A Range true: Enable binlog clearing. false: Disable binlog clearing. Default Value false

**Table 5** Data structure description of fields **source_endpoint** and **target_endpoint**
Parameter	Mandatory	Type	Description
db_type	No	String	Definition Database type, which indicates the DB engine type of the source or destination database. Constraints This parameter is mandatory when an API is invoked to modify a task after a connection test. Range mysql: MySQL mongodb: MongoDB gaussdbv5: GaussDB Distributed taurus: TaurusDB gaussdbv5ha: GaussDB Centralized kafka: Kafka postgresql: PostgreSQL oracle: Oracle Default Value N/A
az_code	No	String	Definition Code of the AZ where the database is located. Constraints N/A Range N/A Default Value N/A
region	No	String	Definition Region where the DB instance is located. This parameter is mandatory when the database is a cloud instance, for example, an RDS instance. Constraints In the DR scenario, this parameter is mandatory in source_endpoint when job_direction is set to down. In the DR scenario, this parameter is mandatory in target_endpoint when job_direction is set to up. Range N/A Default Value N/A
inst_id	No	String	Definition DB instance ID. This parameter is mandatory when the database is a cloud instance, for example, an RDS instance. Constraints In the DR scenario, this parameter is mandatory in source_endpoint when job_direction is set to down. In the DR scenario, this parameter is mandatory in target_endpoint when job_direction is set to up. Range N/A Default Value N/A
vpc_id	No	String	Definition ID of the Virtual Private Cloud (VPC) where the database is located. Constraints N/A Range N/A Default Value N/A
subnet_id	No	String	Definition ID of the subnet where the database is located. Constraints N/A Range N/A Default Value N/A
security_group_id	No	String	Definition ID of the security group to which the database belongs. Constraints N/A Range N/A Default Value N/A
project_id	No	String	Definition If the database is a cloud DB instance, set this parameter to the project ID in the region where the DB instance is located. Otherwise, set this parameter to the project ID in the region where the current task is located. For details about how to obtain the project ID, see Obtaining a Project ID. Constraints N/A Range N/A Default Value N/A
db_name	No	String	Definition The service name. This parameter is mandatory when the source database is an Oracle database. Constraints The value cannot exceed 128 characters. The value cannot contain the following special characters: !<>'&"\ Range N/A Default Value N/A
db_password	No	String	Definition Database password, which is used for authentication when the database is connected. Constraints This parameter is mandatory when an API is invoked to modify a task after a connection test, except for engines that do not require a password. Range N/A Default Value N/A
db_port	No	Integer	Definition Database port number, which is used to specify the service port for connecting to the database. Constraints The value is an integer ranging from 1 to 65535. Range N/A Default Value N/A
db_user	No	String	Definition Username used to connect to the database. Constraints This parameter is mandatory when an API is invoked to modify a task after a connection test, except for engines that do not require a username. Range N/A Default Value N/A
inst_name	No	String	Definition RDS instance name. Constraints N/A Range N/A Default Value N/A
ip	No	String	Definition Database IP address. This parameter is mandatory when an API is invoked to modify a task after a connection test. Constraints N/A Range N/A Default Value N/A
mongo_ha_mode	No	String	Definition MongoDB HA mode. Constraints N/A Range N/A Default Value N/A
safe_mode	No	Integer	Definition Running mode of an MRS cluster. Constraints N/A Range 0: normal cluster 1: security cluster Default Value N/A
ssl_cert_password	No	String	Definition SSL certificate password. The certificate file name extension is .p12. Constraints N/A Range N/A Default Value N/A
ssl_cert_check_sum	No	String	Definition The checksum value of the SSL certificate, which is used for backend verification. This parameter is mandatory for secure connection to the source database. Constraints N/A Range N/A Default Value N/A
ssl_cert_key	No	String	Definition SSL certificate content, which is encrypted using Base64. Constraints N/A Range N/A Default Value N/A
ssl_cert_name	No	String	Definition SSL certificate name. Constraints N/A Range N/A Default Value N/A
ssl_link	No	Boolean	Definition Whether to use SSL connection. This parameter specifies whether to enable SSL encrypted transmission for database connections. Constraints N/A Range true: SSL connection is used. false: SSL connection is not used. Default Value N/A
topic	No	String	Definition Kafka topic name. Constraints N/A Range N/A Default Value N/A
cluster_mode	No	String	Definition MongoDB cluster mode. This parameter must be specified in source_endpoint if the cluster instance cannot obtain the IP address of the shard node. Constraints N/A Range Sharding4.0+: MongoDB cluster 4.0 or later Default Value Sharding4.0+
kafka_security_config	No	Object	Definition Kafka security authentication configuration. This parameter is not required for non-security authentication. For details, see Table 6.

**Table 6** Data structure description of field **kafka_security_config**
Parameter	Mandatory	Type	Description
type	No	String	Definition Security protocol. This parameter is mandatory for security authentication. The corresponding Kafka field is security.protocol. Constraints N/A Range PLAINTEXT: No security authentication mode is available. You only need to enter an IP address and a port number. SASL_PLAINTEXT: The SASL mechanism is used to connect to Kafka, and you need to configure SASL parameters. SSL: SSL encryption is used to connect to Kafka, and you need to configure SSL parameters. SASL_SSL: Both SASL and SSL authentication modes are used. You need to configure SSL and SASL parameters. Default Value N/A
trust_store_key_name	No	String	Definition Certificate name. Constraints This parameter is mandatory when the security protocol is set to SSL or SASL_SSL. Range N/A Default Value N/A
trust_store_key	No	String	Definition Base64-encoded value of the security certificate. Constraints This parameter is mandatory when the security protocol is set to SSL or SASL_SSL. Range N/A Default Value N/A
trust_store_password	No	String	Definition Certificate password. Constraints This parameter is mandatory when a password is set for the certificate. Range N/A Default Value N/A
endpoint_algorithm	No	String	Definition Host name endpoint identification algorithm, which specifies the endpoint identification algorithm for verifying the server host name using the server certificate. If this parameter is left blank, host name verification is disabled. The corresponding field for Kafka is ssl.endpoint.identification.algorithm. Constraints N/A Range N/A Default Value N/A
sasl_mechanism	No	String	Definition SASL mechanism used for client connection. The corresponding Kafka field is sasl.mechanism. Constraints This parameter is mandatory when the authentication type is SASL_PLAINTEXT or SASL_SSL. Range GSSAPI PLAIN SCRAM-SHA-256 SCRAM-SHA-512 Default Value N/A
delegation_tokens	No	Boolean	Definition Whether to use delegation tokens for authentication. Constraints This parameter is valid only when the security protocol is set to SASL_SSL or SASL_PLAINTEXT and the SASL mechanism is set to SCRAM-SHA-256 or SCRAM-SHA-512. Range true: Delegation tokens are used for authentication. false: Delegation tokens are not used for authentication. Default Value N/A
enable_key_store	No	Boolean	Definition Whether to enable two-way SSL authentication. Constraints N/A Range true: Two-way SSL authentication is enabled. false: Two-way SSL authentication is disabled. Default Value N/A
key_store_key	No	String	Definition Keystore certificate. Constraints This parameter is mandatory when two-way SSL authentication is enabled. Range N/A Default Value N/A
key_store_key_name	No	String	Definition Keystore certificate name. Constraints This parameter is mandatory when two-way SSL authentication is enabled. Range N/A Default Value N/A
key_store_password	No	String	Definition Keystore certificate password. This parameter is mandatory when a password is set for the certificate. The corresponding Kafka field is ssl.keystore.password. Constraints This parameter is mandatory when a password is set for the certificate. Range N/A Default Value N/A
set_private_key_password	No	Boolean	Definition Whether to set the keystore private key password. Constraints N/A Range true: The keystore private key password is set. false: The keystore private key password is not set. Default Value false
key_password	No	String	Definition Keystore private key password. The corresponding Kafka field is ssl.key.password. Constraints This parameter is mandatory when two-way SSL authentication is enabled and set_private_key_password is set to true. Range N/A Default Value N/A

**Table 7** Data structure description of fields **tags** and **sys_tags**
Parameter	Mandatory	Type	Description
key	No	String	Definition Tag key. Constraints A tag key can contain a maximum of 36 characters. Only letters, digits, underscores (_), and hyphens (-) are allowed. Set this parameter when you need to modify a tag. Range N/A Default Value N/A
value	No	String	Definition Tag value. Constraints A tag key can contain a maximum of 43 characters. Only letters, digits, underscores (_), and hyphens (-) are allowed. Set this parameter when you need to modify a tag. Range N/A Default Value N/A

**Table 8** Data structure description of field **period_order**
Parameter	Mandatory	Type	Description
period_type	No	Integer	Definition Subscription period type. Constraints This parameter is valid and mandatory only when charging_mode is set to period. Range 2: indicates that the service is subscribed by month. 3: indicates that the service is subscribed by year. Default Value N/A
period_num	No	Integer	Definition Number of subscription periods. Constraints This parameter is valid and mandatory only when charging_mode is set to period. The value of period_num must be a positive integer. Range If period_type is set to 2 (month), the value ranges from 1 to 9. If period_type is set to 3 (year), the value ranges from 1 to 3. Default Value N/A
is_auto_renew	No	Integer	Definition Whether auto renewal is enabled. Constraints This parameter is valid only when charging_mode is set to period. If this parameter is not specified, automatic renewal is disabled by default. Range 0: The subscription is not automatically renewed. 1: The subscription is automatically renewed. Default Value N/A

**Table 9** Data structure description of field **public_ip_list**
Parameter	Mandatory	Type	Description
id	Yes	String	Definition ID of a specified EIP. Constraints N/A Range N/A Default Value N/A
public_ip	Yes	String	Definition EIP. Constraints N/A Range N/A Default Value N/A
type	Yes	String	Definition Type of the task with the EIP bound. Constraints In a primary/standby task, master indicates the primary task, and slave indicates the standby task. In other cases, the value is fixed to master. Range master: primary task slave: standby task Default Value N/A

Response Parameters

Status code: 202

**Table 10** Response body parameters
Parameter	Type	Description
results	Array of objects	Definition Response body set for creating tasks in batches. For details, see Table 11.
count	Integer	Definition Total number of returned task records, which is consistent with the length of the results array. Constraints N/A Range N/A

**Table 11** Data structure description of field **results**
Parameter	Type	Description
id	String	Definition Task ID, which uniquely identifies a data replication task and serves as the identifier for operations such as query, modification, and deletion. Constraints N/A Range N/A
child_ids	Array of strings	Definition Subtask ID set. This parameter is returned when there are subtasks. Constraints N/A Range N/A
name	String	Definition Task name. Constraints N/A Range N/A
status	String	Definition Task status. Constraints N/A Range CREATING: The task is being created. CREATE_FAILED: The task failed to be created. CONFIGURATION: The task is being configured. WAITING_FOR_START: The task is waiting to be started. RELEASE_RESOURCE_COMPLETE: The task is stopped. DELETED: The task is deleted. INCRE_TRANSFER_STARTED: The incremental migration is in progress. INCRE_TRANSFER_FAILED: The incremental migration failed. FULL_TRANSFER_STARTED: The full migration is in progress. FULL_TRANSFER_COMPLETE: The full migration is complete. PAUSING: The task is paused. FULL_TRANSFER_FAILED: The full migration failed.
create_time	String	Definition Creation time, in timestamp format. Constraints N/A Range N/A
error_code	String	Definition Error code returned if the task fails. Constraints N/A Range N/A
error_msg	String	Definition Error message returned if the task fails. Constraints N/A Range N/A

Example Request

Creating to-the-cloud MySQL migration tasks in batches, in which task_type is set to FULL_INCR_TRANS, and net_type is set to eip

https://{endpoint}/v3/054ba152d480d55b2f5dc0069e7ddef0/jobs/batch-creation

{
  "jobs" : [ {
    "name" : "DRS-9228",
    "node_type" : "high",
    "engine_type" : "mysql",
    "net_type" : "eip",
    "job_direction" : "up",
    "db_use_type" : "migration",
    "task_type" : "FULL_INCR_TRANS",
    "customize_sutnet_id" : "352ad828-3467-4f03-987a-c55a5a9dd417",
    "source_endpoint" : {
      "db_type" : "mysql"
    },
    "target_endpoint" : {
      "region" : "cn-xianhz-1",
      "db_type" : "mysql",
      "inst_id" : "e05a3679efe241d8b5dee80b17c1a863in01"
    },
    "is_target_readonly" : false,
    "bind_eip" : true
  } ]
}

Creating real-time MySQL DR tasks in batches (current cloud as standby), in which net_type is set to eip

https://{endpoint}/v3/054ba152d480d55b2f5dc0069e7ddef0/jobs/batch-creation

{
  "jobs" : [ {
    "name" : "DRS-api-test",
    "engine_type" : "cloudDataGuard-mysql",
    "net_type" : "eip",
    "node_type" : "high",
    "job_direction" : "up",
    "source_endpoint" : {
      "db_type" : "mysql"
    },
    "target_endpoint" : {
      "region" : "cn-xianhz-1",
      "db_type" : "mysql",
      "inst_id" : "e05a3679efe241d8b5dee80b17c1a863in01",
      "project_id" : "054ba152d480d55b2f5dc0069e7ddef0"
    },
    "is_target_readonly" : true,
    "bind_eip" : true,
    "db_use_type" : "cloudDataGuard",
    "task_type" : "FULL_INCR_TRANS",
    "customize_sutnet_id" : "352ad828-3467-4f03-987a-c55a5a9dd417",
    "multi_write" : false
  } ]
}

Creating to-the-cloud DDS replica set migration tasks in batches, in which task_type is set to FULL_INCR_TRANS, and net_type is set to eip

https://{endpoint}/v3/054ba152d480d55b2f5dc0069e7ddef0/jobs/batch-creation

{
  "jobs" : [ {
    "name" : "DRS-3371-linxiaolu",
    "node_type" : "high",
    "engine_type" : "mongodb",
    "net_type" : "eip",
    "job_direction" : "up",
    "db_use_type" : "migration",
    "task_type" : "FULL_INCR_TRANS",
    "customize_sutnet_id" : "faf513f3-7a88-4a5c-bec7-238699c29c17",
    "source_endpoint" : {
      "db_type" : "mongodb"
    },
    "target_endpoint" : {
      "region" : "cn-xianhz-1",
      "db_type" : "mongodb",
      "inst_id" : "3cadd5a0ef724f55ac7fa5bcb5f4fc5fin02"
    },
    "bind_eip" : true
  } ]
}

Creating a MySQL primary/standby synchronization task, in which task_type is set to FULL_INCR_TRANS, and net_type is set to eip

https://{endpoint}/v3/054ba152d480d55b2f5dc0069e7ddef0/jobs/batch-creation

{
  "jobs" : [ {
    "name" : "DRS-linxiaolu-test3",
    "engine_type" : "mysql",
    "net_type" : "eip",
    "node_type" : "high",
    "job_direction" : "up",
    "source_endpoint" : {
      "db_type" : "mysql"
    },
    "target_endpoint" : {
      "region" : "cn-xianhz-1",
      "db_type" : "mysql",
      "inst_id" : "64e8d7a31afa476ca85609a17af83765in01",
      "project_id" : "054ba152d480d55b2f5dc0069e7ddef0"
    },
    "bind_eip" : true,
    "db_use_type" : "sync",
    "task_type" : "FULL_INCR_TRANS",
    "customize_sutnet_id" : "0cf77cfb-3785-4065-a9c4-74b7bb2df071",
    "master_az" : "az2xahz",
    "slave_az" : "az3xahz"
  } ]
}

Example Response

Status code: 202

Accepted

{
  "results" : [ {
    "id" : "e11eaf8f-71ef-4fad-8890-aed7572ajb11",
    "name" : "DRS-9228",
    "status" : "CREATING",
    "create_time" : "1599188556112"
  } ],
  "count" : 1
}

Status Code

Status Code	Description
202	Accepted
400	Bad Request

For other statuses, see Status Code.

Error Code

For details, see Error Code.

Parent topic: Public API Management

Previous topic: Public API Management

Next topic: Testing Connections in Batches