Updated on 2024-03-28 GMT+08:00

Obtaining Backups

Function

This API is used to obtain backups of a DB instance.

  • Before calling an API, you need to understand the API in Authentication.

Constraints

This API is used to query full and incremental backups of DB instances.

URI

  • URI format

    GET /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}

  • Parameter description
    Table 1 Parameter description

    Name

    Mandatory

    Description

    project_id

    Yes

    Specifies the project ID of a tenant in a region.

    For details about how to obtain the project ID, see Obtaining a Project ID.

    instance_id

    Yes

    Specifies the DB instance ID.

    backup_id

    No

    Specifies the backup ID.

    backup_type

    No

    Specifies the backup type. Value:

    • auto: automated full backup
    • manual: manual full backup
    • fragment: differential full backup
    • incremental: automated incremental backup

    offset

    No

    Specifies the index position. If offset is set to N, the resource query starts from the N+1 piece of data. The value is 0 by default, indicating that the query starts from the first piece of data. The value cannot be a negative number.

    limit

    No

    Specifies the number of records to be queried. The default value is 100. The value cannot be a negative number. The minimum value is 1 and the maximum value is 100.

    begin_time

    No

    Specifies the start time for obtaining the backup list. The format of the start time is "yyyy-mm-ddThh:mm:ssZ".

    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.

    NOTE:

    When begin_time is not empty, end_time is mandatory.

    end_time

    No

    Specifies the end time for obtaining the backup list. The format of the end time 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 time zone offset is shown as +0800.

    NOTE:

    When end_time is not empty, begin_time is mandatory.

Request

  • Request parameters

    None

Response

  • Normal response
    Table 2 Parameter description

    Name

    Type

    Description

    backups

    Array of objects

    Indicates the backup list.

    For details, see Table 3.

    total_count

    Integer

    Indicates the total number of records.

    Table 3 backups field data structure description

    Name

    Type

    Description

    id

    String

    Indicates the backup ID.

    name

    String

    Indicates the backup name.

    type

    String

    Indicates the backup type. Value:

    • auto: automated full backup
    • manual: manual full backup
    • fragment: differential full backup
    • incremental: automated incremental backup

    size

    Long

    Indicates the backup size in KB.

    status

    String

    Indicates the backup status. Value:

    • BUILDING: Backup in progress
    • COMPLETED: Backup completed
    • FAILED: Backup failed
    • DELETING: Backup being deleted

    begin_time

    String

    Indicates the backup start time.

    • For a full backup, it indicates the full backup start time.
    • For an RDS for MySQL incremental backup, it indicates the time when the last transaction of the last incremental backup task is committed.

    The format is yyyy-mm-ddThh:mm:ssZ. T is the separator between the calendar and the hourly notation of time. Z indicates the time zone offset.

    end_time

    String

    Indicates the backup end time.

    • For a full backup, it indicates the full backup end time.
    • For an RDS for MySQL incremental backup, it indicates the time when the last transaction is committed.

    The format is yyyy-mm-ddThh:mm:ssZ. T is the separator between the calendar and the hourly notation of time. Z indicates the time zone offset.

    datastore

    Object

    Indicates the database version.

    For details, see Table 4.

    instance_id

    String

    Indicates the ID of the DB instance for which the backup is created.

    associated_with_ddm

    Boolean

    Indicates whether this instance is associated with a DDM instance.

    Table 4 datastore field data structure description

    Parameter

    Type

    Description

    type

    String

    Indicates the DB engine. Its value can be any of the following and is case-insensitive:

    • MySQL
    • PostgreSQL

    version

    String

    Indicates the database version.

  • Example normal response

    Obtaining all backups of an RDS for MySQL instance:

    {
    	"backups": [{
    		"id": "43e4feaab48f11e89039fa163ebaa7e4br01",
    		"name": "xxxx.xxx",
    		"type": "auto",
    		"size": 2803,
    		"status": "COMPLETED",
    		"begin_time": "2018-08-06T12:41:14+0800",
    		"end_time": "2018-08-06T12:43:14+0800",
    		"datastore": {
    			"type": "MySQL",
    			"version": "5.7"
    		},
    		"instance_id": "a48e43ff268f4c0e879652d65e63d0fbin01",
    		"associated_with_ddm": false
    	}],
    	"total_count": 1
    }

    Obtaining all backups of an RDS for PostgreSQL instance:

    {
    	"backups": [{
    		"id": "43e4feaab48f11e89039fa163ebaa7e4br03",
    		"name": "xxxx.xxx",
    		"type": "incremental",
    		"size": 2803,
    		"status": "COMPLETED",
    		"begin_time": "2018-08-06T12:41:14+0800",
    		"end_time": "2018-08-06T12:43:14+0800",
    		"datastore": {
    			"type": "PostgreSQL",
    			"version": "9.6"
    		},
    		"instance_id": "a48e43ff268f4c0e879652d65e63d0fbin03 ",
    		"associated_with_ddm": false
    	}],
    	"total_count": 1
    }
  • Abnormal response

    For details, see Abnormal Request Results.

Status Code

Error Code

For details, see Error Codes.