Help Center/ Data Replication Service/ API Reference/ APIs V5.0 (in OBT)/ Backup Migration/ Creating a Backup Migration Task

Updated on 2025-02-14 GMT+08:00

Online Debugging

CLI Examples

View PDF

Creating a Backup Migration Task

Function

This API is used to configure backup migration tasks in three common scenarios.

Backup migration supports the following common scenarios:

Full migrations of backup files in OBS buckets
Full+incremental migrations of backup files in OBS buckets
Full migration of the RDS full backup

URI

POST /v5/{project_id}/backup-migration-jobs

**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.
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. The token is the value of X-Subject-Token in the response header.
X-Language	No	String	Request language type.

**Table 3** Request body parameters
Parameter	Mandatory	Type	Description
base_info	Yes	BackupJobBaseInfo object	Basic information body for creating a backup migration task.
target_db_info	Yes	BackupJobEndpointInfo object	RDS for SQL Server instance information to be restored for a backup migration task.
backup_info	Yes	BackupInfo object	Backup file information.
options	Yes	BackupRestoreOptionInfo object	Configuration parameters related to backup migration.

**Table 4** BackupJobBaseInfo
Parameter	Mandatory	Type	Description
name	Yes	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
engine_type	Yes	String	DB engine. - sqlserver: RDS for SQL Server
description	No	String	Task description.
tags	No	Array of ResourceTag objects	Tag information. A tag value can contain letters, digits, spaces, and the following characters: _.:/=+-@
enterprise_project_id	No	String	Enterprise project ID.

**Table 5** ResourceTag
Parameter	Mandatory	Type	Description
key	No	String	The tag key. The value can contain a maximum of 36 characters, including letters, digits, underscores (_), and hyphens (-).
value	No	String	The tag value. The value can contain letters, digits, spaces, and the following characters: _ . : / = + - @

**Table 6** BackupJobEndpointInfo
Parameter	Mandatory	Type	Description
target_instance_id	Yes	String	ID of the RDS for SQL Server instance to be restored for a backup migration task.
ms_file_stream_status	No	String	Whether FileStream is enabled for the destination instance. You can obtain the value from the API for querying RDS for SQL Server details.
file_id	No	String	ID of the RDS for SQL Server backup file. This parameter is mandatory when full RDS backup is used for restoration. You can obtain the value from the RDS backup management page.

**Table 7** BackupInfo
Parameter	Mandatory	Type	Description
file_source	Yes	String	Specifies the backup file source. Letters in the value must be in upper case. OBS: The backup file is from an OBS bucket. RDS: The backup file is a full backup of an RDS DB instance.
bucket_name	No	String	The OBS bucket name. This parameter is mandatory when the backup file in an OBS bucket is used for data restoration. The value can be 3 to 63 characters in length and can contain only lowercase letters, digits, hyphens (-), and periods (.). It must start and end with a letter or digit, and cannot be an IP address. You need to specify the bucket name. You can log in to OBS Browser and obtain the target bucket name from the OBS bucket list on the home page.
files	Yes	Array of BackupFileInfo objects	List of backup files.

**Table 8** BackupFileInfo
Parameter	Mandatory	Type	Description
name	Yes	String	Backup file name.
obs_path	No	String	File path in the OBS bucket. Mandatory in OBS scenarios. Default configuration in RDS scenarios.
rds_version	No	String	Database version of the backup file. Default configuration in OBS scenarios. Mandatory in RDS scenarios.
rds_source_instance_id	No	String	Instance to which the backup file belongs. Default configuration in OBS scenarios. Mandatory in RDS scenarios.

