Help Center/ Data Replication Service/ API Reference/ History API/ APIs V3.0/ Public API Management/ Modifying Tasks in Batches
Updated on 2026-09-07 GMT+08:00
Online Debugging
CLI Examples
View PDF
Share

Modifying Tasks in Batches

Function

This API is used to modify task names or descriptions in batches and set exception notification.

Debugging

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

Constraints

  • After the test of connections to the source and destination databases is successful, you need to call this API. Enter the source and destination database information according to the example. Otherwise, errors may occur in subsequent tasks.
  • This API can be invoked when the task name, description, or exception notification is modified but the task is not in the stopped or deleted state.
  • This API is invoked after connections to the source and destination databases are tested. The task must be in CONFIGURATION state. In the dual-active DR scenario, the parent task cannot call the API.
  • To ensure API performance, it is recommended that a single batch contain no more than 10 tasks.

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.

URI

PUT /v3/{project_id}/jobs/batch-modification

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 modifying tasks, which includes information about one or more tasks to be modified.

For details, see Table 4.
Table 4 Data structure description of field jobs

Parameter

Mandatory

Type

Description

job_id

Yes

String

Definition

Task ID, which uniquely identifies a data replication task and serves as the identifier for modifying the task.

Constraints

N/A

Range

N/A

Default Value

N/A

description

No

String

Definition

Task description, which provides supplementary information and remarks about the task.

Constraints

  • This parameter is mandatory when you modify the task description.

  • The value can contain 0 to 256 characters.

  • The value cannot contain the following special characters: !<>'&"

Range

N/A

Default Value

N/A

name

No

String

Definition

Task name, which is used to identify and distinguish between different data replication tasks.

Constraints

Set this parameter when you need to change the task name.

Range

N/A

Default Value

N/A

alarm_notify

No

Object

Definition

Alarm notification method for task exceptions.

For details, see Table 5.

task_type

No

String

Definition

Task mode, which specifies the execution mode of the data replication task.

Constraints

This parameter can be modified only for MySQL-to-TaurusDB synchronization tasks in the configuring or incremental state.

Range

  • FULL_TRANS: Full migration. Only historical data is migrated.
  • INCR_TRANS: Incremental migration. Only data changes are synchronized.
  • FULL_INCR_TRANS: Full+incremental migration. Historical data is migrated first, and then incremental data is continuously synchronized.

Default Value

N/A

source_endpoint

No

Object

Definition

Source database connection information. This parameter is mandatory for calling the API after a connection test.

For details, see Table 7.

target_endpoint

No

Object

Definition

Destination database connection information. This parameter is mandatory for calling the API after a connection test.

For details, see Table 7.

node_type

No

String

Definition

Specification code, which determines the compute resource size of the replication instance.

Constraints

  • This parameter is mandatory for calling the API after a connection test.

  • The values supported in a specific scenario can be obtained through the API for querying available node specifications.

Range

  • micro: micro specifications
  • small: small specifications
  • medium: medium specifications
  • high: large specifications
  • xlarge: ultra-large specifications
  • 2xlarge: macro specifications

Default Value

high

engine_type

No

String

Definition

Engine type of the DRS task.

Constraints

  • This parameter is mandatory for calling the API after a connection test.

  • For details, see the engine type description.

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

net_type

No

String

Definition

Type of the network used by the task.

Constraints

This parameter is mandatory for calling the API after a connection test.

Range

  • vpn
  • vpc
  • eip

Default Value

N/A

store_db_info

No

Boolean

Definition

Whether to save the database information.

Constraints

This parameter is mandatory for calling the API after a connection test.

Range

  • true: The database information is saved.

  • false: The database information is not saved.

Default Value

N/A

is_recreate

No

Boolean

Definition

Whether the task is a rebuilding task.

Constraints

N/A

Range

  • true: rebuilding task

  • false: not a rebuilding task

Default Value

N/A

job_direction

No

String

Definition

Task direction.

Constraints

This parameter is mandatory for calling the API after a connection test.

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

is_target_readonly

No

Boolean

Definition

Whether the destination DB instance is restricted to read-only.

Constraints

N/A

Range

  • true: The destination DB instance is restricted to read-only.

  • false: The destination DB instance is not restricted to read-only.

Default Value

N/A

replace_definer

No

Boolean

Definition

Whether to migrate all Definers to the user. This parameter is available for MySQL databases.

Constraints

