Querying Full Backups

Function

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

Learn how to 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	Definition Project ID of a tenant in a region. To obtain this value, see Obtaining a Project ID. Constraints N/A Range The value contains 32 characters. Only letters and digits are allowed. Default Value N/A

**Table 2** Query parameters
Parameter	Mandatory	Type	Description
instance_id	No	String	Definition Instance ID, which uniquely identifies an instance. Constraints N/A Range The value contains 36 characters with a suffix of in07. Only letters and digits are allowed. Default Value N/A
backup_id	No	String	Definition Backup ID, which uniquely identifies a backup. Constraints N/A Range The value contains 36 characters with a suffix of br07. Only letters and digits are allowed. Default Value N/A
backup_type	No	String	Definition Backup type. Constraints N/A Range auto: automated full backup manual: manual full backup Default Value N/A
offset	No	String	Definition 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. Range ≥ 0 Default Value 0
limit	No	String	Definition Number of records to be queried. Constraints The value must be an integer and cannot be a negative number. Range 1–100 Default Value 100
begin_time	No	String	Definition 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 N/A Range The time is earlier than the current time. Default Value N/A
end_time	No	String	Definition 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 N/A Range The time is earlier than the current time and later than the start time. Default Value N/A
name	No	String	Definition Backup name. Constraints N/A 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 N/A
instance_name	No	String	Definition Instance name. Constraints N/A 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 N/A

Request Parameters

**Table 3** Request header parameters
Parameter	Mandatory	Type	Description
X-Auth-Token	Yes	String	Definition User token. To obtain this value, call the IAM API for obtaining a user token. The value of X-Subject-Token in the response header is the token value. Constraints N/A Range N/A Default Value N/A
X-Language	No	String	Definition Request language type. Constraints N/A 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	Definition Backup information. Range N/A
total_count	Long	Definition Total number of backup files. Range ≥ 0

**Table 5** backups
Parameter	Type	Description
id	String	Definition Backup ID. Range The value contains 36 characters with a suffix of br07. Only letters and digits are allowed.
name	String	Definition Backup name. 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	Definition 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. Range N/A
end_time	String	Definition 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. Range N/A
status	String	Definition Backup status. Range BUILDING: backup in progress COMPLETED: backup completed FAILED: backup failed AVAILABLE: backup available
take_up_time	Integer	Definition Backup duration in minutes. Range ≥ 0
type	String	Definition Backup type. Range auto: automated full backup manual: manual full backup
size	Long	Definition Backup size in MB. Range ≥ 0
datastore	MysqlDatastore object	Definition Database information.
instance_id	String	Definition Instance ID, which uniquely identifies an instance. Range The value contains 36 characters with a suffix of in07. Only letters and digits are allowed.
instance_name	String	Definition Instance name. 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	Definition Backup level. This parameter is returned when level-1 backup is enabled. Range 0: Backup being created or creation failed 1: level-1 backup 2: level-2 backup
description	String	Definition Description of the backup file. Range N/A

**Table 6** MysqlDatastore
Parameter	Type	Description
type	String	Definition DB engine. Range gaussdb-mysql
version	String	Definition DB version. 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" : "TaurusDB-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" : "TaurusDB-gauss-e747",
    "backup_level" : "2"
  } ],
  "total_count" : 1
}

Status Code

For details, see Status Codes.

Error Code

For details, see Error Codes.

Parent topic: Backup Management

Previous topic: Creating a Manual Backup

Next topic: Querying an Automated Backup Policy