Updated on 2024-07-11 GMT+08:00

Asynchronously Creating Tasks in Batches

Function

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

Constraints

  • This API is available only for synchronization from MySQL to MySQL, migration from Redis to GeminiDB Redis, migration from cluster Redis to GeminiDB Redis, and synchronization from Oracle to GaussDB Distributed.
  • This API can be used only in certain regions. For details, see Endpoints.

URI

POST /v5/{project_id}/jobs/batch-async-create

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

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.

The default value is application/json.

X-Auth-Token

Yes

String

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.

After a request is processed, the value of X-Subject-Token in the header is the token value.

X-Language

No

String

Request language type.

Enumerated values:

  • en-us
  • zh-cn
Table 3 Request body parameters

Parameter

Mandatory

Type

Description

jobs

Yes

Array of objects

Request body for asynchronously creating tasks.

For details, see Table 4.

Table 4 Data structure description of field jobs

Parameter

Mandatory

Type

Description

base_info

Yes

Object

Basic information body for creating a task.

For details, see Table 5.

source_endpoint

Yes

Array of objects

Database information body for creating a task.

For details, see Table 7.

target_endpoint

Yes

Array of objects

Database information body for creating a task.

For details, see Table 7.

alarm_notify

No

Object

Information body for setting task exception notification. If this parameter is enabled, the system sends a notification to a specified SMN topic when the task is abnormal.

For details, see Table 14.

speed_limit

No

Array of objects

Flow control information body.

  • If you enable flow control, you can customize the maximum migration speed.
  • If you disable flow control, the migration speed is not limited and the outbound bandwidth of the source database is maximally used,

which causes read consumption on the source database accordingly. For example, if the outbound bandwidth of the source database is 100 MB/s and 80% bandwidth is used, the I/O consumption on the source database is 80 MB/s.

For details, see Table 15.

user_migration

No

Object

User migration information body.

For details, see Table 16.

policy_config

Yes

Object

Policy information body. This parameter is used to configure migration and synchronization policies, including the conflict policy, DROP DATASE filtering, and object synchronization scope.

For details, see Table 19.

db_object

Yes

Object

Database object information body. This parameter is used to select databases or tables to be migrated for migration and synchronization tasks.

For details, see Table 20.

db_param

No

Object

Database parameter information body.

For details, see Table 26.

tuning_params

No

Object

Advanced setting information body.

For details, see Table 28.

period_order

No

Object

Yearly/Monthly information body.

For details, see Table 30.

node_info

Yes

Object

Information body of the DRS instance.

For details, see Table 31.

public_ip_list

No

Array of objects

Information about a specified EIP.

For details, see Table 35.

Table 5 Data structure description of field base_info

Parameter

Mandatory

Type

Description

name

No

String

Task name. The task name can be 4 to 50 characters in length. It is case-insensitive and can contain only letters, digits, hyphens (-), and underscores (_).

  • Minimum length: 4
  • Maximum length: 50

Minimum length: 4

Maximum length: 50

job_type

No

String

Task scenario. Values:

  • migration: real-time migration.
  • sync: real-time synchronization.
  • cloudDataGuard: real-time disaster recovery.

Enumerated values:

  • migration
  • sync
  • cloudDataGuard

multi_write

No

Boolean

Whether the DR type is dual-active. Note:

  • This parameter is mandatory when job_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 job_type is set to other values, multi_write is optional.

engine_type

No

String

Engine type. The value can be:

  • oracle-to-gaussdbv5: Synchronization from Oracle to GaussDB distributed.
  • redis-to-gaussredis: Migration from Redis to GeminiDB Redis.
  • rediscluster-to-gaussredis: Migration from cluster Redis to GeminiDB Redis.

Enumerated values:

  • oracle-to-gaussdbv5
  • redis-to-gaussredis
  • rediscluster-to-gaussredis

job_direction

No

String

Migration direction. Values:

  • 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: self-built databases.

Enumerated values:

  • up
  • down
  • non-dbs

task_type

No

String

Migration type. Values:

  • FULL_TRANS: full migration.
  • FULL_INCR_TRANS: full+incremental migration.
  • INCR_TRANS: incremental migration.

Enumerated values:

  • FULL_TRANS
  • FULL_INCR_TRANS
  • INCR_TRANS

net_type

No

String

Network type. Values:

  • eip: public network.
  • vpc: VPC network. The VPC network cannot be selected in DR scenarios.
  • vpn: VPN or Direct Connect.

Enumerated values:

  • eip
  • vpc
  • vpn

charging_mode

No

String

Billing mode. The pay-per-use billing is used by default. Values:

  • period: indicates the yearly/monthly billing.
  • on_demand: indicates the pay-per-use billing.

Enumerated values:

  • period
  • on_demand

enterprise_project_id

No

String

Enterprise project ID. The default value is 0, indicating the default enterprise project.

Default value: 0

description

No

String

Task description. The task description can contain a maximum of 256 characters and cannot contain the following special characters: !<>'&"\

Minimum length: 0

Maximum length: 256

start_time

No

String

Scheduled start time of a task.

expired_days

No

String

Number of days after which an abnormal task automatically stops. The unit is day. The value ranges from 14 to 100. If this parameter is not specified, the default value is 14.

