Help Center> Data Replication Service> API Reference> APIs V3.0 (Deprecated)> Public API Management> Modifying Tasks in Batches
Updated on 2024-07-11 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

Node specification type. This parameter is mandatory when this API is invoked to modify a task after the connection test.

Default value: high

Value: high

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

OK

{
  "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