DescribeBackups - ApsaraDB RDS - Alibaba Cloud Documentation Center

Queries the backup sets of an instance.

Operation Description

NoteA backup set can be used to restore data only when BackupStatus of the backup set is Success.

Authorization information

The following table shows the authorization information corresponding to the API. The authorization information can be used in the Action policy element to grant a RAM user or RAM role the permissions to call this API operation. Description:

Operation: the value that you can use in the Action element to specify the operation on a resource.
Access level: the access level of each operation. The levels are read, write, and list.
Resource type: the type of the resource on which you can authorize the RAM user or the RAM role to perform the operation. Take note of the following items:
- The required resource types are displayed in bold characters.
- If the permissions cannot be granted at the resource level, All Resources is used in the Resource type column of the operation.
Condition Key: the condition key that is defined by the cloud service.
Associated operation: other operations that the RAM user or the RAM role must have permissions to perform to complete the operation. To complete the operation, the RAM user or the RAM role must have the permissions to perform the associated operations.

Operation	Access level	Resource type	Condition key	Associated operation
rds:DescribeBackups	READ	RDS acs:rds::{#accountId}:dbinstance/ RDS acs:rds:{#regionId}:{#accountId}:dbinstance/{#dbinstanceId}	rds:ResourceTag	none

Request parameters

Parameter	Type	Required	Description	Example
DBInstanceId	string	Yes	The ID of the instance.	rm-uf6wjk5xxxxxxx
BackupId	string	No	The ID of the backup set.	327329803
BackupStatus	string	No	The status of the backup set. Valid values: Success Failed	Success
BackupMode	string	No	The backup mode. Valid values: Automated Manual	Automated
StartTime	string	No	The beginning of the time range to query. Specify the time in the ISO 8601 standard in the yyyy-MM-ddTHH:mmZ format. The time must be in UTC.	2011-06-01T16:00Z
EndTime	string	No	The end of the time range to query. The end time must be later than the start time. Specify the time in the ISO 8601 standard in the yyyy-MM-ddTHH:mmZ format. The time must be in UTC. NoteWe recommend that you specify a time range that is as short as possible to avoid timeout.	2011-06-15T16:00Z
PageSize	integer	No	The number of entries to return on each page. Valid values: 30 50 100 Default value: 30.	30
PageNumber	integer	No	The number of the page to return. Valid values: any non-zero positive integer. Default value: 1.	1
BackupType	string	No	The backup type. Valid values: FullBackup: full backup IncrementalBackup: incremental backup	FullBackup
ResourceGroupId	string	No	The ID of the resource group.	rg-acfmy*****

Response parameters

Parameter	Type	Description	Example
	object	The response parameters.
RequestId	string	The ID of the request.	1A6D328C-84B8-40DC-BF49-6C73984D7494
TotalEcsSnapshotSize	long	The size of the snapshot chain of the instance. Unit: bytes.	0
PageRecordCount	string	The number of backup sets on the current page.	30
TotalRecordCount	string	The total number of entries returned.	100
PageNumber	string	The page number of the returned page.	1
Items	array	An array that consists of the details of the returned backup sets.
	object
StorageClass	string	The storage class of the backup set. Valid values: 0: regular storage 1: archive storage	0
Encryption	string	The encryption information about the backup set.	{}
BackupStatus	string	The status of the backup set.	Success
StoreStatus	string	Indicates whether the backup set can be deleted. Valid values: Enabled: The backup set can be deleted. Disabled: The backup set cannot be deleted.	Disabled
ConsistentTime	long	The point in time at which the data in the backup set is consistent. The return value of this parameter is a timestamp. NoteIf the instance runs MySQL 5.6, a timestamp is returned. Otherwise, the value 0 is returned.	1576506856
BackupType	string	The backup type of the backup set. Valid values: FullBackup: full backup IncrementalBackup: incremental backup	FullBackup
CopyOnlyBackup	string	The backup mode of the backup set. Valid values: 0: the standard mode. This mode supports full backups and incremental backups. 1: the copy-only mode. This mode supports only full backups. NoteThis parameter is returned only when the instance runs SQL Server.	0
BackupEndTime	string	The end time of the backup task. The time follows the ISO 8601 standard in the yyyy-MM-ddTHH:mmZ format. The time is displayed in UTC.	2019-02-13T12:20:00Z
MetaStatus	string	The status of the backup set that is used to restore individual databases or tables. Valid values: OK: The backup set is normal. LARGE: The backup set contains an abnormally large number of tables. It cannot be used to restore individual databases or tables. EMPTY: The backup set is generated from a failed backup task. NoteIf an empty string is returned, the backup set cannot be used to restore individual databases or tables.	OK
BackupInitiator	string	The initiator of the backup task. Valid values: System User	System
BackupIntranetDownloadURL	string	The URL that is used to download the backup set over an internal network. If the backup set cannot be downloaded, null is returned. NoteFor example, if BackupMethod of an ApsaraDB RDS for SQL Server instance is set to Snapshot, a null string is returned.	http://rdsbak-hz-v3.oss-cn-hangzhou-internal.aliyuncs.com/xxxxx
BackupMethod	string	The method that is used to generate the backup set. Valid values: Logical: logical backup Physical: physical backup Snapshot: snapshot backup	Physical
BackupStartTime	string	The start time of the backup task. The time follows the ISO 8601 standard in the yyyy-MM-ddTHH:mmZ format. The time is displayed in UTC.	2019-02-03T12:20:00Z
BackupDownloadURL	string	The URL that is used to download the backup set over the Internet. If the backup set cannot be downloaded, null is returned. NoteFor example, if BackupMethod of an ApsaraDB RDS for SQL Server instance is set to Snapshot, a null string is returned.	http://rdsbak-hz-v3.oss-cn-hangzhou.aliyuncs.com/xxxxx
IsAvail	integer	Indicates whether the backup set is available. Valid values: 0: The backup set is unavailable. 1: The backup set is available.	1
BackupId	string	The ID of the backup set.	321020562
HostInstanceID	string	The No. of the instance that generates the backup set. This parameter is used to indicate whether the instance that generates the backup set is a primary instance or a secondary instance.	5882781
BackupSize	long	The backup size. Unit: bytes.	2167808
BackupMode	string	The backup mode of the backup set. Valid values: Automated Manual	Automated
DBInstanceId	string	The ID of the instance	rm-uf6wjk5xxxxxxx
Checksum	string	The checksum. The value of this parameter is calculated by using the CRC64 algorithm.	1835830439**********
BackupDownloadLinkByDB	array	An array consisting of URLs from which you can download backup sets of individual databases.
	object
IntranetDownloadLink	string	The internal URL from which you can download the backup set.	https://cn-hangzhou-internal.bak.rds.aliyuncs.com/custins53664665/hins18676859_2021072909473127987849.zip?Expires=*****&dbList=tb1
DataBase	string	The name of the database.	dbs
DownloadLink	string	The public URL from which you can download the backup set.	https://cn-hangzhou.bak.rds.aliyuncs.com/custins53664665/hins18676859_2021072909473127987849.zip?Expires=*****&dbList=tb1
ResourceGroupId	string	The ID of the resource group.	rg-acfmy*****

Examples

Sample success responses

JSONformat

{
  "RequestId": "1A6D328C-84B8-40DC-BF49-6C73984D7494",
  "TotalEcsSnapshotSize": 0,
  "PageRecordCount": "30",
  "TotalRecordCount": "100",
  "PageNumber": "1",
  "Items": {
    "Backup": [
      {
        "StorageClass": "0",
        "Encryption": "{}",
        "BackupStatus": "Success",
        "StoreStatus": "Disabled",
        "ConsistentTime": 1576506856,
        "BackupType": "FullBackup",
        "CopyOnlyBackup": "0",
        "BackupEndTime": "2019-02-13T12:20:00Z",
        "MetaStatus": "OK",
        "BackupInitiator": "System",
        "BackupIntranetDownloadURL": "http://rdsbak-hz-v3.oss-cn-hangzhou-internal.aliyuncs.com/xxxxx",
        "BackupMethod": "Physical",
        "BackupStartTime": "2019-02-03T12:20:00Z",
        "BackupDownloadURL": "http://rdsbak-hz-v3.oss-cn-hangzhou.aliyuncs.com/xxxxx",
        "IsAvail": 1,
        "BackupId": "321020562",
        "HostInstanceID": "5882781",
        "BackupSize": 2167808,
        "BackupMode": "Automated",
        "DBInstanceId": "rm-uf6wjk5xxxxxxx",
        "Checksum": "1835830439**********",
        "BackupDownloadLinkByDB": {
          "BackupDownloadLinkByDB": [
            {
              "IntranetDownloadLink": "https://cn-hangzhou-internal.bak.rds.aliyuncs.com/custins53664665/hins18676859_2021072909473127987849.zip?Expires=*****&dbList=tb1",
              "DataBase": "dbs",
              "DownloadLink": "https://cn-hangzhou.bak.rds.aliyuncs.com/custins53664665/hins18676859_2021072909473127987849.zip?Expires=*****&dbList=tb1"
            }
          ]
        },
        "ResourceGroupId": "rg-acfmy*****"
      }
    ]
  }
}

Error codes

HTTP status code	Error code	Error message	Description
400	InvalidRestoreTime.Malformed	The requested restoreTime param is invalid, or the requested restoreTime is not within the scope of the instance backup.	-
400	InvalidPageNumbers.Malformed	Specified page number is not valid.	The page number cannot be found.
400	InvalidStartTime.Format	Specified start time is not valid.	The start time is invalid.
400	InvalidEndTime.Format	Specified end time is not valid.	The end time is invalid. Check the end time.
400	InvalidParameterCombination	The end time must be greater than the start time	The end time must be later than the start time.
400	InvalidDBinstanceClass.ValueNotSupported	The specified parameter DBinstanceClass is invalid.	The specified parameter DBinstanceClass is invalid.
400	InvalidBackupSetLocation.Format	Specified backup set location is not valid.	-
403	InvalidMaxRecordsPerPage.Malformed	Specified record number is not valid.	-
403	IncorrectDBInstanceState	Current DB instance state does not support this operation.	-
404	InvalidDBInstanceName.NotFound	The database instance does not exist.	The name of the RDS instance cannot be found. Check the name of the RDS instance.
404	InvalidDBInstance.NotFound	The specified instance does not exist or is not supported.	The RDS instance cannot be found. Check the ID or name of the RDS instance.

For a list of error codes, visit the Service error codes.

Change history

Change time

Summary of changes

Operation

2021-10-21

The response structure of the API operation changes.

Change item	Change content
Output Parameters	The response structure of the API operation changes.