Querying Backups (v3)

Function

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

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

Constraints

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

URI

GET https://{Endpoint}/v3/{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	Explanation: Project ID of a tenant in a region. For details about how to obtain the value, see Obtaining a Project ID. Restrictions: None Value range: The value can contain 32 characters. Only letters and digits are allowed. Default value: None
instance_id	No	String	Explanation: Instance ID, which uniquely identifies an instance and is used to query the backups of an instance. Restrictions: None Value range: The value can contain 32 characters. Only letters and digits are allowed. Default value: None
backup_id	No	String	Explanation: Backup ID, which uniquely identifies an instance backup and is used to query information about a backup. Restrictions: None Value range: The value is compliant with the UUID format and can contain 36 characters. Only letters and digits are allowed. Default value: None
backup_type	No	String	Explanation: Backup type, which is used to query a certain type of backup. Restrictions: None Value range: auto: automated full backup manual: manual full backup Default value: None
offset	No	Integer	Explanation: Index offset. The query starts from the next piece of data indexed by this parameter. Restrictions: None Value range: [0, 10^10-1] Default value: 0 (indicating that the query starts from the first data record.)
limit	No	Integer	Explanation: Number of records to be queried. Restrictions: None Value range: [0, 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 calendar and 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. Restrictions: 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. Value range: None Default value: None
end_time	No	String	Explanation: 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 calendar and 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. Restrictions: 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. Value range: None Default value: None

Request Parameters

None

Response Parameters

**Table 2** Response parameters
Parameter	Type	Description
backups	Array of objects	Explanation: Backup information. For details, see Table 3.
total_count	Long	Explanation: Total number of backup files. Value 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	Explanation: Backup ID. Value range: The value can contain 36 characters. Only letters and digits are allowed.
name	String	Explanation: Backup name. Value range: None
description	String	Explanation: Description of the backup file. Value 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	Explanation: Backup start time in the "yyyy-mm-ddThh:mm:ssZ" format. T is the separator between calendar and 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. Value range: None
end_time	String	Explanation: Backup end time in the "yyyy-mm-ddThh:mm:ssZ" format. T is the separator between calendar and 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. Value range: None
status	String	Explanation: Backup status. Value range: BUILDING: Backup in progress COMPLETED: Backup completed FAILED: Backup failed
size	Double	Explanation: Backup size in MB. Value range: The value is determined by the backup size.
type	String	Explanation: Backup type. Value range: auto: automated full backup manual: manual full backup
datastore	Object	Explanation: Database information. For details, see Table 4.
instance_id	String	Explanation: ID of the instance to which the backup belongs. Value 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	Explanation: DB engine. The value is case-insensitive and can be: GaussDB Value range: None
version	String	Explanation: 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. 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. Value range: None

Example Request

Querying all backups

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

Querying instances based on search criteria

https://gaussdb-opengauss.ap-southeast-1.myhuaweicloud.com/v3/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": [
        {
            "id": "a696cd25e4fc453aa503650225cece8bbr14",
            "name": "GaussDB-hly-ha-20220509080110906",
            "description": null,
            "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",
            "description": null,
            "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
}