对象存储

    • 对象存储 > API 文档 > Object 接口 > 资源列取(v2)

    资源列取(v2)

    最近更新时间: 2022-06-10 12:05:17

    描述

    本接口用于列举指定空间里的所有文件条目。


    请求


    语法

    GET /v2/list?bucket=<BucketName>&prefix=<UrlEncodedPrefix>&delimiter=<UrlEncodedDelimiter>&limit=<Limit>&marker=<Marker> HTTP/1.1
Host:           rsf.qiniuapi.com
Content-Type:   application/x-www-form-urlencoded
Authorization:  QBox <AccessToken>

    请求参数

    参数名称 必填 说明
    bucket 是 指定空间。
    marker 上一次列举返回的位置标记，作为本次列举的起点信息。

    默认值为空字符串。
    limit 本次列举的条目数。

    默认值为0表示列举所有条目。
    prefix 指定前缀，只有资源名匹配该前缀的资源会被列出。

    默认值为空字符串。
    delimiter 指定目录分隔符，列出所有公共前缀（模拟列出目录效果）。

    默认值为空字符串。

    请求头

    该请求操作的实现使用了所有操作的公共请求头。有关详细信息，请查阅公共请求头。


    请求元素

    该请求操作的请求体为空。


    响应


    数据流式返回，每行一个条目

    响应头

    该请求操作的实现使用了所有操作的公共响应头。有关详细信息，请查阅公共响应头。


    响应元素

    字段名称 必填 说明
    marker 是 有剩余条目则返回非空字符串，作为下一次列举的参数传入。

    如果没有剩余条目则返回空字符串。

    类型：字符串
    item 是 返回的一个条目

    类型：结构体
    dir 是 返回的一个目录，如没有指定delimiter参数则为空字符串。

    类型：字符串

    item结构体说明

    字段名称 必填 说明
    key 是 资源名。

    类型：字符串
    putTime 是 上传时间，单位：100纳秒，其值去掉低七位即为Unix时间戳。

    类型：数字
    hash 是 文件的HASH值，使用hash值算法计算。

    类型：字符串
    fsize 是 资源内容的大小，单位：字节。

    类型：数字
    mimeType 是 资源的 MIME 类型。

    类型：字符串
    endUser 资源内容的唯一属主标识，请参考上传策略 (PutPolicy)。

    类型：字符串
    type 资源的存储类型，1 表示低频存储，0表示普通存储。

    类型：数字
    • 服务端将流式返回数据，每行一个条目
    • 响应的item表示一个文件
    • 响应的marker表示当前list的位置，客户端应该记录下来，如果list没结束，下一次list带上最后一个marker
    • 响应的dir只在请求里面指定delimiter才有效，表示一个目录
    • 如果对应前缀没有数据响应200但是body为空
    • 只有当返回的数据里面 marker 为空才表示结束，在不指定limit的情况下如果出现错误客户端应该拿着最后一个有效的marker继续请求
    • 响应的条目可能会出现item和dir都为空的情况，这种情况客户端应该把marker记录下来，忽略item和dir

    响应示例

    {"item":{"key":"files/D/93.log","hash":"FhWqsP2Lk36zuwGEFpPzXct12i-v","fsize":6,"mimeType":"application/octet-stream","putTime":15148601207652690,"type":0,"status":0},"marker":"eyJjIjowLCJrIjoiZmlsZXMvRC85My5sb2cifQ==","dir":""}
{"item":null,"marker":"eyJjIjowLCJrIjoiZmlsZXMvRC85NC5sb2cifQ==","dir":""}
{"item":null,"marker":"eyJjIjowLCJrIjoiZmlsZXMvIn0=","dir":"files/"}
{"item":null,"marker":"","dir":"mobile/"}

    特殊错误

    该操作的实现不会返回特殊错误。有关错误和错误代码列表的一般信息，请查阅错误响应。


    示例


    假设test的bucket 中含有以下文件:

    abc/xxx/123
abc/yyy/45
abc/xy
abc/z

    请求参数: prefix=abc/, delimiter=/, limit=4,则返回结果为:

    {"item":null,"marker":"eyJjIjowLCJrIjoiYWJjL3h4eC8xMjMifQ==","dir":"abc/xxx/"}
{"item":{"key":"abc/xy","hash":"FhWqsP2Lk36zuwGEFpPzXct12i-v","fsize":6,"mimeType":"application/octet-stream","putTime":15174657947306490,"type":0,"status":0},"marker":"eyJjIjowLCJrIjoiYWJjL3h5In0=","dir":""}
{"item":null,"marker":"eyJjIjowLCJrIjoiYWJjL3l5eS80NSJ9","dir":"abc/yyy/"}
{"item":{"key":"abc/z","hash":"FhWqsP2Lk36zuwGEFpPzXct12i-v","fsize":6,"mimeType":"application/octet-stream","putTime":15174658052945750,"type":0,"status":0},"marker":"","dir":""}
    以上内容是否对您有帮助？