Querying Backups (v3.1)

Function

This API is used to query backups of an instance. Before calling this API:

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

Constraints

This API can be used to query only manual and automated full backups.

URI

GET /v3.1/{project_id}/backups?instance_id={instance_id}&backup_id={backup_id}&backup_type={backup_type}&offset={offset}&limit={limit}&begin_time={begin_time}&end_time={end_time}

**Table 1** Parameter description
Parameter	Mandatory	Type	Description
project_id	Yes	String	Definition Project ID of a tenant in a region. For details about how 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
instance_id	No	String	Definition Instance ID, which uniquely identifies an instance and is used to query the backups of an instance. Constraints This parameter is mandatory when you query log backups. Range The value is compliant with the UUID format and can contain 32 characters. Only letters and digits are allowed. Default Value N/A
backup_id	No	String	Definition Backup ID, which uniquely identifies an instance backup and is used to query information about a backup. Constraints N/A Range The value is compliant with the UUID format and can contain 36 characters. Only letters and digits are allowed. Default Value N/A
backup_type	No	String	Definition Backup type. Constraints N/A Range auto: instance-level automated full backup manual: instance-level manual full backup Default Value N/A
offset	No	Integer	Definition Index offset. The query starts from the next piece of data indexed by this parameter. Constraints N/A Range [0,10^10-1] Default Value 0: The query starts from the first data record.
limit	No	Integer	Definition Number of records to be queried. Constraints N/A Range [0,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, in the Beijing time zone, the offset is +0800. Example: 2022-05-09T16:01:10+0800. Constraints This parameter can be used together with end_time. If end_time is not used, the backups created after begin_time are returned. If end_time is used, the backups created between begin_time and end_time are returned. Range N/A Default Value N/A
end_time	No	String	Definition Query end time. The format is "yyyy-mm-ddThh:mm:ssZ" and the end time must be later than the start time. T is the separator between the calendar and the hourly notation of time. Z indicates the time zone offset. For example, in the Beijing time zone, the offset is +0800. Example: 2022-05-09T16:01:10+0800. Constraints This parameter can be used together with begin_time. If begin_time is not used, the backups created before end_time are returned. If begin_time is used, the backups created between begin_time and end_time are returned. Range N/A Default Value N/A

Request Parameters

None

Response Parameters

**Table 2** Parameter description
Parameter	Type	Description
backups	Array of objects	Definition Backup information. For details, see Table 3.
total_count	Long	Definition Total number of backup files. Range [0, 2^63 - 1]. The actual value depends on the number of backups in the backup list.

**Table 3** backups field data structure description
Parameter	Type	Description
id	String	Definition Backup ID, which uniquely identifies a backup. Range The value can contain 36 characters. Only letters and digits are allowed.
name	String	Definition Backup name. Range N/A
description	String	Definition Description of the backup file. Range The value can contain up to 256 characters but cannot contain carriage return characters. The following special characters are not 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, in the Beijing time zone, the time zone offset is shown as +0800. Example: 2022-05-09T16:01:10+0800. 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, in the Beijing time zone, the time zone offset is shown as +0800. Example: 2022-05-09T16:01:10+0800. Range N/A
status	String	Definition Backup status. Range BUILDING: Backup in progress COMPLETED: Backup completed FAILED: Backup failed
size	Double	Definition Backup size in MB. Range The value is determined by the backup size.
type	String	Definition Backup type. Range auto: instance-level automated full backup manual: instance-level manual full backup
datastore	Object	Definition Database information. For details, see Table 4.
instance_id	String	Definition ID of the instance to which the backup belongs. Range The value can contain 32 characters. Only letters and digits are allowed.

**Table 4** datastore field data structure description
Parameter	Type	Description
type	String	Definition DB engine. The value is case-insensitive and can be: GaussDB Range N/A
version	String	Definition DB engine version. If this parameter is not specified, the latest version is used by default. To query supported DB engine versions, see Querying DB Engine Versions. Range N/A

Example Request

Querying all backups

GET https://gaussdb-opengauss.ap-southeast-1.myhuaweicloud.com/v3.1/0483b6b16e954cb88930a360d2c4e663/backups

Querying instances based on search criteria

GET https://gaussdb-opengauss.ap-southeast-1.myhuaweicloud.com/v3.1/0483b6b16e954cb88930a360d2c4e663/backups?instance_id=88be33e4c5a64ceba42b42da89310111in14&backup_id=88be1234c5a64ceba42b42da89310111br14&backup_type=auto&begin_time=2022-05-09T16:15:50+0800&end_time=2022-05-09T16:20:45+0800&limit=1&offset=1

Example Response

Backups queried.

{
    "backups": [
        {
            "id": "a696cd25e4fc453aa503650225cece8bbr14",
            "name": "GaussDB-hly-ha-20220509080110906",
            "status": "FAILED",
            "size": 0.0,
            "type": "auto",
            "datastore": {
                "type": "GaussDB",
                "version": "1.4"
            },
            "begin_time": "2022-05-09T16:01:10+0800",
            "end_time": "2022-05-09T16:04:31+0800",
            
            "instance_id": "164abc6d35114095bb849d007b19db3bin14"
        },
        {
            "id": "5651c62a7f12461c98020dd3abfe24ccbr14",
            "name": "GaussDB-hly-master-20220509022658257",
            "status": "FAILED",
            "size": 0.0,
            "type": "auto",
            "datastore": {
                "type": "GaussDB",
                "version": "1.4"
            },
            "begin_time": "2022-05-09T10:26:58+0800",
            "end_time": "2022-05-09T10:30:17+0800",
            
            "instance_id": "fd26e3bf26e5467587eec857e4f66ef0in14"
        }
	],
    "total_count": 167
}