全部产品
对象存储 OSS

GetBucket

更新时间:2017-06-07 13:26:11   分享:   

Get Bucket (List Object)

Get Bucket操作可用来list Bucket中所有Object的信息。

请求语法

  1. GET / HTTP/1.1
  2. Host: BucketName.oss-cn-hangzhou.aliyuncs.com
  3. Date: GMT Date
  4. Authorization: SignatureValue

请求参数(Request Parameters)

GetBucket(ListObject)时,可以通过prefix,marker,delimiter和max-keys对list做限定,返回部分结果。另外,可以通过encoding-type对返回结果中的Delimiter、Marker、Prefix、NextMarker和Key这些元素进行编码。

名称 描述
delimiter 是一个用于对Object名字进行分组的字符。所有名字包含指定的前缀且第一次出现delimiter字符之间的object作为一组元素——CommonPrefixes。
数据类型:字符串
默认值:无
marker 设定结果从marker之后按字母排序的第一个开始返回。
数据类型:字符串
默认值:无
max-keys 限定此次返回object的最大数,如果不设定,默认为100,max-keys取值不能大于1000。
数据类型:字符串
默认值:100
prefix 限定返回的object key必须以prefix作为前缀。注意使用prefix查询时,返回的key中仍会包含prefix。
数据类型:字符串
默认值:无
encoding-type 指定对返回的内容进行编码,指定编码的类型。Delimiter、Marker、Prefix、NextMarker和Key使用UTF-8字符,但xml 1.0标准不支持解析一些控制字符,比如ascii值从0到10的字符。对于包含xml 1.0标准不支持的控制字符,可以通过指定encoding-type对返回的Delimiter、Marker、Prefix、NextMarker和Key进行编码。
数据类型:字符串
默认值:无,可选值:url

响应元素(Response Elements)

名称 描述
Contents 保存每个返回Object meta的容器。
类型:容器
父节点:ListBucketResult
CommonPrefixes 如果请求中指定了delimiter参数,则在OSS返回的响应中包含CommonPrefixes元素。该元素标明那些以delimiter结尾,并有共同前缀的object名称的集合。
类型:字符串
父节点:ListBucketResult
Delimiter 是一个用于对Object名字进行分组的字符。所有名字包含指定的前缀且第一次出现delimiter字符之间的object作为一组元素——CommonPrefixes。
类型:字符串
父节点:ListBucketResult
EncodingType 指明返回结果中编码使用的类型。如果请求的参数中指定了encoding-type,那会对返回结果中的Delimiter、Marker、Prefix、NextMarker和Key这些元素进行编码。
类型:字符串
父节点:ListBucketResult
DisplayName Object 拥有者的名字。
类型:字符串
父节点:ListBucketResult.Contents.Owner
ETag ETag (entity tag) 在每个Object生成的时候被创建,用于标示一个Object的内容。对于Put Object请求创建的Object,ETag值是其内容的MD5值;对于其他方式创建的Object,ETag值是其内容的UUID。ETag值可以用于检查Object内容是否发生变化。不建议用户使用ETag来作为Object内容的MD5校验数据完整性。
类型:字符串
父节点:ListBucketResult.Contents
ID Bucket拥有者的用户ID。
类型:字符串
父节点:ListBucketResult.Contents.Owner
IsTruncated 指明是否所有的结果都已经返回; “true”表示本次没有返回全部结果;“false”表示本次已经返回了全部结果。
类型:枚举字符串
有效值:true、false
父节点:ListBucketResult
Key Object的Key.
类型:字符串
父节点:ListBucketResult.Contents
LastModified Object最后被修改的时间。
类型:时间
父节点:ListBucketResult.Contents
ListBucketResult 保存Get Bucket请求结果的容器.
类型:容器 子节点:Name, Prefix, Marker, MaxKeys, Delimiter, IsTruncated, Nextmarker, Contents
父节点:None
Marker 标明这次Get Bucket(List Object)的起点。
类型:字符串
父节点:ListBucketResult
MaxKeys 响应请求内返回结果的最大数目。
类型:字符串
父节点:ListBucketResult
Name Bucket名字
类型:字符串
父节点:ListBucketResult
Owner 保存Bucket拥有者信息的容器。
类型:容器 子节点:DisplayName, ID
父节点:ListBucketResult
Prefix 本次查询结果的开始前缀。
类型:字符串
父节点:ListBucketResult
Size Object的字节数。
类型:字符串
父节点:ListBucketResult.Contents
StorageClass Object的存储类型,支持“Standard”、“IA”、“Archive”。(目前只有部分区域支持“Archive”类型)
类型:字符串
父节点:ListBucketResult.Contents

