Querying Cross-Region Backups

Function

This API is used to obtain cross-region backups of an instance in the target backup region.

Before calling this API, learn how to authenticate it.
Before calling this API, learn about the request header parameters.

Authorization Information

Each account has all the permissions required to call all APIs, but IAM users must be assigned the required permissions.

If you are using role/policy-based authorization, see Permissions and Supported Actions for details on the required permissions.
If you are using identity policy-based authorization, the following identity policy-based permissions are required.

Action	Access Level	Resource Type (*: required)	Condition Key	Alias	Dependencies
rds:backup:list	list	-	-	-	-

Constraints

For RDS for SQL Server, automated full backups, manual backups, and automated incremental backups can be queried.

URI

URI format
GET /v3/{project_id}/offsite-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** Parameters
Parameter	Mandatory	Description
project_id	Yes	Definition Project ID of a tenant in a region. Constraints The value cannot be empty. Range To obtain the value, see Obtaining a Project ID. Default Value N/A
instance_id	Yes	Definition Instance ID. Constraints The value cannot be empty. Range You can obtain the value of this parameter from id in Table 4 by calling the API for querying DB instances. Default Value N/A
backup_type	Yes	Definition Backup type. Constraints N/A Range auto: indicates automated full backups and manual backups. Cross-region manual backups are supported only for RDS for SQL Server. incremental: indicates automated incremental backups. Default Value N/A
backup_id	No	Definition Backup ID. Constraints N/A Range N/A Default Value N/A
offset	No	Definition Index offset. Constraints If offset is set to N, the 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 must be a number but cannot be a negative number. Range An integer greater than or equal to 0 Default Value 0
limit	No	Definition Number of records returned by a query. Constraints The value cannot be a negative number. Range 1–100 Default Value 100
begin_time	No	Definition Specifies the start time for obtaining the cross-region 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. Constraints When begin_time is not empty, end_time is mandatory. Range N/A Default Value N/A
end_time	No	Definition Specifies the end time for obtaining the cross-region 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. Constraints When end_time is not empty, begin_time is mandatory. Range N/A Default Value N/A

Request

Request parameters
None

URI example
GET https://{endpoint}/v3/0483b6b16e954cb88930a360d2c4e663/offsite-backups?instance_id=43e4feaab48f11e89039fa163ebaa7e4br01&offset=0&limit=10&begin_time=2018-08-06T10:41:14+0800&end_time=2018-08-16T10:41:14+0800

Response

Normal response

**Table 2** Parameters
Parameter	Type	Description
backups	Array of objects	Definition Indicates the backup list. For details, see Table 3.
total_count	Integer	Definition Indicates the total number of records. Range N/A

**Table 3** backups field data structure description
Parameter	Type	Description
id	String	Definition Indicates the backup ID. Range N/A
name	String	Definition Indicates the backup name. Range N/A
type	String	Definition Indicates the backup type. Range auto: indicates automated full backups and manual backups. Cross-region manual backups are supported only for RDS for SQL Server. incremental: indicates automated incremental backups.
size	Long	Definition Indicates the backup size in KB. Range N/A
status	String	Definition Indicates the backup status. Range BUILDING: backup in progress COMPLETED: backup completed FAILED: backup failed DELETING: backup being deleted
databases	Array of objects	Definition Indicates the self-built database. This parameter is returned only for RDS for SQL Server DB instances. For details, see Table 4.
begin_time	String	Definition Indicates the 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. Range N/A
end_time	String	Definition Indicates the backup end time. For a full backup, it indicates the full backup end time. For an incremental backup, it indicates the time when the last transaction in the backup file was submitted. 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. For example, in the Beijing time zone, the time zone offset is shown as +0800. Range N/A
datastore	Object	Definition Indicates the database version. For details, see Table 5.
instance_id	String	Definition Indicates the ID of the DB instance for which the backup is created. Range N/A
associated_with_ddm	Boolean	Definition Indicates whether to associate with DDM. This parameter is returned only for RDS for MySQL DB instances. Range N/A

**Table 4** databases field data structure description
Parameter	Type	Description
name	String	Definition Indicates the name of the self-built database. Range N/A

**Table 5** datastore field data structure description
Parameter	Type	Description
type	String	Definition DB engine. Range MySQL PostgreSQL sqlserver
version	String	Definition DB engine version. Range N/A

Example normal response

MySQL:

{
	"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.6"
		},
		"instance_id": "a48e43ff268f4c0e879652d65e63d0fbin01",
                "associated_with_ddm": false
	}],
	"total_count": 1
}

PostgreSQL:

{
	"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": "PostgreSQL",
			"version": "9.6"
		},
		"instance_id": "a48e43ff268f4c0e879652d65e63d0fbin01"
	}],
	"total_count": 1
}

Microsoft SQL Server:

{
    "backups": [
        {
            "id": "d0ea632a5c32451dbdb157ef5c2ad3ecbr04", 
            "name": "sqlserver-rds-1784-20221202062025775", 
            "type": "auto", 
            "size": 5956, 
            "status": "COMPLETED", 
            "begin_time": "2022-12-02T06:20:25+0000", 
            "end_time": "2022-12-02T06:24:45+0000", 
            "datastore": {
                "type": "sqlserver", 
                "version": "2019_SE"
            }, 
            "instance_id": "ad4ee2b80adb430082d8336d7da2e14din04"
        }, 
        {
            "id": "07d6a8ab12304f9aa3f368a6cff21ac9br04", 
            "name": "backup-81f1", 
            "type": "auto", 
            "size": 773, 
            "status": "COMPLETED", 
            "begin_time": "2022-12-02T06:12:22+0000", 
            "end_time": "2022-12-02T06:16:37+0000", 
            "datastore": {
                "type": "sqlserver", 
                "version": "2019_SE"
            }, 
            "instance_id": "ad4ee2b80adb430082d8336d7da2e14din04"
        }
    ], 
    "total_count": 2
}