**Table 9** BackupRestoreOptionInfo
Parameter	Mandatory	Type	Description
is_cover	No	Boolean	Whether to overwrite the destination database. The default value is false. true: indicates the destination database is overwritten. false: indicates the destination database is not overwritten.
is_default_restore	No	Boolean	Whether to restore all databases by default. true: indicates all databases in the backup file are restored by default. false: indicates that you need to specify the name of the database to be restored in the db_names field.
is_last_backup	Yes	Boolean	A complete restoration process involves restoring several incremental backup files. The destination DB instance will not be available until the last backup file is restored. You can determine whether the selected backup file is the last one. Select Yes in either of the following scenarios: If you perform a one-time full migration only, set this parameter to true. If you perform an incremental migration and set the selected file as the last incremental backup file during a cutover migration, set this parameter to false.
is_precheck	Yes	Boolean	Whether to perform pre-verification. true: Perform a pre-verification. false: Do not perform a per-verification.
recovery_mode	Yes	String	Restoration mode. full: indicates a full migration. incre: indicates an incremental migration.
db_names	No	Array of strings	Database name.
reset_db_name_map	No	Map<String,String>	This field is a map. Currently, the format key is "", and value indicates the name of the new database. If you enable Reset Database Name, the original database names in the backup file will be reset to new database names. Constraints: The backup file contains only one database. The backup file is a full backup file and is the last backup file. Select Full for Backup File and Yes for Last Backup Type.
is_delete_backup_file	No	Boolean	Whether to delete the OBS backup file downloaded to the RDS for SQL Server disk when the backup file in the OBS bucket is used for restoration. By default, the backup file is deleted. true: indicates that the backup file is deleted. false: indicates that the backup file is not deleted.

Response Parameters

Status code: 200

**Table 10** Response body parameters
Parameter	Type	Description
job_id	String	Task ID.

Status code: 400

**Table 11** Response body parameters
Parameter	Type	Description
error_code	String	Error code.
error_msg	String	Error message.

Example Request

Full migration of backup files in OBS buckets.

https://{endpoint}/v5/054ba152d480d55b2f5dc0069e7ddef0/backup-migration-jobs

{
  "base_info" : {
    "name" : "DRS-7526",
    "engine_type" : "sqlserver",
    "enterprise_project_id" : "0",
    "description": "Destination RDS instance name: rds-sqlserver-2022-stand",
    "tags" : [ ]
  },
  "target_db_info" : {
    "target_instance_id" : "0a3182607bc549bcb46cc9a8755761a6in04",
    "ms_file_stream_status" : "off",
    "file_id" : ""
  },
  "backup_info" : {
    "file_source" : "OBS",
    "bucket_name" : "zyy-obs",
    "files" : [ {
      "name" : "1706510914000_0_Test_Database.bak",
      "obs_path" : ""
    } ]
  },
  "options" : {
    "is_cover" : true,
    "recovery_mode" : "full",
    "is_default_restore" : true,
    "is_last_backup" : true,
    "reset_db_name_map" : { },
    "is_precheck" : true,
    "is_delete_backup_file" : true,
    "db_names" : [ "" ]
  }
}

Migration using the RDS backup file.

https://{endpoint}/v5/054ba152d480d55b2f5dc0069e7ddef0/backup-migration-jobs

{
  "base_info" : {
    "name" : "DRS-7526",
    "engine_type" : "sqlserver",
    "enterprise_project_id" : "0",
    "description" : "miao'shu",
    "tags" : [ ]
  },
  "target_db_info" : {
    "target_instance_id" : "0a3182607bc549bcb46cc9a8755761a6in04",
    "ms_file_stream_status" : "off",
    "file_id" : "0d87037d934848999fdc10bbabb08e6fbr04"
  },
  "backup_info" : {
    "file_source" : "RDS",
    "files" : [ {
      "name" : "",
      "obs_path" : "",
      "rds_version" : "2019_EE",
      "rds_source_instance_id" : "7fb189b57339473a929d41dabb3878a2in04"
    } ]


  },
  "options" : {
    "is_precheck" : true,
    "recovery_mode" : "",
    "is_last_backup" : "",
    "reset_db_name_map" : {
      "db_test12" : "",
      "db_hailiang_schema" : "",
      "db_sqls2v5_01" : ""
    },
    "db_names" : [ "db_test12", "db_hailiang_schema", "db_sqls2v5_01" ]
  }
}

