文档首页/ 云数据库 TaurusDB/ API参考/ API/ 备份管理/ 查询实例回收站中保留的备份列表 - ListRetainedBackups
更新时间:2026-11-10 GMT+08:00
分享

查询实例回收站中保留的备份列表 - ListRetainedBackups

功能介绍

查询实例释放后保留在回收站中的备份列表。

调用方法

请参见如何调用API。

授权信息

账号具备所有API的调用权限,如果使用账号下的IAM用户调用当前API,该IAM用户需具备调用API所需的权限。

  • 如果使用角色与策略授权,具体权限要求请参见权限和授权项。
  • 如果使用身份策略授权,需具备如下身份策略权限。

    授权项

    访问级别

    资源类型(*为必须)

    条件键

    别名

    依赖的授权项

    gaussdbformysql:backup:list

    List

    -

    -

    • gaussdb:instance:list
    • gaussdb:backup:list

    -

URI

GET /v3/{project_id}/instances/{instance_id}/recycle-backups

表1 路径参数

参数

是否必选

参数类型

描述

project_id

是

String

参数解释:

租户在某一Region下的project ID。

获取方法请参见获取项目ID。

约束限制:

不涉及。

取值范围:

只能由英文字母、数字组成,且长度为32个字符。

默认取值:

不涉及。

instance_id

是

String

参数解释:

实例ID,此参数是实例的唯一标识。

通过调用查询回收站实例信息接口获取。

约束限制:

不涉及。

取值范围:

只能由英文字母、数字组成,后缀为in07,长度为36个字符。

默认取值:

不涉及。

表2 Query参数

参数

是否必选

参数类型

描述

offset

否

Integer

参数解释:

索引位置,偏移量。从第一条数据偏移offset条数据后开始查询。

约束限制:

必须为整数,不能为负数。

取值范围:

≥0。

默认取值:

0。

limit

否

Integer

参数解释:

查询记录数。

约束限制:

必须为整数,不能为负数。

取值范围:

1-100。

默认取值:

100。

请求参数

表3 请求Header参数

参数

是否必选

参数类型

描述

X-Auth-Token

是

String

参数解释:

用户Token。 通过调用IAM服务获取用户Token接口获取。

请求响应成功后在响应消息头中包含的“X-Subject-Token”的值即为Token值。

约束限制:

不涉及。

取值范围:

不涉及。

默认取值:

不涉及。

X-Language

否

String

参数解释:

请求语言类型。

约束限制:

不涉及。

取值范围:

  • en-us:英文。

  • zh-cn:中文。

默认取值:

en-us。

响应参数

状态码:200

表4 响应Body参数

参数

参数类型

描述

recycle_backup_infos

Array of RetainedBackupInfo objects

参数解释:

保留备份信息列表。

policy

RetainedBackupPolicy object

参数解释:

保留策略信息。

total

Long

参数解释:

保留备份总数。

取值范围:

不涉及。

表5 RetainedBackupInfo

参数

参数类型

描述

backup_id

String

参数解释:

备份ID。

取值范围:

不涉及。

instance_id

String

参数解释:

源实例ID(已释放实例)。

取值范围:

不涉及。

status

String

参数解释:

备份状态。

取值范围:

Active:可用。

backup_name

String

参数解释:

备份名称。

取值范围:

不涉及。

size

Integer

参数解释:

备份大小,单位MB。

取值范围:

不涉及。

begin_time

String

参数解释:

备份开始时间,格式为“yyyy-mm-ddThh:mm:ssZ”。

其中,T指某个时间的开始;Z指时区偏移量,例如偏移1个小时显示为+0100。

取值范围:

不涉及。

end_time

String

参数解释:

备份结束时间,格式为“yyyy-mm-ddThh:mm:ssZ”,且大于备份开始时间。

其中,T指某个时间的开始;Z指时区偏移量,例如偏移1个小时显示为+0100。

取值范围:

不涉及。

backup_type

String

参数解释:

备份类型。

取值范围:

  • auto:自动全量备份。

  • manual:手动全量备份。

  • differential:差量备份。

  • sparse:稀疏备份。

  • recycle: 回收站备份。

backup_level

String

参数解释:

备份级别,即备份位置。

取值范围:

  • 1:一级备份。

  • 2:二级备份。

表6 RetainedBackupPolicy

参数

参数类型

描述

backup_retention_strategy

String

参数解释:

实例释放保留策略。

状态码:400

表7 响应Body参数

参数

参数类型

描述

error_code

String

错误码。

error_msg

String

错误消息。

状态码:500

表8 响应Body参数

参数

参数类型

描述

error_code

String

错误码。

error_msg

String

错误消息。

请求示例

查询指定实例在回收站中保留的备份列表。

GET https://{endpoint}/v3/054e292c9880d4992f02c0196d3ea468/instances/61a4ea66210545909d74a05c27a7179ein07/recycle-backups?offset=0&limit=10

响应示例

状态码:200

查询实例回收站中保留的备份列表。

{
  "recycle_backup_infos" : [ {
    "backup_id" : "43e64a863b8647b89a8becd1e80d2a87br07",
    "instance_id" : "61a4ea66210545909d74a05c27a7179ein07",
    "status" : "Active",
    "backup_name" : "backup-test",
    "size" : 3218,
    "begin_time" : "2026-07-30T08:30:00Z",
    "end_time" : "2026-07-30T08:35:00Z",
    "backup_type" : "manual",
    "backup_level" : "2"
  } ],
  "policy" : {
    "backup_retention_strategy" : "retain_all"
  },
  "total" : 1
}

状态码

状态码

描述

200

Success.

400

Client error.

500

Server error.

错误码

请参见错误码。

相关文档