Default value: 14

tags

No

Array of objects

Tag information. Up to 20 tags can be added.

For details, see Table 6.

is_open_fast_clean

No

Boolean

Specifies whether to enable binlog clearing for RDS for MySQL or RDS for MariaDB. If this parameter is not transferred, the default value false is used, indicating that quick binlog clearing is disabled.

Table 6 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 (-).

Minimum length: 1

Maximum length: 36

value

No

String

Tag value. The value can contain a maximum of 43 characters, including letters, digits, underscores (_), and hyphens (-).

Minimum length: 1

Maximum length: 43

Table 7 Data structure description of fields source_endpoint and target_endpoint

Parameter

Mandatory

Type

Description

db_type

Yes

String

Database type. The value can be:

  • oracle: Oracle.
  • gaussdbv5: GaussDB distributed.
  • redis: Redis.
  • rediscluster: Cluster Redis.
  • gaussredis: GeminiDB Redis.

Enumerated values:

  • oracle
  • gaussdbv5
  • redis
  • rediscluster
  • gaussredis

endpoint_type

Yes

String

DB instance type. Values:

  • offline: indicates an on-premises database.
  • ecs: indicates a database built on Huawei Cloud ECSs.
  • cloud: indicates a Huawei cloud database.

Enumerated values:

  • offline
  • ecs
  • cloud

endpoint_role

Yes

String

DB instance role. Values:

  • so: indicates the source database.
  • ta: indicates the destination database.

Enumerated values:

  • so
  • ta

endpoint

Yes

Object

Basic information body of the database.

For details, see Table 8.

cloud

No

Object

Region and project where a DB instance is located.

For details, see Table 9.

vpc

No

Object

Information about the VPC, subnet, and security group where a DB instance resides.

For details, see Table 10.

config

No

Object

Basic information body of database settings.

For details, see Table 11.

ssl

No

Object

Information body of the database SSL certificate.

For details, see Table 12.

customized_dns

No

Object

Custom DNS server.

For details, see Table 13.

Table 8 Data structure description of fields endpoint and source_sharding

Parameter

Mandatory

Type

Description

id

No

String

Database information ID.

endpoint_name

Yes

String

Database scenario type. The value can be:

  • oracle: indicates the on-premises Oracle database.
  • ecs_oracle: indicates the Oracle database built on Huawei Cloud ECSs.
  • cloud_gaussdbv5: indicates the Huawei Cloud distributed GaussDB database.
  • mysql: indicates the MySQL database built on other clouds or on-premises MySQL database.
  • ecs_mysql: indicates the MySQL database built on Huawei Cloud ECSs.
  • cloud_mysql: indicates the Huawei Cloud RDS for MySQL database.
  • redis: On-premises Redis database.
  • ecs_redis: Redis database built on Huawei Cloud ECSs.
  • rediscluster: On-premises cluster Redis database.
  • ecs_rediscluster: Cluster Redis database built on Huawei Cloud ECSs.
  • cloud_gaussdb_redis: Huawei Cloud GeminiDB Redis.

Enumerated values:

  • oracle
  • ecs_oracle
  • cloud_gaussdbv5
  • mysql
  • ecs_mysql
  • cloud_mysql
  • redis
  • ecs_redis
  • rediscluster
  • ecs_rediscluster
  • cloud_gaussdb_redis

ip

No

String

Database IP address. Constraints:

  • If an on-premises MongoDB database is used, use colons (:) to separate the database IP address and port number, and use commas (,) to separate multiple values. A maximum of three IP addresses or domain names can be entered.
  • If a DDS instance is used, use colons (:) to separate the database IP address and port number, and use commas (,) to separate multiple values.
  • If the database is a cluster Redis database, enter the IP addresses and port numbers of all shards in the source cluster Redis database. Use colons (:) to separate a database IP address and port number. Use commas (,) to separate multiple values. You are advised to enter the IP address of the slave node of a cluster shard. Up to 32 IP addresses or domain names can be entered. Use commas (,) to separate multiple IP addresses or domain names.

Example:

  • MongoDB: 192.168.0.10:8080,192.168.0.11:8080,192.168.0.12:8080
  • DDS: 192.168.205.130:8635,192.168.250.64:8635
  • Cluster Redis: 192.168.0.1:8080,192.168.0.2:8080

db_port

No

String

Database port.

The value is an integer ranging from 1 to 65535.

db_user

Yes

String

Database username.

db_password

Yes

String

Database password.

instance_id

No

String

ID of a Huawei Cloud DB instance.

instance_name

No

String

Name of a Huawei Cloud DB instance.

db_name

No

String

Database name. Example:

  • oracle: serviceName.orcl.

source_sharding

No

Array of objects

Information about the physical source database.

For details, see Table 8.

Table 9 Data structure description of field cloud

Parameter

Mandatory

Type

Description

region

Yes

String

Region ID. This parameter is mandatory when DB Instance Type is set to ecs (database built on Huawei Cloud ECSs) or cloud (Huawei cloud database). For details, see Regions and Endpoints. Note: If there are subprojects in a region, the region ID is a combination of the regional project ID and subproject ID, which are combined using an underscore (_).

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.

az_code

No

String

