Querying the Backup List

Function

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

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 Policies 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
dds:backup:listAll	list	-	-	dds:backup:list	-

URI

URI format
GET /v3/{project_id}/backups
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** URI parameters
Name	Mandatory	Type	Description
project_id	Yes	string	Definition Project ID of a tenant in a region. To obtain the project ID, see Obtaining a Project ID. Constraints N/A Range N/A Default Value N/A

**Table 2** Query parameters
Name	Mandatory	Type	Description
instance_id	No	string	Definition Instance ID, which can be obtained by calling the API described in Querying Instances and Details. If you do not have an instance, call the API described in Creating a DB Instance to create one. Constraints N/A Range N/A Default Value N/A
backup_id	No	string	Definition Backup ID. Constraints If the backup ID belongs to an automated incremental backup, the instance ID must be specified. Range N/A Default Value N/A
backup_type	No	string	Definition Backup type. Constraints When the value of this field is Incremental, the instance ID must be transferred. Range Auto: automated full backup Manual: manual full backup Incremental: automated incremental backup If this parameter is not transferred, all full backups, including automated and manual full backups, are queried by default. Default Value N/A
offset	No	Integer	Definition Index offset. The query starts from the next backup creation time indexed by this parameter in a specified project. If offset is set to N, the query starts from the N+1 piece of data. Constraints N/A Range The value must be greater than or equal to 0. Default Value 0: The query starts from the latest backup created.
limit	No	Integer	Definition Maximum backups to be queried. Constraints N/A Range 1–100 Default Value 100 If this parameter is not transferred, the first 100 backups are queried by default.
begin_time	No	string	Definition Start time of the query. The format is yyyy-mm-dd hh:mm:ss. The value is in UTC format. Constraints When end_time is not empty, begin_time is mandatory. Range N/A Default Value N/A
end_time	No	string	Definition End time of the query. The format is yyyy-mm-dd hh:mm:ss. The value is in UTC format. Constraints When begin_time is not empty, end_time is mandatory. Range N/A Default Value N/A
mode	No	string	Definition Instance mode. Constraints N/A Range Sharding ReplicaSet Single Default Value N/A
order_field	No	String	Definition Sorting field. Constraints When order_rule is not empty, order_field is mandatory. Range name: backup name instanceName: instance name type: backup type datastoreType: engine type beginTime: start time status: backup status Default Value If this parameter is not specified, backups are sorted in descending order based on the backup start time, that is, the value of begin_time in the response.
order_rule	No	String	Definition Sorting rule. Constraints When order_field is not empty, order_rule is mandatory. Range asc: ascending order desc: descending order Default Value If this parameter is not specified, backups are sorted in descending order based on the backup start time, that is, the value of begin_time in the response.
backup_status	No	String	Definition Backup status. Constraints N/A Range COMPLETED BUILDING FAILED Default Value N/A
backup_name	No	String	Definition Backup name. Fuzzy match is supported. Constraints N/A Range N/A Default Value N/A
backup_description	No	String	Definition Backup description. Fuzzy match is supported. Constraints N/A Range N/A Default Value N/A
instance_name	No	String	Definition Instance name. Fuzzy match is supported. Constraints N/A Range N/A Default Value N/A

Request Parameters

**Table 3** Request header parameters
Name	Mandatory	Type	Description
X-Auth-Token	Yes	string	Definition User token obtained from IAM. For details, see Authentication. Constraints N/A Range N/A Default Value N/A

Response Parameters

**Table 4** Response body parameters
Name	Type	Description
backups	Array of objects	Definition The backup list. For more information, see Table 5. Range N/A
total_count	Integer	Definition The total number of queried records. Range N/A

**Table 5** Data structure description of the backups field
Name	Type	Description
id	String	Definition The backup ID. Range N/A
name	String	Definition The backup name. Range N/A
instance_id	String	Definition 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. Range N/A
instance_name	String	Definition The name of the DB instance for which the backup is created. Range N/A
datastore	Object	Definition The database version. For more information, see Table 6. Range N/A
type	String	Definition The backup type. Range Auto: automated full backup Manual: manual full backup Incremental: automated incremental backup
begin_time	String	Definition The backup start time. The format of the start time is yyyy-mm-dd hh:mm:ss. The value is in UTC format. Range N/A
end_time	String	Definition The backup end time. The format of the end time is yyyy-mm-dd hh:mm:ss. The value is in UTC format. Range N/A
status	String	Definition The backup status. Range BUILDING: Backup in progress COMPLETED: Backup completed FAILED: Backup failed DISABLED: Backup being deleted
size	Long	Definition The backup size in KB. Range N/A
description	String	Definition The backup description. Range N/A
instance_status	String	Definition Instance status. Range normal: An instance is running normally. abnormal: An instance is abnormal. creating: An instance is being created. frozen: An instance is frozen. data_disk_full: The storage space is full. enlargefail: Nodes failed to be added to the instance.
instance_mode	String	Definition Instance mode. Range Sharding ReplicaSet Single
is_instance_restoring	Boolean	Definition Whether the current instance is being restored or checked. Range true: The instance is being restored or checked. The instance backup cannot be deleted. false: The instance is not being restored or checked. The instance backup can be deleted.
backup_method	String	Definition Backup method. Range Snapshot: snapshot backup Physical: physical backup Logical: logical backup Incremental: incremental backup
kms_enable	Boolean	Definition Whether KMS encryption is enabled. Range true: KMS encryption is enabled. false: KMS encryption is disabled.
deletable	Boolean	Definition Whether the backup can be deleted. If a full backup policy is enabled, automated backups cannot be deleted. Manual backups can be deleted. Range true: The backup can be deleted. false: The backup cannot be deleted.

**Table 6** Data structure description of the datastore field
Name	Type	Description
type	String	Definition The DB engine. Range DDS-Community
version	String	Definition The database version. Versions 5.0, 4.4, 4.2, 4.0, and 3.4 are supported. Range The value can be 5.0, 4.4, 4.2, 4.0, or 3.4.

Example Request

GET https://{endpoint}/v3/054e292c9880d4992f02c0196d3ea468/backups?instance_id=a48e43ff268f4c0e879652d65e63d0fbin02

Example Response

{ 
 "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  
 }

SDK

Click Document Database Service DDS SDK to download the SDK or view the SDK document. To learn how to install and authenticate an SDK, read the Usage section.