细节分析

  1. Object中用户自定义的meta,在GetBucket请求时不会返回。
  2. 如果访问的Bucket不存在,包括试图访问因为命名不规范无法创建的Bucket,返回404 Not Found错误,错误码:NoSuchBucket。
  3. 如果没有访问该Bucket的权限,返回403 Forbidden错误,错误码:AccessDenied。
  4. 如果因为max-keys的设定无法一次完成listing,返回结果会附加一个<NextMarker>,提示继续listing可以以此为marker。NextMarker中的值仍在list结果之中。
  5. 在做条件查询时,即使marker实际在列表中不存在,返回也从符合marker字母排序的下一个开始打印。如果max-keys小于0或者大于1000,将返回400 Bad Request错误。错误码:InvalidArgument。
  6. 若prefix,marker,delimiter参数不符合长度要求,返回400 Bad Request。错误码:InvalidArgument。
  7. prefix,marker用来实现分页显示效果,参数的长度必须小于1024字节。
  8. 如果把prefix设为某个文件夹名,就可以罗列以此prefix开头的文件,即该文件夹下递归的所有的文件和子文件夹。如果再把delimiter设置为 / 时,返回值就只罗列该文件夹下的文件,该文件夹下的子文件名返回在CommonPrefixes部分,子文件夹下递归的文件和文件夹不被显示。如一个bucket存在三个object :fun/test.jpg, fun/movie/001.avi, fun/movie/007.avi。若设定prefix为”fun/” ,则返回三个object;如果增加设定delimiter为“/”,则返回文件”fun/test.jpg”和前缀”fun/movie/”;即实现了文件夹的逻辑。

举例场景

在bucket“my_oss”内有4个object,名字分别为:

  • oss.jpg
  • fun/test.jpg
  • fun/movie/001.avi
  • fun/movie/007.avi

示例

请求示例:

  1. GET / HTTP/1.1
  2. Host: oss-example.oss-cn-hangzhou.aliyuncs.com
  3. Date: Fri, 24 Feb 2012 08:43:27 GMT
  4. Authorization: OSS qn6qrrqxo2oawuk53otfjbyc:BC+oQIXVR2/ZghT7cGa0ykboO4M=

返回示例:

  1. HTTP/1.1 200 OK
  2. x-oss-request-id: 534B371674E88A4D8906008B
  3. Date: Fri, 24 Feb 2012 08:43:27 GMT
  4. Content-Type: application/xml
  5. Content-Length: 1866
  6. Connection: keep-alive
  7. Server: AliyunOSS
  8. <?xml version="1.0" encoding="UTF-8"?>
  9. <ListBucketResult xmlns=”http://doc.oss-cn-hangzhou.aliyuncs.com”>
  10. <Name>oss-example</Name>
  11. <Prefix></Prefix>
  12. <Marker></Marker>
  13. <MaxKeys>100</MaxKeys>
  14. <Delimiter></Delimiter>
  15. <IsTruncated>false</IsTruncated>
  16. <Contents>
  17. <Key>fun/movie/001.avi</Key>
  18. <LastModified>2012-02-24T08:43:07.000Z</LastModified>
  19. <ETag>&quot;5B3C1A2E053D763E1B002CC607C5A0FE&quot;</ETag>
  20. <Type>Normal</Type>
  21. <Size>344606</Size>
  22. <StorageClass>Standard</StorageClass>
  23. <Owner>
  24. <ID>00220120222</ID>
  25. <DisplayName>user-example</DisplayName>
  26. </Owner>
  27. </Contents>
  28. <Contents>
  29. <Key>fun/movie/007.avi</Key>
  30. <LastModified>2012-02-24T08:43:27.000Z</LastModified>
  31. <ETag>&quot;5B3C1A2E053D763E1B002CC607C5A0FE&quot;</ETag>
  32. <Type>Normal</Type>
  33. <Size>344606</Size>
  34. <StorageClass>Standard</StorageClass>
  35. <Owner>
  36. <ID>00220120222</ID>
  37. <DisplayName>user-example</DisplayName>
  38. </Owner>
  39. </Contents>
  40. <Contents>
  41. <Key>fun/test.jpg</Key>
  42. <LastModified>2012-02-24T08:42:32.000Z</LastModified>
  43. <ETag>&quot;5B3C1A2E053D763E1B002CC607C5A0FE&quot;</ETag>
  44. <Type>Normal</Type>
  45. <Size>344606</Size>
  46. <StorageClass>Standard</StorageClass>
  47. <Owner>
  48. <ID>00220120222</ID>
  49. <DisplayName>user-example</DisplayName>
  50. </Owner>
  51. </Contents>
  52. <Contents>
  53. <Key>oss.jpg</Key>
  54. <LastModified>2012-02-24T06:07:48.000Z</LastModified>
  55. <ETag>&quot;5B3C1A2E053D763E1B002CC607C5A0FE&quot;</ETag>
  56. <Type>Normal</Type>
  57. <Size>344606</Size>
  58. <StorageClass>Standard</StorageClass>
  59. <Owner>
  60. <ID>00220120222</ID>
  61. <DisplayName>user-example</DisplayName>
  62. </Owner>
  63. </Contents>
  64. </ListBucketResult>