Name of the AZ where the database is located.

Table 10 Data structure description of field vpc

Parameter

Mandatory

Type

Description

vpc_id

Yes

String

ID of the VPC where a DB instance is located. To obtain the ID, perform the following steps:

Method 1: Log in to the VPC console and view the VPC ID on the VPC details page.

Method 2: Call the API for querying VPCs. For details, see Querying VPCs.

subnet_id

Yes

String

ID of the subnet where a DB instance is located. To obtain the ID, perform the following steps:

Method 1: Log in to the VPC console and click the target subnet on the Subnets page to view the network ID on the displayed page.

Method 2: Call the API for querying subnets. For details, see Querying Subnets.

security_group_id

No

String

ID of the security group where a DB instance is located. To obtain the ID, perform the following steps:

Method 1: Log in to the VPC console. Choose Access Control > Security Groups in the navigation pane on the left. On the displayed page, click the target security group. You can view the security group ID on the displayed page.

Method 2: Call the API for querying security groups. For details, see Querying Security Groups.

Table 11 Data structure description of field config

Parameter

Mandatory

Type

Description

is_target_readonly

No

Boolean

Whether the destination DB instance is set to read-only. This parameter is available 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.

Default value: true

node_num

No

Integer

Number of subtasks connected to the source cluster Redis instance for data migration from cluster Redis to GeminiDB Redis. The value ranges from 1 to 16 and cannot be greater than the number of shards in the source cluster Redis instance. Set this parameter based on the scale of the source cluster Redis instance. You are advised to set one subtask to connect to four shards in the source cluster Redis instance.

Minimum value: 1

Maximum value: 16

Default value: 0

Table 12 Data structure description of field ssl

Parameter

Mandatory

Type

Description

ssl_link

No

Boolean

Whether SSL is enabled. If SSL is enabled, the value of this parameter is true.

ssl_cert_name

No

String

SSL certificate name.

ssl_cert_key

No

String

SSL certificate content, which is encrypted using Base64.

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_password

No

String

SSL certificate password. This parameter is mandatory if the certificate file name extension is .p12.

Table 13 Data structure description of field customized_dns

Parameter

Mandatory

Type

Description

is_set_dns

Yes

Boolean

Specifies whether to set your own DNS server.

set_dns_action

Yes

String

Behavior of setting your own DNS server.

  • add: Add a customized DNS server IP address.
  • keep: Retain the DNS server IP address.
  • update: Update the customized DNS server IP address. (The update takes effect when the DNS server IP address changes.)
  • recover: Restore the default DNS server IP address. (Restoration may cause domain name resolution failures. Exercise caution when performing this operation.)

Enumerated values:

  • add
  • keep
  • update
  • recover

dns_ip

Yes

String

DNS server IP address.

Minimum length: 0

Maximum length: 15

Table 14 Data structure description of field alarm_notify

Parameter

Mandatory

Type

Description

alarm_to_user

Yes

Boolean

Whether to notify users of alarms.

Default value: false

topic_urn

No

String

SMN topic URN.

delay_time

No

Long

Delay threshold, in seconds. Values:

  • Minimum value: 1
  • Maximum value: 3600
  • Default value: 0
NOTE:
  1. A synchronization delay indicates a time difference (in seconds) of synchronization between the source and destination database.
  2. If the delay exceeds a specified value and lasts for 6 minutes, DRS will notify specified recipients. (In the early stages of an incremental migration, there is more delay because more data is waiting to be synchronized. In this situation, no notifications will be sent.)
  3. This option is available only for full+incremental tasks.

rpo_delay

No

Long

RPO delay threshold, in seconds. Values:

  • Minimum value: 1
  • Maximum value: 3600
  • Default value: 0
NOTE:

If the RPO delay between the service database and the DRS instance exceeds a specified value and lasts for 6 minutes, DRS will notify specified recipients. (In the early stages of an incremental DR, there is more delay because more data is waiting to be synchronized. In this situation, no notifications will be sent.)

rto_delay

No

Long

RTO delay threshold, in seconds. Values:

  • Minimum value: 1
  • Maximum value: 3600
  • Default value: 0
NOTE:

If the RTO delay between the DRS instance and the DR database exceeds a specified value and lasts for 6 minutes, DRS will notify specified recipients.

Table 15 Data structure description of field speed_limit

Parameter

Mandatory

Type

Description

begin

Yes

String

Start time (UTC) of flow control. The start time is an integer in hh:mm format and the minutes part is ignored. hh indicates the hour, for example, 01:00.

end

Yes

String

End time (UTC) in the format of hh:mm, for example, 15:59. The value must end with 59.

speed

Yes

String

Speed. The value ranges from 1 to 9,999, in MB/s.

Table 16 Data structure description of field user_migration

Parameter

Mandatory

Type

Description

is_migrate_user

Yes

Boolean

Whether to migrate users.

is_set_password

Yes

Boolean

Whether to reset a unified password. Values:

  • true: Reset a unified password.
  • false: Do not reset a unified password. The following scenarios are supported:
  • Real-time migration: MySQL migration.

password

No

String

Unified password. This parameter is mandatory when is_set_password is set to true. The password cannot be empty.

user_list

No

Array of objects

