You can call the DescribeBackups operation to query the data backup files of an ApsaraDB RDS instance.

Note A data backup file can be used to restore data only when the BackupStatus parameter of the data backup file is Success.

Debugging

OpenAPI Explorer automatically calculates the signature value. For your convenience, we recommend that you call this operation in OpenAPI Explorer. OpenAPI Explorer dynamically generates the sample code of the operation for different SDKs.

Request parameters

Parameter Type Required Example Description
Action String Yes DescribeBackups

The operation that you want to perform. Set the value to DescribeBackups.

DBInstanceId String Yes rm-uf6wjk5xxxxxxx

The ID of the instance.

BackupId String No 327329803

The ID of the specific data backup file.

BackupStatus String No Success

The statuses of the data backup files. Valid values:

  • Success
  • Failed
BackupMode String No Automated

The mode is based on which the data backup files are generated. Valid values:

  • Automated
  • Manual
StartTime String No 2011-06-01T16:00Z

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.

EndTime String No 2011-06-15T16:00Z

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.

PageSize Integer No 30

The number of entries to return on each page. Valid values:

  • 30
  • 50
  • 100

Default value: 30.

PageNumber Integer No 1

The number of the page to return. Valid values: any non-zero positive integer.

Default value: 1.

Response parameters

Parameter Type Example Description
TotalRecordCount String 100

The total number of entries returned.

PageNumber String 1

The page number of the returned page.

PageRecordCount String 30

The number of data backup files on the page.

Items Array of Backup

An array that consists of data backup files.

Backup
BackupId String 321020562

The ID of the specific data backup file.

DBInstanceId String rm-uf6wjk5xxxxxxx

The ID of the instance.

HostInstanceID String 5882781

The ID of the instance that generates the data backup file. This parameter is used to indicate whether the primary instance or secondary instance generates the data backup file.

BackupStatus String Success

The status of the specific data backup file

BackupStartTime String 2019-02-03T12:20:00Z

The start time of the backup task that generated the specific data backup file. The time follows the ISO 8601 standard in the yyyy-MM-ddTHH:mmZ format. The time must be in UTC.

BackupEndTime String 2019-02-13T12:20:00Z

The end time of the backup task that generated the specific data backup file. The time follows the ISO 8601 standard in the yyyy-MM-ddTHH:mmZ format. The time must be in UTC.

BackupType String FullBackup

The type of backup that was performed to generate the specific data backup file. Valid values:

  • FullBackup
  • IncrementalBackup
BackupMode String Automated

The mode based on which the specific data backup file was generated. Valid values:

  • Automated
  • Manual
BackupMethod String Physical

The method that is used to generate the specific data backup file. Valid values:

  • Logical: logical backup
  • Physical: physical backup
  • Snapshot: snapshot backup
BackupDownloadURL String http://rdsbak-hz-v3.oss-cn-hangzhou.aliyuncs.com/xxxxx

The URL from which the specific data backup file can be downloaded over the Internet. If the data backup file cannot be downloaded over the Internet, a null string is returned.

Note For example, if the instance runs SQL Server and the BackupMethod parameter is set to Snapshot, a null string is returned.
BackupIntranetDownloadURL String http://rdsbak-hz-v3.oss-cn-hangzhou-internal.aliyuncs.com/xxxxx

The URL from which the specific data backup file can be downloaded over an internal network. If the data backup file cannot be downloaded over an internal network, a null string is returned.

Note For example, if the instance runs SQL Server and you set the BackupMethod parameter to Snapshot, a null string is returned.
BackupSize Long 2167808

The size of the specific data backup file. Unit: bytes.

StoreStatus String Disabled

Indicates whether the data backup file can be deleted. Valid values:

  • Enabled: The data backup file can be deleted.
  • Disabled: The data backup file cannot be deleted.
BackupDownloadLinkByDB Array of BackupDownloadLinkByDB

The URL from which you can download the specific data backup file of the individual database.

BackupDownloadLinkByDB
DataBase String dbs

The name of the database.

DownloadLink String https://cn-hangzhou.bak.rds.aliyuncs.com/custins53664665/hins18676859_2021072909473127987849.zip?Expires=*****&dbList=tb1

The public URL from which you can download the specific data backup file.

IntranetDownloadLink String https://cn-hangzhou-internal.bak.rds.aliyuncs.com/custins53664665/hins18676859_2021072909473127987849.zip?Expires=*****&dbList=tb1

The internal URL from which you can download the specific data backup file.

BackupInitiator String System

The initiator of the backup task generated the specific data backup file. Valid values:

  • System
  • User
ConsistentTime Long 1576506856

The point in time at which the data in the specific data backup file is consistent. The return value of this parameter is a timestamp.

Note If the instance runs MySQL 5.6, a timestamp is returned. Otherwise, the value 0 is returned.
CopyOnlyBackup String 0

The mode that is used to generate the specific data backup file. 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.
    Note This parameter is returned only when the instance runs SQL Server.
Encryption String null

The encrypted information of the specific data backup file.

IsAvail Integer 1

Indicates whether the specific data backup file is available. Valid values:

  • 0: The data backup file is unavailable.
  • 1: The data backup file is available.
MetaStatus String OK

The status of the specific data backup file that is used to restore individual databases and tables. Valid values:

  • OK: The data backup file is normal.
  • LARGE: The data backup filet contains an abnormally large number of tables. It cannot be used to restore individual databases or tables.
  • EMPTY: The data backup file is generated from a failed backup task.
Note If a null string is returned, the specific data backup file does not support the restoration of individual databases or tables.
StorageClass String 0

The storage media is used to store the backup file. Valid values:

  • 0: regular storage
  • 1: archive storage
RequestId String 1A6D328C-84B8-40DC-BF49-6C73984D7494

The ID of the request.

TotalEcsSnapshotSize Long 0

The size of the snapshot chain of the instance. Unit: bytes.

Examples

Sample requests

http(s)://rds.aliyuncs.com/?Action=DescribeBackups
&DBInstanceId=rm-uf6wjk5xxxxxxx
&<Common request parameters>

Sample success responses

XML format 

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

JSON format 

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

Error codes

For a list of error codes, visit the API Error Center.