请求示例(含Prefix参数):

  1. GET /?prefix=fun HTTP/1.1
  2. Host: oss-example.oss-cn-hangzhou.aliyuncs.com
  3. Date: Fri, 24 Feb 2012 08:43:27 GMT
  4. Authorization: OSS qn6qrrqxo2oawuk53otfjbyc:BC+oQIXVR2/ZghT7cGa0ykboO4M=

返回示例:

  1. HTTP/1.1 200 OK
  2. x-oss-request-id: 534B371674E88A4D8906008B
  3. Date: Fri, 24 Feb 2012 08:43:27 GMT
  4. Content-Type: application/xml
  5. Content-Length: 1464
  6. Connection: keep-alive
  7. Server: AliyunOSS
  8. <?xml version="1.0" encoding="UTF-8"?>
  9. <ListBucketResult xmlns=”http://doc.oss-cn-hangzhou.aliyuncs.com”>
  10. <Name>oss-example</Name>
  11. <Prefix>fun</Prefix>
  12. <Marker></Marker>
  13. <MaxKeys>100</MaxKeys>
  14. <Delimiter></Delimiter>
  15. <IsTruncated>false</IsTruncated>
  16. <Contents>
  17. <Key>fun/movie/001.avi</Key>
  18. <LastModified>2012-02-24T08:43:07.000Z</LastModified>
  19. <ETag>&quot;5B3C1A2E053D763E1B002CC607C5A0FE&quot;</ETag>
  20. <Type>Normal</Type>
  21. <Size>344606</Size>
  22. <StorageClass>Standard</StorageClass>
  23. <Owner>
  24. <ID>00220120222</ID>
  25. <DisplayName>user_example</DisplayName>
  26. </Owner>
  27. </Contents>
  28. <Contents>
  29. <Key>fun/movie/007.avi</Key>
  30. <LastModified>2012-02-24T08:43:27.000Z</LastModified>
  31. <ETag>&quot;5B3C1A2E053D763E1B002CC607C5A0FE&quot;</ETag>
  32. <Type>Normal</Type>
  33. <Size>344606</Size>
  34. <StorageClass>Standard</StorageClass>
  35. <Owner>
  36. <ID>00220120222</ID>
  37. <DisplayName>user_example</DisplayName>
  38. </Owner>
  39. </Contents>
  40. <Contents>
  41. <Key>fun/test.jpg</Key>
  42. <LastModified>2012-02-24T08:42:32.000Z</LastModified>
  43. <ETag>&quot;5B3C1A2E053D763E1B002CC607C5A0FE&quot;</ETag>
  44. <Type>Normal</Type>
  45. <Size>344606</Size>
  46. <StorageClass>Standard</StorageClass>
  47. <Owner>
  48. <ID>00220120222</ID>
  49. <DisplayName>user_example</DisplayName>
  50. </Owner>
  51. </Contents>
  52. </ListBucketResult>

请求示例(含prefix和delimiter参数):

  1. GET /?prefix=fun/&delimiter=/ HTTP/1.1
  2. Host: oss-example.oss-cn-hangzhou.aliyuncs.com
  3. Date: Fri, 24 Feb 2012 08:43:27 GMT
  4. Authorization: OSS qn6qrrqxo2oawuk53otfjbyc:DNrnx7xHk3sgysx7I8U9I9IY1vY=

返回示例:

  1. HTTP/1.1 200 OK
  2. x-oss-request-id: 534B371674E88A4D8906008B
  3. Date: Fri, 24 Feb 2012 08:43:27 GMT
  4. Content-Type: application/xml
  5. Content-Length: 712
  6. Connection: keep-alive
  7. Server: AliyunOSS
  8. <?xml version="1.0" encoding="UTF-8"?>
  9. <ListBucketResult xmlns=”http://doc.oss-cn-hangzhou.aliyuncs.com”>
  10. <Name>oss-example</Name>
  11. <Prefix>fun/</Prefix>
  12. <Marker></Marker>
  13. <MaxKeys>100</MaxKeys>
  14. <Delimiter>/</Delimiter>
  15. <IsTruncated>false</IsTruncated>
  16. <Contents>
  17. <Key>fun/test.jpg</Key>
  18. <LastModified>2012-02-24T08:42:32.000Z</LastModified>
  19. <ETag>&quot;5B3C1A2E053D763E1B002CC607C5A0FE&quot;</ETag>
  20. <Type>Normal</Type>
  21. <Size>344606</Size>
  22. <StorageClass>Standard</StorageClass>
  23. <Owner>
  24. <ID>00220120222</ID>
  25. <DisplayName>user_example</DisplayName>
  26. </Owner>
  27. </Contents>
  28. <CommonPrefixes>
  29. <Prefix>fun/movie/</Prefix>
  30. </CommonPrefixes>
  31. </ListBucketResult>
本文导读目录
本文导读目录
以上内容是否对您有帮助?