User list in the migration objects. The following scenarios are supported:

  • Real-time migration: MySQL-to-MySQL migration and MongoDB-to-DDS migration.

For details, see Table 17.

role_list

No

Array of objects

User role in the migration objects. The following scenarios are supported:

  • Real-time migration: MongoDB-to-DDS migration.

For details, see Table 18.

Table 17 Data structure description of field user_list

Parameter

Mandatory

Type

Description

id

Yes

String

User ID.

account

Yes

String

User.

is_set_password

No

Boolean

Whether to reset the user password. The following scenarios are supported:

  • Real-time migration: MySQL-to-MySQL migration.

password

No

String

New password. This parameter is mandatory when is_set_password is set to true. The password cannot be empty.

Table 18 Data structure description of field role_list

Parameter

Mandatory

Type

Description

role

Yes

String

Role.

Table 19 Data structure description of field policy_config

Parameter

Mandatory

Type

Description

filter_ddl_policy

No

String

DDL filtering policy. Values:

  • drop_database

Scenarios:

  • Real-time migration: For MySQL migration, this parameter can be set to "", indicating that DROP DATABASE is not filtered.
  • Real-time synchronization: For MySQL synchronization, this parameter can only be set to drop_database.

Enumerated values:

  • drop_database

conflict_policy

No

String

Incremental conflict policy. The conflict policy refers to the conflict handling policy during incremental synchronization. By default, conflicts in the full synchronization phase are ignored. Values:

  • ignore: Ignore the conflict. The system will ignore the conflicting data and continue the subsequent synchronization process.
  • stop: Report an error. The synchronization task will be stopped and fail. You can view the details in synchronization logs.
  • overwrite: Overwrite the existing data with the synchronized data. Conflicting data will be overwritten.

Scenarios:

  • Real-time migration: Not supported.
  • Real-time synchronization: Supported.

Enumerated values:

  • ignore
  • stop
  • overwrite

index_trans

No

Boolean

Object synchronization scope: indicates whether to synchronize normal indexes. By default, DRS synchronizes the primary key or unique index. A normal index refers to an index other than the primary key or unique index. Values:

  • true: All indexes will be synchronized.
  • false: Only primary key or unique indexes are synchronized.

Default value: true

ddl_trans

No

Boolean

Object synchronization scope: indicates whether to synchronize DDLs in the incremental phase. Values:

  • true: DDLs are synchronized in the incremental phase.
  • false: DDLs are not synchronized in the incremental phase.

Default value: true

data_sync_topology_type

No

String

Data synchronization topology. Data synchronization supports multiple synchronization topologies. You can plan your synchronization instances based on service requirements. Values:

  • one2one: one-to-one.
  • one2many: one-to-many.
  • many2one: many-to-one.

Default value: one2one

Enumerated values:

  • one2one
  • one2many
  • many2one

support_ddl_info

No

String

DDLs to be synchronized. Values:

  • CREATE_TABLE: Create a table.
  • ADD_COLUMN: Add a column.
  • MODIFY_COLUMN: Modify column attribute.
  • CHANGE_COLUMN: Change column attribute.
  • DROP_INDEX: Delete an index.
  • ADD_INDEX: Add an index.
  • CREATE_INDEX: Create an index.
  • RENAME_INDEX: Rename an index.

Note:

  • In one-to-one and one-to-many scenarios, if the DDL usage of the source and destination databases must be consistent, high-risk DDLs must be synchronized.
  • In one-to-one and one-to-many scenarios, if you do not want a high-risk DDL to be performed in the destination, deselect the high-risk DDL to protect destination data. However, filtering DDL may cause synchronization to fail, for example, column deletion.
  • In many-to-one data synchronization tasks, it is recommended that only the ADD COLUMN operation is synchronized, or tasks may fail or data may be inconsistent due to changes in destination tables. Typical failure scenarios are as follows:
    • Synchronizing the TRUNCATE operation clears all destination data.
    • Synchronizing the CREATE INDEX operation locks the destination table.
    • Synchronizing the RENAME operation causes other task failure because the destination table cannot be found.
    • Synchronizing the MODIFY COLUMN operation causes other task failure due to incompatible data types.

Enumerated values:

  • CREATE_TABLE
  • ADD_COLUMN
  • MODIFY_COLUMN
  • CHANGE_COLUMN
  • DROP_INDEX
  • ADD_INDEX
  • CREATE_INDEX
  • RENAME_INDEX

sync_type_policy

No

String

Synchronization object type. Values:

  • supportAllType: All types.
  • tableData: Data.
  • tableStructure: Table structure.
  • constraintData: Index.
NOTE:

Except supportAllType, other types can be specified together, for example, tableData,tableStructure.

increment_read_mode

No

String

Incremental log reading mode for synchronization from Oracle to GaussDB: logminer or xstream.

dml_types

No

String

DML synchronization type. The value can be:

  • i: INSERT
  • u: UPDATE
  • d: DELETE
Table 20 Data structure description of field db_object

Parameter

Mandatory

Type

Description

object_scope

Yes

String

Migration or synchronization object scope. Values:

  • all: Migrate or synchronize all objects.
  • database: database-level migration or synchronization.
  • table: table-level migration or synchronization.

