Querying Full Backups

Function

This API is used to query backups according to search criteria. Before calling this API:

Learn how to authorize and authenticate it.
Obtain the required region and endpoint.

URI

GET /v3/{project_id}/backups

**Table 1** URI parameters
Parameter	Mandatory	Type	Description
project_id	Yes	String	Explanation: Project ID of a tenant in a region. To obtain this value, see Obtaining a Project ID. Constraints: None Value range: The value can contain 32 characters. Only letters and digits are allowed. Default value: None

**Table 2** Query parameters
Parameter	Mandatory	Type	Description
instance_id	No	String	Explanation: Instance ID, which uniquely identifies an instance. Constraints: None Value range: The value can contain 36 characters with a suffix of in07. Only letters and digits are allowed. Default value: None
backup_id	No	String	Explanation: Backup ID, which uniquely identifies a backup. Constraints: None Value range: The value can contain 36 characters with a suffix of br07. Only letters and digits are allowed. Default value: None
backup_type	No	String	Explanation: Backup type. Constraints: None Value range: auto: automated full backup manual: manual full backup Default value: None
offset	No	String	Explanation: Index offset. The query starts from the next piece of data indexed by this parameter. Constraints: The value must be an integer and cannot be a negative number. Value range: ≥0 Default value: 0
limit	No	String	Explanation: Number of records to be queried. Constraints: The value must be an integer and cannot be a negative number. Value range: 1–100 Default value: 100
begin_time	No	String	Explanation: Query start time in the "yyyy-mm-ddThh:mm:ssZ" format. T is the separator between the calendar and the hourly notation of time. Z indicates the time zone offset. For example, if the time zone offset is one hour, the value of Z is +0100. Constraints: None Value range: The time is earlier than the current time. Default value: None
end_time	No	String	Explanation: Query end time in the "yyyy-mm-ddThh:mm:ssZ" format. T is the separator between the calendar and the hourly notation of time. Z indicates the time zone offset. For example, if the time zone offset is one hour, the value of Z is +0100. Constraints: None Value range: The time is earlier than the current time and later than the start time. Default value: None
name	No	String	Explanation: Backup name. Constraints: None Value range: The name must start with a letter and consist of 4 to 64 characters. Only letters (case-sensitive), digits, hyphens (-), and underscores (_) are allowed. Default value: None
instance_name	No	String	Explanation: Instance name. Constraints: None Value range: The name must start with a letter and consist of 4 to 64 characters. Only letters (case-sensitive), digits, hyphens (-), and underscores (_) are allowed. Default value: None

Request Parameters

**Table 3** Request header parameters
Parameter	Mandatory	Type	Description
X-Auth-Token	Yes	String	Explanation: User token. It can be obtained by calling the IAM API used to obtain a user token. The value of X-Subject-Token in the response header is the token value. Constraints: None Value range: None Default value: None
X-Language	No	String	Explanation: Request language type. Constraints: None Value range: en-us zh-cn Default value: en-us

Response Parameters

Status code: 200

**Table 4** Response body parameters
Parameter	Type	Description
backups	Array of backups objects	Explanation: Backup information. Value range: None
total_count	Long	Explanation: Total number of backup files. Value range: ≥0

**Table 5** backups
Parameter	Type	Description
id	String	Explanation: Backup ID. Value range: The value can contain 36 characters with a suffix of br07. Only letters and digits are allowed.
name	String	Explanation: Backup name. Value range: The name must start with a letter and consist of 4 to 64 characters. Only letters (case-sensitive), digits, hyphens (-), and underscores (_) are allowed.
begin_time	String	Explanation: Backup start time in the "yyyy-mm-ddThh:mm:ssZ" format. T is the separator between the calendar and the hourly notation of time. Z indicates the time zone offset. For example, if the time zone offset is one hour, the value of Z is +0100. Value range: None
end_time	String	Explanation: Backup end time in the "yyyy-mm-ddThh:mm:ssZ" format. T is the separator between the calendar and the hourly notation of time. Z indicates the time zone offset. For example, if the time zone offset is one hour, the value of Z is +0100. Value range: None
status	String	Explanation: Backup status. Value range: BUILDING: Backup in progress COMPLETED: Backup completed FAILED: Backup failed AVAILABLE: Backup available
take_up_time	Integer	Explanation: Backup duration in minutes. Value range: ≥ 0
type	String	Explanation: Backup type. Value range: auto: automated full backup manual: manual full backup
size	Long	Explanation: Backup size in MB. Value range: ≥0
datastore	MysqlDatastore object	Explanation: Database information.
instance_id	String	Explanation: Instance ID, which uniquely identifies an instance. Value range: The value can contain 36 characters with a suffix of in07. Only letters and digits are allowed.
instance_name	String	Explanation: Instance name. Value range: The name must start with a letter and consist of 4 to 64 characters. Only letters (case-sensitive), digits, hyphens (-), and underscores (_) are allowed.
backup_level	String	Explanation: Backup level. This parameter is returned when the level-1 backup function is enabled. Value range: 0: Backup being created or creation failed 1: level-1 backup 2: level-2 backup
description	String	Explanation: Description of the backup file. Value range: None

**Table 6** MysqlDatastore
Parameter	Type	Description
type	String	Explanation: DB engine. Value range: gaussdb-mysql
version	String	Explanation: DB version. Value range: 8.0

Status code: 400

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

Status code: 500

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

Example Request

Querying automated backups generated from July 6, 2020 to July 16, 2020

GET https://{endpoint}/v3/97b026aa9cc4417888c14c84a1ad9860/backups?instance_id=43e4feaab48f11e89039fa163ebaa7e4br01&backup_id=c0c9f155c7b7423a9d30f0175998b63bbr01&backup_type=auto&offset=0&limit=10&begin_time=2020-07-06T10:41:14+0800&end_time=2020-07-16T10:41:14+0800

Example Response

Status code: 200

Success.

{
  "backups" : [ {
    "id" : "1fe4feaab48f11e6654hfa163eba87e4b66u",
    "name" : "GaussDBforMySQL-gauss-e747-20200705185048266",
    "begin_time" : "2018-08-06T12:41:14+0800",
    "end_time" : "2018-08-06T12:45:14+0800",
    "take_up_time" : 2,
    "status" : "COMPLETED",
    "type" : "auto",
    "size" : 2803,
    "datastore" : {
      "type" : "GaussDB(for MySQL)",
      "version" : "8.0"
    },
    "instance_id" : "43e4feaab48f11e89039fa163ebaa7e4br01",
    "instance_name" : "GaussDBforMySQL-gauss-e747",
    "backup_level" : "2"
  } ],
  "total_count" : 1
}