Updated on 2024-06-07 GMT+08:00

Querying Cross-Region Backups

Function

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

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

Constraints

Cross-region manual backups can be queried only for RDS for SQL Server.

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

    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_type

    Yes

    Specifies the backup type. Its value can be any of the following:

    • 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.

    backup_id

    No

    Specifies the backup ID.

    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 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.

    NOTE:

    When begin_time is not empty, end_time is mandatory.

    end_time

    No

    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.

    NOTE:

    When end_time is not empty, begin_time is mandatory.

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

    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

    Parameter

    Type

    Description

    id

    String

    Indicates the backup ID.

    name

    String

    Indicates the backup name.

    type

    String

    Indicates the backup type.

    Its value can be any of the following:

    • 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

    Indicates the backup size in KB.

    status

    String

    Indicates the backup status. Its value can be any of the following:

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

    databases

    Array of objects

    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

    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.

    end_time

    String

    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.

    datastore

    Object

    Indicates the database version.

    For details, see Table 5.

    instance_id

    String

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

    associated_with_ddm

    Boolean

    Indicates whether to associate with DDM. This parameter is returned only for RDS for MySQL DB instances.

    Table 4 databases field data structure description

    Name

    Type

    Description

    name

    String

    Indicates the name of the self-built database.

    Table 5 datastore field data structure description

    Name

    Type

    Description

    type

    String

    DB engine. Currently, only MySQL and Microsoft SQL Server are supported.

    version

    String

    DB engine version.

  • 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
    }
  • Abnormal Response

    For details, see Abnormal Request Results.

Status Code

Error Code

For details, see Error Codes.