Enumerated values:

  • all
  • database
  • table

target_root_db

No

Object

Destination database for database object migration or synchronization. This parameter is mandatory for database synchronization from Layer 2 to Layer 3.

For details, see Table 21.

object_info

No

Map<String,DatabaseObject>

Object information for migration or synchronization. If object_scope is set to all, leave this parameter blank. If object_scope is set to database or table, this parameter is mandatory.

For details, see Table 22.

Table 21 Data structure description of field target_root_db

Parameter

Mandatory

Type

Description

db_name

No

String

Database name.

db_encoding

No

String

Encoding format. The default value is UTF-8.

Table 22 Data structure description of field object_info

Parameter

Mandatory

Type

Description

sync_type

No

String

Type of the database in real-time synchronization. Values:

config: This parameter is mandatory only when the database is used as an association database in advanced settings for data filtering. In this case, the database and its schemas and tables will not be synchronized to the destination database. The name and all parameters do not take effect. Enter the associated objects in schemas and tables.

NOTE:

To synchronize the database-level object, set sync_type to config for the lower-level object.

Enumerated values:

  • config

name

No

String

Name of the database in the destination database (database name mapping).

all

No

Boolean

Whether to migrate or synchronize the entire database.

NOTE:
  • If data filtering, column filtering, and column mapping are required for schemas, tables, and columns in the database, set this parameter to false. Otherwise, set this parameter to true.
  • If additional columns are required for tables in the database, set this parameter to true and enter additional column information in columns of table-level objects.
  • If the table columns in the database are used as association columns in advanced settings for data filtering, set this parameter to true, enter the association column information in columns, and enter the configuration criteria in advanced settings for data filtering in config_conditions.

schemas

No

Map<String,SchemaObject>

Schema to be migrated or synchronized. This parameter is mandatory when all is set to false.

For details, see Table 23.

tables

No

Map<String,TableObject>

Table to be migrated or synchronized. This parameter is mandatory when all is set to false.

For details, see Table 24.

total_table_num

No

Integer

Number of tables in the database. If the number of tables exceeds the threshold, this parameter is not displayed.

is_synchronized

No

Boolean

Whether synchronization has been performed.

Table 23 Data structure description of field schemas

Parameter

Mandatory

Type

Description

sync_type

No

String

Type of the schema in real-time synchronization. Values:

config: This parameter is mandatory only when the schema is used as an association schema in advanced settings for data filtering. In this case, the schema and its tables will not be synchronized to the destination database. The name and all parameters do not take effect. Enter the associated objects in tables.

NOTE:

To synchronize the schema-level object, set sync_type to config for the lower-level object.

name

No

String

Name of the schema in the destination database (schema name mapping).

all

No

Boolean

Whether to migrate or synchronize the entire schema.

NOTE:
  • If data filtering, column filtering, and column mapping are required for tables and columns in the schema, set this parameter to false. Otherwise, set this parameter to true.
  • If additional columns are required for tables in the schema, set this parameter to true and enter additional column information in columns of table-level objects.
  • If the table columns in the schema are used as association columns in advanced settings for data filtering, set this parameter to true, enter the association column information in columns, and enter the configuration criteria in advanced settings for data filtering in config_conditions.

tables

No

Map<String,TableObject>

Table to be migrated or synchronized. This parameter is mandatory when all is set to false.

For details, see Table 24.

Table 24 Data structure description of field tables

Parameter

Mandatory

Type

Description

sync_type

No

String

Type of the table in real-time synchronization. Values:

config: This parameter is mandatory only when the table is used as an association table in advanced settings for data filtering. In this case, the table and its columns will not be synchronized to the destination database. The name, all, filtered, and filter_conditions parameters do not take effect. Enter the associated objects in columns and the configuration criteria in advanced settings for data filtering in config_conditions.

NOTE:

To synchronize the table-level object, set sync_type to config for the lower-level object.

type

No

String

Object type. Values:

  • table: indicates a table.
  • view: indicates a view.
  • procedure: indicates a stored procedure.

Enumerated values:

  • table
  • view
  • procedure

name

No

String

Name of the table in the destination database (table name mapping).

all

No

Boolean

Whether to migrate or synchronize the entire table.

NOTE:
  • If column filtering and column mapping are not required for the table, set this parameter to true. Otherwise, set this parameter to false.
  • If additional columns are required for the table, set this parameter to true and enter additional column information in columns.
  • If the table columns are used as association columns in advanced settings for data filtering, set this parameter to true, enter the association column information in columns, and enter the configuration criteria in advanced settings for data filtering in config_conditions.

db_alias_name

No

String

Mapping of database names at the table level in the one-to-many scenario.

schema_alias_name

No

String

Mapping of schema names at the table level in the one-to-many scenario.

filtered

No

Boolean

Whether to filter data in the table.

filter_conditions

No

Array of strings

Filtering criteria for the table data. The processing rule value is a SQL statement. The value contains a maximum of 512 characters.

Minimum length: 0

Maximum length: 512

config_conditions

No

Array of strings

Configuration criteria in advanced settings for data filtering of the table. This parameter is mandatory when the table is used as an association table for query. The processing rule value is a SQL statement. The value contains a maximum of 512 characters.

