Help Center> Document Database Service> API Reference> APIs V3.0 (Recommended)> Backup and Restoration> Querying the Backup List
Updated on 2022-12-12 GMT+08:00
View PDF

Querying the Backup List

Description

This API is used to query backups based on specified conditions.

URI

  • URI format

    GET https://{Endpoint}/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}&mode={mode}

  • URI example

    https://dds.ap-southeast-1.myhuaweicloud.com/v3/97b026aa9cc4417888c14c84a1ad9860/backups?instance_id=c0c9f155c7b7423a9d30f0175998b63bin01&offset=0&limit=10&begin_time=2018-08-06 10:41:14&end_time=2018-08-16 10:41:14

Table 1 Parameter description

Name

Type

Mandatory

Description

x-auth-token

string

Yes

User token

project_id

string

Yes

The project ID of a tenant in a region. To obtain the project ID, see Obtaining a Project ID.

instance_id

string

No

The instance ID, which can be obtained by calling the API for querying instances. If you do not have an instance, you can call the API used for creating an instance.

backup_id

string

No

Backup ID.

If the backup ID belongs to an automated incremental backup, the instance ID must be specified.

backup_type

string

No

Backup type.

  • Auto: indicates automated full backup.
  • Manual indicates manual full backup.
  • Incremental: indicates automated incremental backup.
  • If this parameter is not transferred, all full backups, including automated and manual full backups, are queried by default. When the value of this field is Incremental, the instance ID must be transferred.

offset

Integer

No

The index position. The query starts from the next instance creation time indexed by this parameter under a specified project. If offset is set to N, the resource query starts from the N+1 piece of data.

The value must be greater than or equal to 0. If this parameter is not transferred, offset is set to 0 by default, indicating that the query starts from the latest created DB instance.

limit

Integer

No

The maximum allowed number of backups to be queried.

The value ranges from 1 to 100. If this parameter is not transferred, the first 100 DB instances are queried by default.

begin_time

string

No

The start time of the query. The format is yyyy-mm-dd hh:mm:ss. The value is in UTC format.

NOTE:

When end_time is not empty, begin_time is mandatory.

end_time

string

No

Specifies the end time of the query. The format is "yyyy-mm-dd hh:mm:ss". The value is in UTC format.

NOTE:

When begin_time is not empty, end_time is mandatory.

mode

string

No

The DB instance mode.

Valid value:

  • Sharding
  • ReplicaSet
  • Single

Requests

None

Responses

  • Parameter description
    Table 2 Parameter description

    Name

    Type

    Mandatory

    Description

    backups

    Array of objects

    Yes

    The backup list. For more information, see Table 3.

    total_count

    Integer

    Yes

    The total number of queried records.
    Table 3 Data structure description of the backups field

    Name

    Type

    Mandatory

    Description

    id

    String

    Yes

    Indicates the backup ID.

    name

    String

    Yes

    The backup name.

    instance_id

    String

    Yes

    The ID of the DB instance from which the backup was created. You can obtain the ID by calling the API for querying DB instances. If you do not have an instance, you can call the API used for creating an instance.

    instance_name

    String

    Yes

    The name of the DB instance for which the backup is created.

    datastore

    Object

    Yes

    The database version. For more information, see Table 4.

    type

    String

    Yes

    The backup type.

    • Auto: indicates automated full backup.
    • Manual indicates manual full backup.
    • Incremental: indicates automated incremental backup.

    begin_time

    String

    Yes

    The backup start time. The format of the start time is yyyy-mm-dd hh:mm:ss. The value is in UTC format.

    end_time

    String

    Yes

    The backup end time. The format of the end time is yyyy-mm-dd hh:mm:ss. The value is in UTC format.

    status

    String

    Yes

    The backup status. Valid value:

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

    size

    Long

    Yes

    The backup size in KB.

    description

    String

    Yes

    The backup description.
    Table 4 Data structure description of the datastore field

    Name

    Type

    Mandatory

    Description

    type

    String

    Yes

    The DB engine.

    Valid value: DDS-Community.

    version

    String

    Yes

    The database version. Versions 4.2, 4.0, and 3.4 are supported. The value can be 4.2, 4.0, or 3.4.

    NOTE:
    • DDS 4.2 is restricted for commercial use. For details, see the DDS notices.
    • To ensure you have a good experience using DDS, create a DDS 4.0 instance.
  • Response example
    { 
 "backups": [ 
    { 
        "id": "43e4feaab48f11e89039fa163ebaa7e4br01", 
        "name": "backup-test", 
        "instance_id": "43e4feaab48f11e89039fa163ebaa7e4br01", 
        "instance_name": "cluster-test",
        "datastore" : {  
               "type" : "DDS-Community",  
               "version" : "3.4" 
        }, 
        "type": "auto", 
        "begin_time": "2018-08-06 12:41:14", 
        "end_time": "2018-08-06 12:43:14",
        "status": "COMPLETED", 
        "size": 2803,
        "description": "backup description"
     } 
   ], 
   "total_count":1 
}

Status Code

For more information, see Status Code.

Error Code

For more information, see Error Code.

Parent topic: Backup and Restoration