This parameter is mandatory for calling the API after a connection test.

Range

  • true: The Definers of all source database objects will be migrated to the user. Other users do not have permissions on database objects unless they are authorized.
  • false: The Definers of all source database objects will not be changed. You need to migrate all accounts and permissions of the source database in the next step.

Default Value

N/A

tags

No

Array of object

Definition

Tags, which are used to add identifiers to tasks for categorized management.

For details, see Table 9.

db_use_type

No

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

Default Value

N/A

product_id

No

String

Definition

Product ID, which is used to identify the product information of a yearly/monthly task.

Constraints

N/A

Range

N/A

Default Value

N/A
Table 5 Data structure description of field alarm_notify

Parameter

Mandatory

Type

Description

delay_time

No

Long

Definition

Subscription delay, that is, the delay for sending an alarm notification (unit: s).

Constraints

N/A

Range

1–3600

Default Value

0

rto_delay

No

Long

Definition

Recovery Time Objective (RTO) delay, that is, the delay threshold of the DR recovery time objective (unit: s).

Constraints

N/A

Range

1–3600

Default Value

0

rpo_delay

No

Long

Definition

Recovery Point Objective (RPO) delay, that is, the delay threshold of the DR recovery point objective (unit: s).

Constraints

N/A

Range

1–3600

Default Value

0

alarm_to_user

No

Boolean

Definition

Whether to notify users of alarms.

Constraints

N/A

Range

  • true: Users are notified.
  • false: Users are not notified.

Default Value

false

subscriptions

No

Array of objects

Definition

Receiving method and message body, which are used to configure the notification channel for alarms. A maximum of two channels can be configured.

For details, see Table 6.
Table 6 Data structure description of field subscriptions

Parameter

Mandatory

Type

Description

endpoints

No

Array of strings

Definition

List of mobile numbers or email addresses, which are used to receive alarm notifications.

Constraints

  • Use commas (,) to separate multiple mobile numbers or email addresses.
  • A maximum of 10 mobile numbers or email addresses are supported.

Range

N/A

Default Value

N/A

protocol

No

String

Definition

Receiving method, which specifies the notification channel for alarms.

Constraints

N/A

Range

  • sms: SMS message
  • email: email

Default Value

N/A
Table 7 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 for calling the API 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

Project ID of the region where the DB instance is located. 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.

To obtain this value, see Obtaining a Project ID.

Constraints

N/A

Range

N/A

Default Value

N/A

db_name

No

String

Definition

Service name. In the Oracle scenario, the corresponding parameter is serviceName.

Constraints

  • If this parameter is required, you need to manually create the corresponding database.
  • 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 for calling the API 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 for calling the API 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 for calling the API 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

For MongoDB 4.0 or later, if the cluster instance cannot obtain the IP address of the shard node, set this parameter in source_endpoint.

Constraints

N/A

Range

Sharding4.0+: MongoDB cluster 4.0 or later

Default Value

Sharding4.0+

kafka_security_config

No

Object

Definition

This parameter is only for Kafka security authentication.

For details, see:

Table 8.
Table 8 Data structure description of field kafka_security_config

Parameter

Mandatory

Type

Description

type

No

String

Definition

Security protocol. The corresponding Kafka field is security.protocol.

Constraints

This parameter is mandatory for security authentication.

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. This parameter is mandatory when the security protocol is set to SSL or SASL_SSL.

Constraints

N/A

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

N/A

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 required 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 required when two-way SSL authentication is enabled.

Range

N/A

Default Value

N/A

key_store_password

No

String

Definition

Keystore certificate password. The corresponding field for Kafka 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 field for Kafka 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 9 Data structure description of field 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

Response Parameters

Status code: 200

Table 10 Response body parameters

Parameter

Type

Description

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

results

Array of objects

Definition

Returned list of tasks that are modified in batches, which includes the modification result of each task.

For details, see Table 11.
Table 11 Data structure description of field results

Parameter

Type

Description

id

String

Definition

Task ID, which uniquely identifies a data replication task.

Constraints

N/A

Range

N/A

status

String

Definition

Status

Constraints

N/A

Range

  • success: The task is successful.
  • failed: The task fails.

error_code

String

Definition

Error code returned if the task fails.

Constraints

N/A

Range

The value is in the format of DRS.XXXXXX.

error_msg

String

Definition

Error message returned if the task fails.

Constraints

N/A

Range

N/A