Minimum length: 0

Maximum length: 512

is_synchronized

No

Boolean

Whether synchronization has been performed.

columns

No

Map<String,ColumnObject>

Columns to be synchronized, mapped, filtered, or added. This parameter is mandatory when column filtering, column mapping, and additional columns are required. This parameter takes effect only in real-time synchronization tasks. This parameter is mandatory when all is set to false.

For details, see Table 25.

Table 25 Data structure description of field columns

Parameter

Mandatory

Type

Description

sync_type

No

String

Type of the column in real-time synchronization. Values:

config: This parameter is mandatory only when the column is used as an association column in advanced settings for data filtering. If the column is a primary key column or index column required for optimizing the query, primary_key_for_data_filtering or index_for_data_filtering is mandatory.

NOTE:

Whether to synchronize the column to the destination database depends on the filtered parameter, which is different from the database, schema, and table-level synchronization.

primary_key_for_data_filtering

No

String

Whether the column is a primary key column in advanced settings for data filtering. If the column is a primary key column, set this parameter to the column name. Otherwise, leave this parameter blank.

index_for_data_filtering

No

String

Whether the column is an index column required for optimizing the query. The index is added to the cached data. It does not affect the source table. If the column is an index column in advanced settings for data filtering, this parameter is mandatory. Otherwise, leave this parameter blank.

name

No

String

Name of the column in the destination database (column name mapping). If the column is an additional column, the value must be the same as the column name in the table-level object.

type

No

String

Data type of the column. Column filtering: Enter the data type of the source column. Additional column adding: Enter the data type of the new column. The values and constraints vary depending on the operation type. Values:

  • Default: The value can be int, long, varchar(256), datetime, or timestamp.
  • create_time: The value can be long, datetime, or timestamp.
  • update_time: The value can be long, datetime, or timestamp.
  • Expression: The value can be varchar (256), and the column value must be concat(__current_database, '@', __current_table).
  • serverName@database@table: The value can be varchar(256).

primary_key_for_column_filtering

No

String

Whether the column is a primary key column in column mapping. If the column is a primary key column, set this parameter to PRI. Otherwise, leave this parameter blank.

filtered

No

Boolean

Whether the column is filtered out. This parameter cannot be used together with the additional parameter. Values:

  • true: indicates that the column will be synchronized.
  • false: indicates that the column is filtered out and will not be synchronized.

additional

No

Boolean

Whether the column is an additional column. If the column is an additional column, the value of name must be the same as the column name in the table-level object and cannot be used together with the filtered parameter.

operation_type

No

String

Operation type. The new column is filled with a specific operation type. Values:

  • Default: "operation_type":"ADDITIONALCOLUMN,default_value"
  • create_time: "operation_type":"ADDITIONALCOLUMN,create_time"
  • update_time: "operation_type":"ADDITIONALCOLUMN,update_time"
  • Expression: "operation_type":"ADDITIONALCOLUMN,expression"
  • serverName@database@table: "operation_type":"ADDITIONALCOLUMN,server_database_table"

value

No

String

Value of the additional column. Note:

  • This parameter is mandatory only when operation type is set to Default or serverName@database@table.
  • When operation type is set to Expression, this parameter has a fixed value of concat(__current_database, '@', __current_table).
Table 26 Data structure description of field db_param

Parameter

Mandatory

Type

Description

common

No

Array of objects

Common parameter. Only the values of destination database parameters whose comparison results are inconsistent can be changed.

For details, see Table 27.

performance

No

Array of objects

Performance parameter. If the comparison results are consistent, you can also change the values of destination database parameters.

For details, see Table 27.

Table 27 Data structure description of fields common and performance

Parameter

Mandatory

Type

Description

key

Yes

String

Database parameter name.

target_value

Yes

String

Parameter value of the destination database.

Table 28 Data structure description of field tuning_params

Parameter

Mandatory

Type

Description

full_sync

Yes

Array of objects

Full migration tuning parameters.

For details, see Table 29.

incre_capture

Yes

Array of objects

Incremental capture tuning parameters.

For details, see Table 29.

incre_apply

Yes

Array ofobjects

Incremental replay tuning parameters.

For details, see Table 29.

incre_relay

Yes

Array of objects

Incremental log extraction tuning parameters.

For details, see Table 29.

Table 29 Data structure description of fields full_sync, incre_capture, incre_apply, and incre_relay

Parameter

Mandatory

Type

Description

param_name

Yes

String

Parameter name.

param_value

Yes

String

Parameter value.

availability

Yes

Boolean

Available or not.

Table 30 Data structure description of field period_order

Parameter

Mandatory

Type

Description

period_type

Yes

Integer

Subscription period type. Values:

  • 2: indicates that the service is subscribed by month.
  • 3: indicates that the service is subscribed by year.

Default value: 3

Enumerated values:

  • 2
  • 3

period_num

Yes

Integer

Number of subscription periods. This parameter depends on the value of period_type. For example:

  • When period_type is set to 2, the value 1 indicates one month.
  • When period_type is set to 3, the value 1 indicates one year.

is_auto_renew

No

Integer

Whether auto renewal is enabled. Values:

  • 0: indicates that auto renewal is disabled. This is the default value. You need to pay manually.
  • 1: indicates that auto renewal is enabled.

