列举资源（list）
描述
本接口用于将指定空间内的资源分批列出。
接口规格
bucket=<UrlEncodedBucket>&marker=<Marker>&limit=<Limit>&prefix=<UrlEncodedPrefix>&delimiter=<UrlEncodedDelimiter>
| 参数名称 | 必填 | 说明 |
bucket |
是 | 指定空间。 |
limit |
本次列举的条目数，范围为1-1000。 缺省值为1000。 |
|
prefix |
指定前缀，只有资源名匹配该前缀的资源会被列出。 缺省值为空字符串。 |
|
delimiter |
指定目录分隔符，列出所有公共前缀（模拟列出目录效果）。 缺省值为空字符串。 |
|
marker |
上一次列举返回的位置标记，作为本次列举的起点信息。 缺省值为空字符串。 |
请求
请求报文格式
POST /list?<listSpec> HTTP/1.1
Host: rsf.qbox.me
Content-Type: application/x-www-form-urlencoded
Authorization: QBox <AccessToken>
访问权限
管理凭证方式。
头部信息
该请求必须指定以下头部信息。
| 头部名称 | 必填 | 说明 |
| Host | 是 | 管理服务器域名，固定为rsf.qbox.me。 |
| Content-Type | 是 | 请求内容MIME类型，固定为application/x-www-form-urlencoded。 |
| Authorization | 是 | 该参数应严格按照管理凭证格式进行填充，否则会返回401错误码。 一个合法的Authorization值应类似于： |
请求内容
该请求无需指定请求内容。
响应
响应报文格式
HTTP/1.1 200 OK
Content-Type: application/json
Cache-Control: no-store
头部信息
| 头部名称 | 说明 |
| Content-Type | 正常情况下该值将被设为application/json，表示返回JSON格式的文本信息。 |
响应内容
■ 如果请求成功，返回包含如下内容的JSON字符串（已格式化，便于阅读）：
{
"marker": "<marker string>",
"commonPrefixes": [
"xxx",
"yyy"
],
"items": [
{
"key"： "<key string>",
"putTime": <filePutTime int64>,
"hash": "<fileETag string>",
"fsize": <fileSize int64>,
"mimeType": "<mimeType string>",
"customer": "<endUserId string>"
},
...
]
}
| 字段名称 | 必填 | 说明 |
marker |
有剩余条目则返回非空字符串，作为下一次列举的参数传入。 如果没有剩余条目则返回空字符串。 |
|
commonPrefixes |
所有目录名的数组，如没有指定delimiter参数则不输出。 |
|
items |
是 | 所有返回条目的数组，如没有剩余条目则为空数组。 |
key |
是 | 资源名。 |
putTime |
是 | 上传时间，单位：100纳秒，其值去掉低七位即为Unix时间。 |
fsize |
是 | 资源内容的大小，单位：字节。 |
hash |
是 | 资源内容的ETag值。 |
mimeType |
是 | 资源内容的MIME类型。 |
customer |
资源内容的唯一属主标识，请参考上传策略。 |
■ 如果请求失败，返回包含如下内容的JSON字符串（已格式化，便于阅读）：
{
"error": "<errMsg string>",
}
| 字段名称 | 必填 | 说明 |
error |
是 | 与HTTP状态码对应的消息文本。 |
响应状态码
| HTTP状态码 | 含义 |
| 200 | 列举成功。 |
| 400 | 请求报文格式错误。 |
| 401 | 管理凭证无效。 |
| 599 | 服务端操作失败。 如遇此错误，请将完整错误信息（包括所有HTTP响应头部）通过邮件发送给我们。 |
示例
- 列出所有
00打头的资源：
接口规格
bucket=qiniu-ts-demo&prefix=00
返回结果
{"items"=>[{"key"=>"00000001.txt", "hash"=>"Fi2XEahn6IfmwBLwvXb0HGowjyym", "fsize"=>93966, "mimeType"=>"text/plain", "putTime"=>13993416549476933}, {"key"=>"00000002.txt", "hash"=>"Foiz8WAEOgOo8B-lyYegCHcl6VSb", "fsize"=>172422, "mimeType"=>"text/plain", "putTime"=>13993416551051809}, {"key"=>"00000003.txt", "hash"=>"FgsZJh9ACX9-tz2PWjKfFpURlXU2", "fsize"=>175778, "mimeType"=>"text/plain", "putTime"=>13993416553903813}, ...更多内容已省略...]}
- 列出所有
00打头的资源，每批2个：
接口规格
bucket=qiniu-ts-demo&prefix=00&limit=2
返回结果
{"marker"=>"eyJjIjowLCJrIjoiMDAwMDAwMDIuRENNIn0=", "items"=>[{"key"=>"00000001.txt", "hash"=>"Fi2XEahn6IfmwBLwvXb0HGowjyym", "fsize"=>93966, "mimeType"=>"text/plain", "putTime"=>13993416549476933}, {"key"=>"00000002.txt", "hash"=>"Foiz8WAEOgOo8B-lyYegCHcl6VSb", "fsize"=>172422, "mimeType"=>"text/plain", "putTime"=>13993416551051809}]}
{"marker"=>"eyJjIjowLCJrIjoiMDAwMDAwMDQuRENNIn0=", "items"=>[{"key"=>"00000003.txt", "hash"=>"FgsZJh9ACX9-tz2PWjKfFpURlXU2", "fsize"=>175778, "mimeType"=>"text/plain", "putTime"=>13993416553903813}, {"key"=>"00000004.txt", "hash"=>"FikIBhnekDHYA8xugBDchkOrnpEx", "fsize"=>177876, "mimeType"=>"text/plain", "putTime"=>13993416555380554}]}
...更多内容已省略...
- 列出所有
00打头的资源，包括目录，每批2个：
接口规格
bucket=qiniu-ts-demo&prefix=00&limit=2&delimiter=%2F
返回结果
{"marker"=>"eyJjIjowLCJrIjoiMDAwMDAwQ0MuRENNIn0=", "items"=>[{"key"=>"000000CB.txt", "hash"=>"FhSEKlNHeuI1w89AvZMP4ZtlijrO", "fsize"=>208472, "mimeType"=>"text/plain", "putTime"=>13993417254549955}, {"key"=>"000000CC.txt", "hash"=>"FtEIQ24V4Dbx9PVrgK-6S1R3zvbn", "fsize"=>209004, "mimeType"=>"text/plain", "putTime"=>13993417256200466}]}
{"marker"=>"eyJjIjowLCJrIjoiMDAwMDAwQ0UuRENNIn0=", "items"=>[{"key"=>"000000CD.txt", "hash"=>"FsfU5MxvxQxhvxts1KBBbZYPwhui", "fsize"=>210170, "mimeType"=>"text/plain", "putTime"=>13993417258134446}, {"key"=>"000000CE.txt", "hash"=>"FjLnLfzKyNpPHAWcjhRLnwEj-1EP", "fsize"=>209276, "mimeType"=>"text/plain", "putTime"=>13993417259836335}]}
{"marker"=>"eyJjIjowLCJrIjoiMDAyLzAwMDAwMDAyLkRDTSJ9", "items"=>[], "commonPrefixes"=>["001/", "002/"]}
{"marker"=>"eyJjIjowLCJrIjoiMDA0LzAwMDAwMDA0LkRDTSJ9", "items"=>[], "commonPrefixes"=>["003/", "004/"]}
{"marker"=>"eyJjIjowLCJrIjoiMDA2LzAwMDAwMDA2LkRDTSJ9", "items"=>[], "commonPrefixes"=>["005/", "006/"]}
{"marker"=>"eyJjIjowLCJrIjoiMDA4LzAwMDAwMDA4LkRDTSJ9", "items"=>[], "commonPrefixes"=>["007/", "008/"]}
{"marker"=>"eyJjIjowLCJrIjoiMDBBLzAwMDAwMDBBLkRDTSJ9", "items"=>[], "commonPrefixes"=>["009/", "00A/"]}
{"marker"=>"eyJjIjowLCJrIjoiMDBDLzAwMDAwMDBDLkRDTSJ9", "items"=>[], "commonPrefixes"=>["00B/", "00C/"]}
{"marker"=>"eyJjIjowLCJrIjoiMDBFLzAwMDAwMDBFLkRDTSJ9", "items"=>[], "commonPrefixes"=>["00D/", "00E/"]}
{"items"=>[], "commonPrefixes"=>["00F/"]}
附注
无。
如果有任何问题，请进入 七牛云存储问答社区 或者发送 工单 咨询