Example Request

  • Changing task names of specified instances in batches 
    https://{endpoint}/v3/054ba152d480d55b2f5dc0069e7ddef0/jobs/batch-modification

{
  "jobs" : [ {
    "job_id" : "140b5236-88ad-43c8-811c-1268453jb101",
    "name" : "testName"
  } ]
}
  • Setting task exception notifications for specified instances in batches 
    https://{endpoint}/v3/054ba152d480d55b2f5dc0069e7ddef0/jobs/batch-modification

{
  "jobs" : [ {
    "job_id" : "8d0e8e36-a618-490d-8a46-8c61ac9jb502",
    "alarm_notify" : {
      "delay_time" : 0,
      "rto_delay" : 0,
      "rpo_delay" : 0,
      "alarm_to_user" : false,
      "subscriptions" : [ {
        "protocol" : "sms",
        "endpoints" : [ "150********" ]
      }, {
        "protocol" : "email",
        "endpoints" : [ "abc@huawei.com" ]
      } ]
    }
  } ]
}
  • Changing task names and descriptions of specified instances in batches 
    https://{endpoint}/v3/054ba152d480d55b2f5dc0069e7ddef0/jobs/batch-modification

{
  "jobs" : [ {
    "job_id" : "140b5236-88ad-43c8-811c-1268453jb101",
    "name" : "testName",
    "description" : "test description"
  } ]
}
  • Calling the API after the MySQL connection test 
    https://{endpoint}/v3/054ba152d480d55b2f5dc0069e7ddef0/jobs/batch-modification

{
	"jobs": [{
		"job_id": "1fded2ab-ce99-4b0e-9cc9-9ce7e17jb101",
		"name": "DRS-5646-linxiaolu",
		"source_endpoint": {
			"ip": "192.168.0.27",
			"db_port": "3306",
			"db_user": "root",
			"db_password": "********",
			"ssl_link": false,
			"db_type": "mysql",
			"project_id": "054ba152d480d55b2f5dc0069e7ddef0"
		},
		"target_endpoint": {
			"region": "cn-xianhz-1",
			"db_type": "mysql",
			"db_user": "root",
			"db_password": "********",
			"project_id": "054ba152d480d55b2f5dc0069e7ddef0",
			"inst_id": "3def1ac7f8ab4ae48d7c025339f80414in01"
		},
		"node_type": "high",
		"engine_type": "mysql",
		"store_db_info": true,
		"net_type": "eip",
                "job_direction":"up",
		"replace_definer": true
	}]
}
  • Calling the API after the connection test for the migration task from MongoDB to DDS is successful. 
    https://{endpoint}/v3/054ba152d480d55b2f5dc0069e7ddef0/jobs/batch-modification

{
	"jobs": [{
                "job_id": "741d91cf-67e8-4126-ad0f-32f6cccjb105",
		"name": "DRS-4513",
		"source_endpoint": {
			"ip": "192.168.11.231:8635,192.168.10.12:8635",
			"db_port": 0,
			"db_user": "rwuser",
			"db_password": "********",
			"ssl_link": false,
			"db_type": "mongodb",
			"project_id": "0549a6a31000d4e82fd1c00c3d6f2d76",
			"db_name": "admin"
		},
		"target_endpoint": {
			"region": "cn-xianhz-1",
			"db_type": "mongodb",
			"db_user": "rwuser",
			"db_password": "********",
			"project_id": "0549a6a31000d4e82fd1c00c3d6f2d76",
			"inst_id": "3cadd5a0ef724f55ac7fa5bcb5f4fc5fin02"
		},
		"node_type": "high",
		"engine_type": "mongodb",
		"net_type": "eip",
                "job_direction":"up",
		"store_db_info": true

	}]
}
  • Changing the synchronization mode of specified tasks in batches 
    https://{endpoint}/v3/054ba152d480d55b2f5dc0069e7ddef0/jobs/batch-modification

{
  "jobs": [
    {
      "job_id": "140b5236-88ad-43c8-811c-1268453jb101",
      "task_type": "FULL_INCR_TRANS"
    }
  ]
}

Example Response

Status code: 200

OK

{
  "results" : [ {
    "id" : "efa2bd29-8780-494f-a2ee-188b003ejb11",
    "status" : "success"
  } ],
  "count" : 1
}

Status Code

Status Code

Description

200

OK

400

Bad Request

For other statuses, see Status Code.

Error Code

For details, see Error Code.

Parent topic: Public API Management