全部文档
当前文档

暂无内容

如果没有找到您期望的内容,请尝试其他搜索词

文档中心

LIST Retention

最近更新时间:2024-04-03 17:42:38

描述

该接口用于获取Bucket回收站中Object列表,使用此接口的用户,必须是该Bucket的所有者或具有ks3:ListRetention权限。

请求

请求语法

GET /?recycle HTTP/1.1 
Host: {BucketName}.{endpoint} 
Date: {date} 
Authorization: {SignatureValue}

请求参数

参数

描述

是否必选

delimiter

对Object名称进行分割的字符,分割后便于确定公共前缀。将第一次出现delimiter字符之间的Object作为一组元素(即CommonPrefixes)。

  • 类型:String

  • 默认值: 无

  • 示例:/

marker

指定列举目标Bucket中Object的起始位置。KS3按照字母排序方式、从给定的marker开始返回列表。

  • 类型: String

  • 默认值: 无

  • 示例:1.txt

max-keys

指定返回Object的最大数(最后实际返回可能小于该值)。如果想要返回的Object数量大于1000条,可通过设定marker的值来调整起始位置。

  • 取值:[1,1000]。当大于1000时,最多返回1000条记录

  • 类型:String

  • 默认值:1000。如果请求参数包含delimiter,则默认值与最大值均为100

prefix

指定列举Key的前缀。当设置prefix后,又设置delimiter为正斜线(/)时,将只返回该文件夹下的文件,子文件夹名将返回在CommonPrefixes中,子文件夹下递归的所有文件和文件夹不会显示。

如:一个Bucket中有三个Object,分别为image/01、image/test/02和image/test/03。如果仅设置prefix为image/,则将返回全部Object列表。如果设置prefix为image/,delimiter为正斜线(/),将返回image/01和image/test/。

  • 类型: String

  • 默认值: 无

请求头

该接口仅使用公共请求头

请求体

该接口不使用请求体。

响应

响应头

该接口仅返回公共响应头

响应体

响应体为一段描述回收站中Object列表的XML,响应体中包含的元素有:

名称

描述

ListRetentionResult

列出回收站内Object列表相关信息的容器。

  • 类型:Container

  • 父节点:无

Contents

单个Object返回的元数据。

  • 类型: XML Metadata

  • 父节点: ListRetentionResult

CommonPrefixes

当请求中指定了Delimiter参数时,响应中会包含CommonPrefixes元素。

  • 类型: String

  • 父节点: ListRetentionResult

Delimiter

对Object名称进行分割的字符,分割后便于确定公共前缀。

  • 类型: String

  • 父节点: ListRetentionResult

DisplayName

Object的名称。

  • 类型: String

  • 父节点: ListRetentionResult.Contents.Owner

Encoding-Type

Object名称的编码方式。

  • 类型: String

  • 父节点: ListRetentionResult

ETag

Object的实体标签,ETag在上传Object时生成,用于标识一个对象的内容。

  • 类型: String

  • 父节点: ListRetentionResult.Contents

ID

Object Owner的用户ID。

  • 类型: String

  • 父节点: ListRetentionResult.Contents.Owner

IsTruncated

是否被截断。如果Object列表记录数超过了设定的最大值,那么将会被截断。

  • 返回值:true/false。true表示本次没有返回全部结果,false表示本次返回了全部结果。

  • 类型:Boolean

  • 父节点:ListRetentionResult

Key

Object的Key。

  • 类型: String

  • 父节点: ListRetentionResult.Contents

RetentionId

Object的版本ID。回收站支持多版本,当多次同名文件被删除时,回收站内会同时存在多个同名文件,版本数量无限制。恢复回收站内的Object时指定Object的版本ID可针对性进行恢复。

  • 类型:String

  • 父节点: ListRetentionResult.Contents

LastModified

Object最后一次被修改的时间。

  • 类型:Date

  • 父节点:ListRetentionResult.Contents

Marker

