# 查询备份列表-QueryingtheBackupList #### 功能介绍 根据指定条件查询备份列表。 #### 调试 您可以在[API Explorer](https://apiexplorer.developer.huaweicloud.com/apiexplorer/doc?product=DDS&api=ListBackups)中调试该接口。 #### 授权信息 账号具备所有API的调用权限，如果使用账号下的IAM用户调用当前API，该IAM用户需具备调用API所需的权限。 - 如果使用角色与策略授权，具体权限要求请参见[权限和授权项](https://support.huaweicloud.com/api-dds/dds_api_permission.html)。 - 如果使用身份策略授权，需具备如下身份策略权限。 | 授权项 | 访问级别 | 资源类型（\*为必须） | 条件键 | 别名 | 依赖的授权项 | |:---|:---|:---|:---|:---|:---| | dds:backup:listAll | list | - | - | dds:backup:list | - | | dds:instance:listAll | list | - | - | dds:instance:list | - | ![](https://support.huaweicloud.com/api-dds/public_sys-resources/note_3.0-zh-cn.png) 如需开通企业项目，请增加dds:instance:list授权项。 #### URI - URI格式 GET /v3/{project_id}/backups - URI样例 https://dds.cn-north-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 表1路径参数 | 名称 | 是否必选 | 类型 | 描述 | |:---|:---|:---|:---| | project_id | 是 | string | **参数解释：** 租户在某一Region下的项目ID。请参考[获取项目ID](https://support.huaweicloud.com/api-dds/dds_projectid.html)章节获取项目编号。 **约束限制：** 不涉及。 **取值范围：** 不涉及。 **默认取值：** 不涉及。 | 表2Query参数 | 名称 | 是否必选 | 类型 | 描述 | |:---|:---|:---|:---| | instance_id | 否 | string | **参数解释：** 实例ID，可以调用"[查询实例列表和详情-QueryingInstancesandDetails](https://support.huaweicloud.com/api-dds/dds_api_0023.html)"接口获取。如果未申请实例，可以调用"[创建实例-CreatingaDBInstance](https://support.huaweicloud.com/api-dds/dds_api_0020.html)"接口创建。 **约束限制：** 不涉及。 **取值范围：** 不涉及。 **默认取值：** 不涉及。 | | backup_id | 否 | string | **参数解释：** 备份ID。 **约束限制：** 当该字段传入的备份ID归属为自动增量备份时，实例ID必传。 **取值范围：** 不涉及。 **默认取值：** 不涉及。 | | backup_type | 否 | string | **参数解释：** 备份类型。 **约束限制：** 当该字段取值为"Incremental"时，实例ID必传。 **取值范围：** - 取值为"Auto"，表示自动全量备份。 - 取值为"Manual"，表示手动全量备份。 - 取值为"Incremental"，表示自动增量备份。 - 当该字段未传入值时，默认只查询所有的全量备份，包括自动全备备份和手动全量备份。 **默认取值：** 不涉及。 | | offset | 否 | Integer | **参数解释：** 索引位置偏移量，表示从指定project ID下最新的备份创建时间开始，按时间的先后顺序偏移offset条数据后查询对应的备份信息。 **约束限制：** 不涉及。 **取值范围：** 大于或等于0。 **默认取值：** 0，表示从最新的备份创建时间对应的备份开始查询。 | | limit | 否 | Integer | **参数解释：** 查询备份个数上限值。 **约束限制：** 不涉及。 **取值范围：** 1\~100。 **默认取值：** 100。不传该参数时，默认查询前100条备份信息。 | | begin_time | 否 | string | **参数解释：** 查询备份开始的时间，格式为"yyyy-mm-dd hh:mm:ss"。该时间为UTC时间。 **约束限制：** "end_time"有值时，"begin_time"必选。 **取值范围：** 不涉及。 **默认取值：** 不涉及。 | | end_time | 否 | string | **参数解释：** 查询备份开始的结束时间，格式为"yyyy-mm-dd hh:mm:ss"。该时间为UTC时间。 **约束限制：** "begin_time"有值时，"end_time"必选。 **取值范围：** 不涉及。 **默认取值：** 不涉及。 | | mode | 否 | string | **参数解释：** 实例模式。 **约束限制：** 不涉及。 **取值范围：** - Sharding - ReplicaSet - Single **默认取值：** 不涉及。 | | order_field | 否 | String | **参数解释：** 排序字段。 **约束限制：** "order_rule"有值时，"order_field"必选。 **取值范围：** - name，备份名称。 - instanceName，实例名称。 - type，备份类型。 - datastoreType，引擎类型。 - beginTime，开始时间。 - status，备份状态。 **默认取值：** 如果不传值，则默认根据备份开始时间，即响应参数的begin_time，倒序排序。 | | order_rule | 否 | String | **参数解释：** 排序规则。 **约束限制：** "order_field"有值时，"order_rule"必选。 **取值范围：** - asc: 升序排序。 - desc: 降序排序。 **默认取值：** 如果不传值，则默认根据备份开始时间，即响应参数的begin_time，倒序排序。 | | backup_status | 否 | String | **参数解释：** 备份状态。 **约束限制：** 不涉及。 **取值范围：** - COMPLETED - BUILDING - FAILED **默认取值：** 不涉及。 | | backup_name | 否 | String | **参数解释：** 备份名称，支持模糊匹配。 **约束限制：** 不涉及。 **取值范围：** 不涉及。 **默认取值：** 不涉及。 | | backup_description | 否 | String | **参数解释：** 备份描述，支持模糊匹配。 **约束限制：** 不涉及。 **取值范围：** 不涉及。 **默认取值：** 不涉及。 | | instance_name | 否 | String | **参数解释：** 实例名称，支持模糊匹配。 **约束限制：** 不涉及。 **取值范围：** 不涉及。 **默认取值：** 不涉及。 | #### 请求参数 表3请求Header参数 | 名称 | 是否必选 | 类型 | 描述 | |:---|:---|:---|:---| | X-Auth-Token | 是 | string | **参数解释：** 从IAM服务获取的用户Token。请参考[认证鉴权](https://support.huaweicloud.com/api-dds/dds_api_0010.html)。 **约束限制：** 不涉及。 **取值范围：** 不涉及。 **默认取值：** 不涉及。 | #### 响应参数 表4响应Body参数 | 名称 | 参数类型 | 描述 | |:---|:---|:---| | backups | Array of objects | **参数解释：** 备份列表。详情请参见[表5]。 **取值范围：** 不涉及。 | | total_count | Integer | **参数解释：** 总记录数。 **取值范围：** 不涉及。 | 表5backups字段数据结构说明 | 名称 | 参数类型 | 描述 | |:---|:---|:---| | id | String | **参数解释：** 备份ID。 **取值范围：** 不涉及。 | | name | String | **参数解释：** 备份名称。 **取值范围：** 不涉及。 | | instance_id | String | **参数解释：** 备份所属的实例ID，可以调用"查询实例列表"接口获取。如果未申请实例，可以调用"创建实例"接口创建。 **取值范围：** 不涉及。 | | instance_name | String | **参数解释：** 备份所属的实例名称。 **取值范围：** 不涉及。 | | datastore | Object | **参数解释：** 数据库版本信息。详情请参见[表6]。 **取值范围：** 不涉及。 | | type | String | **参数解释：** 备份类型。 **取值范围：** - 取值为"Auto"，表示自动全量备份。 - 取值为"Manual"，表示手动全量备份。 - 取值为"Incremental"，表示自动增量备份。 | | begin_time | String | **参数解释：** 备份开始时间，格式为"yyyy-mm-dd hh:mm:ss"。该时间为UTC时间。 **取值范围：** 不涉及。 | | end_time | String | **参数解释：** 备份结束时间，格式为"yyyy-mm-dd hh:mm:ss"。该时间为UTC时间。 **取值范围：** 不涉及。 | | status | String | **参数解释：** 备份状态。 **取值范围：** - BUILDING：备份中。 - COMPLETED：备份完成。 - FAILED：备份失败。 - DISABLED：备份删除中。 | | size | Long | **参数解释：** 备份大小，单位：KB。 **取值范围：** 不涉及。 | | description | String | **参数解释：** 备份描述。 **取值范围：** 不涉及。 | | instance_status | String | **参数解释：** 实例状态。 **取值范围：** - normal，表示实例正常。 - abnormal，表示实例异常。 - creating，表示实例创建中。 - frozen，表示实例被冻结。 - data_disk_full，表示存储空间满。 - enlargefail，表示实例扩容节点个数失败。 | | instance_mode | String | **参数解释：** 实例模式。 **取值范围：** - Sharding - ReplicaSet - Single | | is_instance_restoring | Boolean | **参数解释：** 当前实例是否处于恢复中或者恢复检查中。 **取值范围：** - true，表示实例处于恢复中或者恢复检查中，不允许删除该实例备份。 - false，当前实例未处于恢复中或者恢复检查中，允许删除该实例备份。 | | backup_method | String | **参数解释：** 备份方式。 **取值范围：** - Snapshot，快照备份。 - Physical，物理备份。 - Logical，逻辑备份。 - Incremental，增量备份。 | | kms_enable | Boolean | **参数解释：** 是否开启kms加密。 **取值范围：** - true，已开启kms加密。 - false，未开启kms加密。 | | deletable | Boolean | **参数解释：** 是否支持删除该备份。当全备策略存在时，不允许删除自动备份。手动备份允许删除。 **取值范围：** - true，允许删除该备份。 - false，不允许删除该备份。 | 表6datastore字段数据结构说明 | 名称 | 参数类型 | 描述 | |:---|:---|:---| | type | String | **参数解释：** 数据库引擎。 **取值范围：** DDS-Community。 | | version | String | **参数解释：** 数据库版本。支持5.0、4.4、4.2、4.0、3.4版本。 **取值范围：** 取值为"5.0"、"4.4"、"4.2"、"4.0"、"3.4"。 | #### 请求示例 ``` GET https://{endpoint}/v3/054e292c9880d4992f02c0196d3ea468/backups?instance_id=a48e43ff268f4c0e879652d65e63d0fbin02 ``` #### 响应示例 ``` { "backups": [ { "id": "e2d711e54fef4aea91c02b94b8530f26br02", "name": "DDS-dds-6733-20260701000022059", "instance_id": "163506c6addf4a9388c4d8470b98b832in02", "instance_name": "dds-6733", "datastore": { "type": "DDS-Community", "version": "4.0" }, "type": "Auto", "begin_time": "2026-06-30 16:00:21", "end_time": "2026-06-30 16:01:43", "status": "COMPLETED", "size": 6088, "description": null, "instance_status": "normal", "instance_mode": "ReplicaSet", "backup_method": "Physical", "kms_enable": false, "is_instance_restoring": false, "deletable": false }, { "id": "5293aff7206d4d579ae6e9d343585909br02", "name": "DDS-dds-6733-20260630144132647", "instance_id": "163506c6addf4a9388c4d8470b98b832in02", "instance_name": "dds-6733", "datastore": { "type": "DDS-Community", "version": "4.0" }, "type": "Auto", "begin_time": "2026-06-30 06:41:32", "end_time": "2026-06-30 06:42:54", "status": "COMPLETED", "size": 1719, "description": null, "instance_status": "normal", "instance_mode": "ReplicaSet", "backup_method": "Physical", "kms_enable": false, "is_instance_restoring": false, "deletable": false } ], "total_count": 2 } ``` #### SDK 单击[文档数据库服务 DDS SDK](https://sdkcenter.developer.huaweicloud.com/?product=DDS)，下载SDK或查看SDK文档。SDK的安装、认证方式等在SDK文档中对应语言类型的【使用】目录下。 #### 状态码 详情请参见[状态码](https://support.huaweicloud.com/api-dds/dds_status_code.html)。 #### 错误码 详情请参见[错误码](https://support.huaweicloud.com/api-dds/dds_error_code.html)。