Help Center/ GaussDB/ API Reference/ APIs (Recommended)/ Backup and Restoration/ Configuring the Automated Backup Policy for Instances in Batches

Updated on 2025-10-20 GMT+08:00

View PDF

Configuring the Automated Backup Policy for Instances in Batches

Function

This API is used to configure the automated backup policy for instances in batches. Before calling this API:

Learn how to authenticate this API.
Obtain the required region and endpoint.

Debugging

You can debug this API in API Explorer.

URI

PUT /v3/{project_id}/backups/policy

**Table 1** Parameter description
Parameter	Mandatory	Description
project_id	Yes	Definition Project ID of a tenant in a region. To obtain the value, see Obtaining a Project ID. Constraints N/A Range The value can contain 32 characters. Only letters and digits are allowed. Default Value N/A

Request Parameters

**Table 2** Request header parameters
Parameter	Mandatory	Type	Description
X-Auth-Token	Yes	String	Definition User token. You can obtain the token by calling the IAM API used to obtain a user token. After the request is processed, the value of X-Subject-Token in the message header is the token value. Constraints N/A Range N/A Default Value N/A
X-Language	No	String	Definition Language. Constraints N/A Range zh-cn en-us Default Value en-us

**Table 3** Parameter description
Parameter	Mandatory	Type	Description
instance_ids	Yes	Array of strings	Definition Instance IDs. Constraints The value must be in UUID format, exactly 36 characters long, and contain only letters and digits.
backup_policy	Yes	Object	Definition Backup policy information. Constraints N/A

**Table 4** backup_policy field data structure description
Parameter	Mandatory	Type	Description
keep_days	No	Integer	Definition Backup retention days. Constraints N/A Range 1 to 732 days To extend the retention period, contact customer service. Automated backups can be retained for up to 36,500 days. Default Value N/A
start_time	No	String	Definition Backup time window. Automated backups will be created during the backup time window. Constraints This parameter indicates the time period (in UTC) during which a backup is performed. For example, if the local backup time is 05:00-06:00 and the time zone is UTC+08:00, set the parameter value to 21:00-22:00. If the time zone is UTC+04:00, set the value to 01:00-02:00. If you set start_time, you are advised to also set period before finalizing the modification to avoid an unexpected backup time window and period in your local time zone. Range The value cannot be left blank. It must be a valid value in the hh:mm-HH:MM format. The current time is the UTC time. The value of HH must be 1 greater than the value of hh. The values of mm and MM must be the same and must be 00. Example value: 21:00-22:00 Default Value N/A
period	No	String	Definition Full backup period. An automated full backup is performed on the UTC date of each week. Constraints This parameter indicates the date (in UTC) when a backup is performed. For example, if the local backup time is 05:00–06:00 on Monday and Tuesday, and the time zone is UTC+08:00, set the parameter value to 1,7. If the time zone is UTC+04:00, set the value to 1,2. If you set period, you are advised to also set start_time before finalizing the modification to avoid an unexpected backup time window and period in your local time zone. Range 1–7. The numbers are separated by commas (,), indicating the days of the week. Example value: 1,2,3,4 indicates that the backup period is Monday, Tuesday, Wednesday, and Thursday. 1,2,3,4,5,6,7 indicates that an automated backup is performed every day from Monday to Sunday. 1,3,5 indicates that an automated backup is performed on Monday, Wednesday, and Friday. Default Value N/A
differential_period	No	String	Definition Interval for automated differential backups. Constraints N/A Range The value can be 15, 30, 60, 180, 360, 720, or 1440 minutes. Default Value N/A
rate_limit	No	Integer	Definition Bandwidth for backing up data. The upload speed is related to the bandwidth. Constraints N/A Range 0–1024 MB/s. The value 0 indicates no limit. Default Value 75MB/s
prefetch_block	No	Integer	Definition Number of prefetch pages from the modified pages in the disk table file during a differential backup. When modified pages are adjacent (for example, with a bulk data load), you can set this parameter to a large value. When modified pages are scattered (for example, random update), you can set this parameter to a small value. Constraints N/A Range 1~8192 Default Value 64
file_split_size	No	Integer	Definition Size by which full and differential backup files are split. Constraints The value must be a multiple of 4. Range 0–1024 GB. 0 GB indicates that the size is not limited. Default Value 4GB
enable_standby_backup	No	Boolean	Definition Whether to enable backup on a standby node. Constraints It is not suitable for single-node instances and instances earlier than V2.0-3.100.0. Range true: This function is enabled. false: This function is disabled. Default Value N/A

Response Parameters

**Table 5** Response Parameters
Parameter	Type	Description
succeeded_num	Integer	Definition Number of instances for which the backup policy is successfully configured. Range N/A
failed_num	Integer	Definition Number of instances for which the backup policy configuration failed. Range N/A
failed_instances	Array of objects	Definition Information about the instances for which the backup policy configuration failed. For details, see Table 6.

**Table 6** Data structure description for the failed_instances field
Parameter	Type	Description
instance_id	String	Definition Instance ID, which uniquely identifies an instance. Range N/A
error_message	String	Definition Error message. Range N/A

Example Request

Configuring the backup policy for GaussDB instances in batches (with a backup retention period of seven days and a backup time window of 19:00–20:00)

PUT https://gaussdb-opengauss.ap-southeast-1.myhuaweicloud.com/v3/0483b6b16e954cb88930a360d2c4e66/backups/policy
{
	"instance_ids" : [ "cc0ae5c47bf94834bf9e44138f7f995ain14", "aa0ae5c47bf94834bf9e44138f7f995ain14" ], 
	"backup_policy": {
		"keep_days": 7,
		"start_time": "19:00-20:00",
		"period": "1,2,3,4,5",
		"differential_period": "30",
  "rate_limit": 75 ,
  "prefetch_block": 64 ,
  "file_split_size": 4 ,
  "enable_standby_backup" : false
 }
}

Example Response

{ 
  "succeeded_num" : 1, 
  "failed_num" : 1, 
  "failed_instances" : [{
    "instance_id" : "14fc6c06d7e842829ee91d11c6b88b3ain01",
    "error_message": ["This operation cannot be performed because the instance status is abnormal."]
 }]
}