Help Center/ Data Replication Service/ API Reference/ APIs V3.0 (Deprecated)/ Public API Management/ Modifying Tasks in Batches

Updated on 2024-10-25 GMT+08:00

Online Debugging

CLI Examples

View PDF

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.
You can call a maximum of 10 APIs in batches.

URI

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

**Table 1** Path parameters
Parameter	Mandatory	Type	Description
project_id	Yes	String	Project ID of a tenant in a region For details about how to obtain the project ID, see Obtaining a Project ID.

Request Parameters

**Table 2** Request header parameters
Parameter	Mandatory	Type	Description
Content-Type	Yes	String	The content type. The default value is application/json.
X-Auth-Token	Yes	String	User token obtained from IAM.
X-Language	No	String	Request language type Default value: en-us Values: en-us zh-cn

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

**Table 4** Data structure description of field **jobs**
Parameter	Mandatory	Type	Description
job_id	Yes	String	Task ID.
description	No	String	Task description. This parameter is mandatory when you modify the task description. Minimum length: 0 character Maximum length: 256
name	No	String	Task name. Set this parameter when you need to change the task name.
alarm_notify	No	Object	Set exception notification. For details, see Table 5.
task_type	No	String	Task mode. Values: FULL_TRANS: full migration INCR_TRANS: incremental migration FULL_INCR_TRANS: full+incremental migration NOTE: This parameter can be modified only for MySQL-to-GaussDB(for MySQL) synchronization tasks in the configuring or incremental state.
source_endpoint	No	Object	Source database information. This parameter is mandatory for calling the API after the connection test. For details, see Table 7.
target_endpoint	No	Object	Destination database information. This parameter is mandatory for calling the API after the connection test. For details, see Table 7.
node_type	No	String	Specifications. Values: micro: minimum specifications. small: small specifications. medium: medium specifications. high: large specifications. xlarge: ultra-large specifications. 2xlarge: maximum specifications. The values supported in a specific scenario can be obtained through the API for Querying Available Node Specifications.
engine_type	No	String	Engine type of a DRS task. This parameter is mandatory when this API is invoked to modify a task after the connection test. Values: mysql: used for migration and synchronization from MySQL to MySQL mongodb: used for migration from MongoDB to DDS cloudDataGuard-mysql: used for DR from MySQL to MySQL gaussdbv5: used for GaussDB synchronization mysql-to-kafka: used for synchronization from MySQL to Kafka taurus-to-kafka: used for synchronization from GaussDB(for MySQL) to Kafka gaussdbv5ha-to-kafka: used for synchronization from GaussDB primary/standby to Kafka postgresql: used for synchronization from PostgreSQL to PostgreSQL For details, see Engine Types.
net_type	No	String	Network type. This parameter is mandatory after the connection test. Values: vpn vpc eip
store_db_info	No	Boolean	Whether to save the database information. This parameter is mandatory when the API is called after the connection test.
is_recreate	No	Boolean	Whether the task is a rebuilding task.
job_direction	No	String	Task direction. This parameter is mandatory after the connection test. Values: up: to-the-cloud scenarios and the current cloud is the standby cloud in the DR. down: out-of-cloud scenarios and the current cloud is the active cloud in the DR. non-dbs: self-built databases.
is_target_readonly	No	Boolean	Whether the destination DB instance can be read-only.
replace_definer	No	Boolean	Whether to migrate all Definers to the user. MySQL databases support this setting. This parameter is mandatory when this API is invoked to modify a task after the connection test. Values: 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.
tags	No	Array of object	Specifies the tag information. For details, see Table 9.
db_use_type	No	String	Migration type. Values: migration: real-time migration. sync: real-time synchronization. cloudDataGuard: real-time disaster recovery.
product_id	No	String	Product ID.

**Table 5** Data structure description of field **alarm_notify**
Parameter	Mandatory	Type	Description
delay_time	No	Long	Subscription delay, in seconds. Minimum value: 1 Maximum value: 3600 Default value: 0
rto_delay	No	Long	Recovery Time Objective (RTO) delay, in seconds. Minimum value: 1 Maximum value: 3600 Default value: 0
rpo_delay	No	Long	Recovery Point Objective (RPO) delay, in seconds. Minimum value: 1 Maximum value: 3600 Default value: 0
alarm_to_user	No	Boolean	Whether to notify users of alarms. The default value is false.
subscriptions	No	Array of objects	Receiving method and message body. Up to two receiving modes and message bodies are supported. For details, see Table 6.

**Table 6** Data structure description of field **subscriptions**
Parameter	Mandatory	Type	Description
endpoints	No	Array of strings	List of mobile numbers or email addresses. Use commas (,) to separate multiple mobile numbers or email addresses. Up to 10 mobile numbers or email addresses are supported.
protocol	No	String	Receiving method. Values: sms: SMS message email: email.