指定列举目标Bucket中Object的起始位置。

  • 类型: String

  • 父节点: ListRetentionResult

MaxKeys

返回的最大Object数,默认为1000。

  • 类型: String

  • 父节点: ListRetentionResult

Name

用户空间的名称。

  • 类型: String

  • 父节点: ListRetentionResult

NextMarker

当本次Object列表数超过了最大值,会标记列表被截断(IsTruncated=true),同时返回下个记录的位置信息。用户在下次List Retention时,可使用该值作为Marker参数。注意:当不提供Delimiter参数时,KS3将不会返回NextMarker,如果IsTruncated为true,则可以使用返回的Contents中最后一个Key作为下次List的Marker参数。

  • 类型: String

  • 父节点: ListRetentionResult

Owner

该Bucket的Owner信息。

  • 类型:String

  • 父节点:ListRetentionResult.Contents

  • 子节点:DisplayName, ID

Prefix

该List请求时指定Key的前缀。

  • 类型: String

  • 父节点: ListRetentionResult

Size

对象的大小,按字节统计。

  • 类型: String

  • 父节点: ListRetentionResult.Contents

StorageClass

Object的存储类型,包括:STANDARD/STANDARD_IA/ARCHIVE。

  • 类型: String

  • 父节点:ListRetentionResult.Contents

DeletedTime

Object被移至回收站的时间。

  • 类型:Date

  • 父节点:ListRetentionResult.Contents

EstimatedClearTime

Object在回收站内被彻底删除的时间。

  • 类型:Date

  • 父节点:ListRetentionResult.Contents

示例

请求示例

GET /?recycle HTTP/1.1 
Host: ks3-example.ks3-cn-beijing.ksyuncs.com
Date: Fri, 26 Dec 2023 06:38:43 GMT
Authorization: authorization string
Content-Type: text/plain

响应示例

<?xml version="1.0" encoding="UTF-8"?>
<ListRetentionResult>
    xmlns="http://s3.amazonaws.com/doc/2006-03-01/">
    <Name>ks3-example</Name>
    <MaxKeys>1000</MaxKeys>
    <IsTruncated>false</IsTruncated>
    <Contents>
        <Key>my-image.jpg</Key>
        <RetentionId>29832406847475_MjcxMjAwMDAwMDAwMDAxNUFFNjUwMDAwMDAwMDAwNEY3N0I2</RetentionId>
        <LastModified>2021-1-1T17:50:30.000Z</LastModified>
        <ETag>fba9dede5f27731c9771645a39863328</ETag>
        <Size>434234</Size>
        <StorageClass>STANDARD</StorageClass>
        <RecycleTime>2021-3-12T12:30:30.000Z</RecycleTime>
        <EstimatedClearTime>2021-3-19T16:00:00.000Z</EstimatedClearTime>
        <Owner>
            <ID>73410125</ID>
            <DisplayName>[email protected]</DisplayName>
        </Owner>
    </Contents>
    <Contents>
        <Key>my-2nd-image.jpg</Key>
        <RetentionId>29832406847486_MjcxMjAwMDAwMDAwMDA1NkJFMjkwMDAwMDAwMDAwMzgxMzJD</RetentionId>
        <LastModified>2021-10-12T17:50:30.000Z</LastModified>
        <ETag>1b2cf535f27731c974343645a3985328</ETag>
        <Size>64994</Size>
        <StorageClass>STANDARD</StorageClass>
        <RecycleTime>2021-4-10T10:30:30.000Z</RecycleTime>
        <EstimatedClearTime>2021-5-9T16:00:00.000Z</EstimatedClearTime>
        <Owner>
            <ID>73410125</ID>
            <DisplayName>[email protected]</DisplayName>
        </Owner>
    </Contents>
</ListBucketResult>

错误码

错误码

HTTP状态码

描述

AccessDenied

403

拒绝访问

NoSuchBucket

404

该Bucket不存在

文档导读
纯净模式常规模式

纯净模式

点击可全屏预览文档内容
文档反馈