Default value: 0

Enumerated values:

  • 0
  • 1
Table 31 Data structure description of field node_info

Parameter

Mandatory

Type

Description

spec

Yes

Object

Information body of DRS instance specifications.

For details, see Table 32.

vpc

No

Object

Information body of DRS instance VPC. This parameter is mandatory for self-built databases.

For details, see Table 33.

base_info

No

Object

Information body of DRS instance VPC. This parameter is mandatory for self-built databases.

For details, see Table 34.

Table 32 Data structure description of field spec

Parameter

Mandatory

Type

Description

node_type

Yes

String

Specification code. Values:

  • micro: minimum specifications.
  • small: small specifications.
  • medium: medium specifications.
  • high: large specifications.

Enumerated values:

  • micro
  • small
  • medium
  • high
Table 33 Data structure description of field vpc

Parameter

Mandatory

Type

Description

vpc_id

Yes

String

ID of the VPC where the DRS instance is located.

subnet_id

Yes

String

ID of the subnet where the DRS instance is located.

custom_node_ip

No

String

IP address of the DRS instance to be created. Use commas (,) to separate multiple values. Only IPv4 addresses are supported. To obtain the IP address, perform the following steps:

  • Method 1: Log in to the VPC console and click the target subnet on the Subnets page. View the subnet CIDR block and select an IP address that is not in use.
  • Method 2: Call the API for querying private IP addresses. For details, see "Querying Private IP Addresses". Select a private IP address whose device_owner is left blank. Example: 192.168.0.10,192.168.0.11

security_group_id

No

String

ID of the security group where the DRS instance is located.

Table 34 Data structure description of field base_info

Parameter

Mandatory

Type

Description

instance_type

Yes

String

DB instance type. The value can be:

  • single: single instance.
  • ha: primary/standby instance.

Enumerated values:

  • single
  • ha

arch

Yes

String

CPU architecture. The value can be:

  • x86
  • arm

Enumerated values:

  • x86
  • arm

availability_zone

Yes

String

AZ ID. If the task instance is not a single instance, you need to specify an AZ for each node of the instance and separate the AZs with commas (,). Example:

  • If instance_type is set to single, the value is cn-north-4a.
  • If instance_type is set to ha, the value is cn-north-4a,cn-north-4b.

status

No

String

Status.

role

No

String

Primary/Standby role of a task.

Table 35 Data structure description of field public_ip_list

Parameter

Mandatory

Type

Description

id

Yes

String

ID of a specified EIP.

public_ip

Yes

String

EIP.

type

Yes

String

Type of a task with an EIP bound.

  • 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.

Enumerated values:

  • master
  • slave

Response Parameters

Status code: 202

Table 36 Response body parameters

Parameter

Type

Description

job

Object

Response body for asynchronously creating tasks in batches.

For details, see Table 37.

Table 37 Data structure description of field job

Parameter

Type

Description

async_job_id

String

ID of the tasks created asynchronously in batches.

Status code: 400

Table 38 Response body parameters

Parameter

Type

Description

error_code

String

Error code.

Minimum length: 12

Maximum length: 12

error_msg

String

Error message.

Minimum length: 1

Maximum length: 512