**Table 7** Data structure description of fields **source_endpoint** and **target_endpoint**
Parameter	Mandatory	Type	Description
db_type	No	String	Database type. This parameter is mandatory when this API is invoked to modify a task after the connection test. Values: mysql: MySQL mongodb: MongoDB gaussdbv5: GaussDB Distributed taurus: GaussDB(for MySQL) gaussdbv5ha: GaussDB Primary/Standby kafka: Kafka postgresql: PostgreSQL
az_code	No	String	Code of the AZ where the database is located.
region	No	String	Region where the DB instance is located. This parameter is mandatory when the database is a cloud instance, for example, an RDS instance. In DR scenarios, if job_direction is set to down, this parameter is mandatory in source_endpoint. If job_direction is set to up, this parameter is mandatory in target_endpoint.
inst_id	No	String	ID of the DB instance. This parameter is mandatory when the database is a cloud instance, for example, an RDS instance. In DR scenarios, if job_direction is set to down, this parameter is mandatory in source_endpoint. If job_direction is set to up, this parameter is mandatory in target_endpoint.
vpc_id	No	String	ID of the VPC where the database is located.
subnet_id	No	String	ID of the subnet where the database is located.
security_group_id	No	String	ID of the security group to which the database belongs.
project_id	No	String	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, see Obtaining a Project ID.
db_name	No	String	The service name. This parameter is mandatory when the source database is an Oracle database. If this parameter is required, you need to manually create the corresponding database. The database name can be a maximum of 128 characters in length and cannot contain the following special characters: !<>&'\"
db_password	No	String	Database password. NOTE: This parameter is mandatory when this API is invoked to modify a task after the connection test of other engines except the engine that does not require a password.
db_port	No	Integer	Database port. The value is an integer ranging from 1 to 65535.
db_user	No	String	Database user. NOTE: This parameter is mandatory when this API is invoked to modify a task after the connection test of other engines except the engine that does not require a username.
inst_name	No	String	RDS instance name.
ip	No	String	Database IP address. NOTE: This parameter is mandatory when this API is invoked to modify a task after the connection test.
mongo_ha_mode	No	String	Mongo HA mode.
safe_mode	No	Integer	Running mode of an MRS cluster. Values: 0: Normal cluster 1: Security cluster
ssl_cert_password	No	String	SSL certificate password. The certificate file name extension is .p12.
ssl_cert_check_sum	No	String	The checksum value of the SSL certificate, which is used for backend verification. This parameter is mandatory for secure connection to the source database.
ssl_cert_key	No	String	SSL certificate content, which is encrypted using Base64.
ssl_cert_name	No	String	SSL certificate name.
ssl_link	No	Boolean	Whether SSL is enabled.
topic	No	String	Kafka topic name.
cluster_mode	No	String	For MongoDB 4.0 or later, if the cluster instance cannot obtain the IP address of the sharded node, set cluster_mode in source_endpoint to Sharding4.0+. Default value: Sharding4.0+ Value: Sharding4.0+
kafka_security_config	No	Object	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	Security protocol. This parameter is mandatory for security authentication. The corresponding field for Kafka is security.protocol. 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: The SSL encryption is used to connect to Kafka, and you need to configure SSL parameters. SASL_SSL: The SASL and SSL encryption authentication modes are used. You need to configure SSL and SASL parameters. Enumerated values: PLAINTEXT SASL_PLAINTEXT SASL_SSL SSL
trust_store_key_name	No	String	Certificate name. This parameter is mandatory when the security protocol is set to SSL or SASL_SSL.
trust_store_key	No	String	Value of the security certificate after Base64 transcoding. This parameter is mandatory when the security protocol is set to SSL or SASL_SSL.
trust_store_password	No	String	Certificate password. This parameter is mandatory when a password is set for the certificate.
endpoint_algorithm	No	String	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.
sasl_mechanism	No	String	SASL mechanism used for client connection. The corresponding field for Kafka is sasl.mechanism. The values are as follows: GSSAPI PLAIN SCRAM-SHA-256 SCRAM-SHA-512
delegation_tokens	No	Boolean	Whether to use token authentication. 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.
enable_key_store	No	Boolean	Whether to enable two-way SSL authentication.
key_store_key	No	String	Keystore certificate. This parameter is mandatory when two-way SSL authentication is enabled.
key_store_key_name	No	String	Keystore certificate name. This parameter is mandatory when two-way SSL authentication is enabled.
key_store_password	No	String	Keystore certificate password. This parameter is mandatory when a password is set for the certificate. The corresponding field for Kafka is ssl.keystore.password.
set_private_key_password	No	Boolean	Whether to set the keystore private key password. The default value is false.
key_password	No	String	Keystore private key password. This parameter is mandatory when two-way SSL authentication is enabled and set_private_key_password is set to true. The corresponding field for Kafka is ssl.key.password.

**Table 9** Data structure description of field **tags**
Parameter	Mandatory	Type	Description
key	No	String	Tag key. The value can contain a maximum of 36 characters, including letters, digits, underscores (_), and hyphens (-). Set this parameter when you need to modify a tag.
value	No	String	Tag value. The value can contain a maximum of 43 characters, including letters, digits, underscores (_), and hyphens (-). Set this parameter when you need to modify a tag.

Response Parameters

Status code: 200

**Table 10** Response body parameters
Parameter	Type	Description
count	Integer	Total number.
results	Array of objects	List of tasks that are modified in batches. For details, see Table 11.

**Table 11** Data structure description of field **results**
Parameter	Type	Description
id	String	Task ID.
status	String	Status Values: success: The task is successful. failed: The task fails.
error_code	String	Error code.
error_msg	String	Error message.

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

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

Status Code

Status Code	Description
200	OK
400	Bad Request

Error Code

For details, see Error Code.

Parent topic: Public API Management

Previous topic: Testing Connections in Batches (Cluster Mode)

Next topic: Selecting Database Objects in Batches

Feedback

Was this page helpful?

Helpful Not helpful

Provide feedback

Thank you very much for your feedback. We will continue working to improve the documentation.See the reply and handling status in My Cloud VOC.

The system is busy. Please try again later.

Which of the following issues have you encountered?

Content is inconsistent with the product UI

Unclear descriptions

Lack of examples or code

Incorrect steps

Can't find what I need

Lack of best practices

Feedback (optional)

0/500

Select at least one type of issue, and enter your comments or suggestions.

Enter a maximum of 500 characters.

Submit Cancel

For any further questions, feel free to contact us through the chatbot.

Chatbot