Full+incremental migration of backup files in OBS buckets.

Perform a full migration first with is_last_backup set to false.

https://{endpoint}/v5/054ba152d480d55b2f5dc0069e7ddef0/backup-migration-jobs

{
  "base_info" : {
    "name" : "DRS-7527",
    "engine_type" : "sqlserver",
    "enterprise_project_id" : "0",
    "description": "Description",
    "tags" : [ ]
  },
  "target_db_info" : {
    "target_instance_id" : "0a3182607bc549bcb46cc9a8755761a6in04",
    "ms_file_stream_status" : "off",
    "file_id" : ""
  },
  "backup_info" : {
    "file_source" : "OBS",
    "bucket_name" : "zyy-obs",
    "files" : [ {
      "name" : "ims.bak",
      "obs_path" : "floder/"
    } ]
  },
  "options" : {
    "is_cover" : true,
    "recovery_mode" : "full",
    "is_default_restore" : true,
    "is_last_backup" : false,
    "reset_db_name_map" : { },
    "is_precheck" : true,
    "is_delete_backup_file" : true,
    "db_names" : [ "" ]
  }
}

Full+incremental migration of backup files in OBS buckets.

After the full migration is complete, perform the incremental migration. If more than one incremental backup file exists, set is_last_backup to false.

https://{endpoint}/v5/054ba152d480d55b2f5dc0069e7ddef0/backup-migration-jobs

{
  "base_info" : {
    "name" : "DRS-7527",
    "engine_type" : "sqlserver",
    "enterprise_project_id" : "0",
    "description": "Description",
    "tags" : [ ]
  },
  "target_db_info" : {
    "target_instance_id" : "0a3182607bc549bcb46cc9a8755761a6in04",
    "ms_file_stream_status" : "off",
    "file_id" : ""
  },
  "backup_info" : {
    "file_source" : "OBS",
    "bucket_name" : "zyy-obs",
    "files" : [ {
      "name" : "ims_log1.bak",
      "obs_path" : "floder/"
    } ]
  },
  "options" : {
    "is_cover" : true,
    "recovery_mode" : "incre",
    "is_default_restore" : true,
    "is_last_backup" : false,
    "reset_db_name_map" : { },
    "is_precheck" : true,
    "is_delete_backup_file" : true,
    "db_names" : [ "" ]
  }
}

Full+incremental migration of backup files in OBS buckets.

Stop database services and perform the last incremental migration. Set is_last_backup to true.

https://{endpoint}/v5/054ba152d480d55b2f5dc0069e7ddef0/backup-migration-jobs

{
  "base_info" : {
    "name" : "DRS-7527",
    "engine_type" : "sqlserver",
    "enterprise_project_id" : "0",
    "description": "Description",
    "tags" : [ ]
  },
  "target_db_info" : {
    "target_instance_id" : "0a3182607bc549bcb46cc9a8755761a6in04",
    "ms_file_stream_status" : "off",
    "file_id" : ""
  },
  "backup_info" : {
    "file_source" : "OBS",
    "bucket_name" : "zyy-obs",
    "files" : [ {
      "name" : "ims_log2.bak",
      "obs_path" : "floder/"
    } ]
  },
  "options" : {
    "is_cover" : true,
    "recovery_mode" : "incre",
    "is_default_restore" : true,
    "is_last_backup" : true,
    "reset_db_name_map" : { },
    "is_precheck" : true,
    "is_delete_backup_file" : true,
    "db_names" : [ "" ]
  }
}

Example Response

Status code: 200

{
  "job_id" : "0667845a-6291-4e2a-95b0-190c0abjb703"
}

Status code: 400

Bad Request

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

Status Code

Status Code	Description
200	OK
400	Bad Request

Error Code

For details, see Error Code.

Parent topic: Backup Migration

Previous topic: Backup Migration

Next topic: Querying the Backup Migration Task List

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