Example Request

  • Asynchronously creating pay-per-use synchronization tasks from Oracle to GaussDB distributed, in which task_type is set to FULL_INCR_TRANS and net_type is set to eip
    https://{endpoint}/v5/054ba152d480d55b2f5dc0069e7ddef0/jobs/batch-async-create
    
    {
      "jobs" : [ {
        "base_info" : {
          "name" : "DRS-1234",
          "job_type" : "sync",
          "engine_type" : "oracle-to-gaussdbv5",
          "job_direction" : "up",
          "task_type" : "FULL_INCR_TRANS",
          "net_type" : "eip",
          "charging_mode" : "on_demand",
          "enterprise_project_id" : "0",
          "description" : "",
          "expired_days" : "14",
          "tags" : [ {
            "key" : "test",
            "value" : "test"
          } ]
        },
        "source_endpoint" : [ {
          "db_type" : "oracle",
          "endpoint_type" : "offline",
          "endpoint_role" : "so",
          "endpoint" : {
            "endpoint_name" : "oracle",
            "ip" : "10.154.217.239",
            "db_port" : "1521",
            "db_user" : "ORACLE_USER",
            "db_name" : "serviceName.orcl",
            "db_password" : "******"
          },
          "ssl" : {
            "ssl_link" : false
          }
        } ],
        "target_endpoint" : [ {
          "db_type" : "gaussdbv5",
          "endpoint_type" : "cloud",
          "endpoint_role" : "ta",
          "endpoint" : {
            "endpoint_name" : "cloud_gaussdbv5",
            "instance_id" : "c2c7579bc09c490b9d8009db715aeb0ain14",
            "db_user" : "root",
            "db_password" : "******"
          },
          "cloud" : {
            "region" : "cn-north-4",
            "project_id" : "9dc8c0f3f74c4dbb23c29cf0318ee561",
            "az_code" : "cn-north-4a,cn-north-4g,cn-north-4c"
          },
          "vpc" : {
            "vpc_id" : "2cb5d364-ae63-4fbb-85b7-7d59f4a88f8f",
            "subnet_id" : "2cb54324-ae63-4fbb-85b7-7d59f4a88f8f",
            "security_group_id" : "039a3s89-665a-43e2-9b4f-bda7d9ee148d"
          }
        } ],
        "alarm_notify" : {
          "alarm_to_user" : true,
          "topic_urn" : "urn:smn:cn-north-4:f2c2468c3ee7410c862a461ca073d2f2:test",
          "delay_time" : 60
        },
        "speed_limit" : [ {
          "begin" : "16:00",
          "end" : "15:59",
          "speed" : "10"
        } ],
        "policy_config" : {
          "ddl_trans" : false
        },
        "db_object" : {
          "object_scope" : "table",
          "target_root_db" : {
            "db_name" : "target_db_name",
            "db_encoding" : "utf8"
          },
          "object_info" : {
            "source_db1" : {
              "name" : "source_db1",
              "all" : false,
              "tables" : {
                "source_tb1" : {
                  "type" : "table",
                  "name" : "source_tb1",
                  "all" : true
                },
                "source_tb2" : {
                  "type" : "table",
                  "name" : "source_tb2",
                  "all" : true
                }
              }
            }
          }
        },
        "node_info" : {
          "spec" : {
            "node_type" : "medium"
          }
        }
      } ]
    }
  • Asynchronously creating pay-per-use synchronization tasks in batches from Oracle to GaussDB Distributed and specifying EIPs
    https://{endpoint}/v5/054ba152d480d55b2f5dc0069e7ddef0/jobs/batch-async-create
    
    {
      "jobs" : [ {
        "base_info" : {
          "name" : "DRS-1234",
          "job_type" : "sync",
          "engine_type" : "oracle-to-gaussdbv5",
          "job_direction" : "up",
          "task_type" : "FULL_INCR_TRANS",
          "net_type" : "eip",
          "charging_mode" : "on_demand",
          "enterprise_project_id" : "0",
          "description" : "",
          "expired_days" : "14",
          "tags" : [ {
            "key" : "test",
            "value" : "test"
          } ]
        },
        "source_endpoint" : [ {
          "db_type" : "oracle",
          "endpoint_type" : "offline",
          "endpoint_role" : "so",
          "endpoint" : {
            "endpoint_name" : "oracle",
            "ip" : "******",
            "db_port" : "1521",
            "db_user" : "ORACLE_USER",
            "db_name" : "serviceName.orcl",
            "db_password" : "******"
          },
          "ssl" : {
            "ssl_link" : false
          }
        } ],
        "target_endpoint" : [ {
          "db_type" : "gaussdbv5",
          "endpoint_type" : "cloud",
          "endpoint_role" : "ta",
          "endpoint" : {
            "endpoint_name" : "cloud_gaussdbv5",
            "instance_id" : "c2c7579bc09c490b9d8009db715aeb0ain14",
            "db_user" : "root",
            "db_password" : "******"
          },
          "cloud" : {
            "region" :"cn-north-4",
            "project_id" : "9dc8c0f3f74c4dbb23c29cf0318ee561",
            "az_code" : "cn-north-4a,cn-north-4g,cn-north-4c"
          },
          "vpc" : {
            "vpc_id" : "2cb5d364-ae63-4fbb-85b7-7d59f4a88f8f",
            "subnet_id" : "2cb54324-ae63-4fbb-85b7-7d59f4a88f8f",
            "security_group_id" : "039a3s89-665a-43e2-9b4f-bda7d9ee148d"
          }
        } ],
        "alarm_notify" : {
          "alarm_to_user" : true,
          "topic_urn" : "urn:smn:cn-north-4:f2c2468c3ee7410c862a461ca073d2f2:test",
          "delay_time" : 60
        },
        "speed_limit" : [ {
          "begin" : "16:00",
          "end" : "15:59",
          "speed" : "10"
        } ],
        "policy_config" : {
          "ddl_trans" : false
        },
        "db_object" : {
          "object_scope" : "table",
          "target_root_db" : {
            "db_name" : "target_db_name",
            "db_encoding" : "utf8"
          },
          "object_info" : {
            "source_db1" : {
              "name" : "source_db1",
              "all" : false,
              "tables" : {
                "source_tb1" : {
                  "type" : "table",
                  "name" : "source_tb1",
                  "all" : true
                },
                "source_tb2" : {
                  "type" : "table",
                  "name" : "source_tb2",
                  "all" : true
                }
              }
            }
          }
        },
        "public_ip_list" : [ {
          "id" : "018d9e56-26d5-455a-97dc-e6f5f44a2cbd",
          "public_ip" : "******",
          "type" : "master"
        } ],
        "node_info" : {
          "spec" : {
            "node_type" : "medium"
          }
        }
      } ]
    }

Example Response

Status code: 202

Accepted

{
  "job" : {
    "async_job_id" : "bd4193aa-072d-4ce6-beec-adffc7252341"
  }
}

Status code: 400

Bad Request

{
  "error_code" : "DRS.10000001",
  "error_msg" : "Failed."
}

Status Code

Status Code

Description

202

Accepted

400

Bad Request

Error Code

For details, see Error Code.