GetBucket

GetBucket操作可用来列出Bucket中所有Object的信息。

请求语法

GET / HTTP/1.1
Host: bucketname.cos.chinac.com
Date: GMT Date
Authorization: SignatureValue

请求参数

GetBucket(ListObject)时,可以通过prefix,marker,delimiter和max-keys对list做限定,返回部分结果。

Name Type Description
delimiter String 是一个用于对Object名字进行分组的字符。所有名字包含指定的前缀且第一次出现delimiter字符之间的object作为一组元素CommonPrefixes
marker String 设定结果从marker之后按字母排序的第一个开始返回
max-keys String 限定此次返回object的最大数,如果不设定,默认为100,max-keys取值不能大于1000
prefix String 限定返回的object key必须以prefix作为前缀。注意使用prefix查询时,返回的key中仍会包含prefix

响应元素

Name Type Description
Name String Bucket名字
Prefix String 本次查询结果的开始前缀
Marker String 标明这次Get Bucket的起点
Delimiter String 用于对Object名字进行分组的字符。所有名字包含指定的前缀且第一次出现delimiter字符之间的object作为一组元素CommonPrefixes
MaxKeys String 响应请求内返回结果的最大数目
IsTruncated Boolean “true”表示本次没有返回全部结果;“false”表示本次已经返回了全部结果。
Contents Object 保存每个返回Object meta
Key String Object的Key
LastModified String Object最后被修改的时间
ETag String ETag在每个Object生成的时候被创建,用于标示一个Object的内容。
Size String Object的字节数
StorageClass String Object的存储类型
Owner Object 保存Bucket拥有者信息
ID String Bucket拥有者的用户ID
DisplayName String Object 拥有者的名字
CommonPrefixes Array 如果请求中指定了delimiter参数,则在COS返回的响应中包含CommonPrefixes元素。该元素表明那些以delimiter结尾,并有共同前缀的集合

细节分析

  1. Object中用户自定义的meta,在GetBucket请求时不会返回
  2. 如果访问的Bucket不存在,返回404 Not Found错误,错误码:NoSuchBucket
  3. 如果没有访问该Bucket的权限,返回403 Forbidden错误,错误码:AccessDenied
  4. 如果因为max-keys的设定无法一次完成List,返回结果会附加一个<NextMarker>,提示继续List可以以此为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用来实现分页显示效果,参数的长度必须小于1000字节
  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:mybucket内有4个Object,名字分别为:

  • cos.jpg
  • fun/test.jpg
  • fun/movie/001.avi
  • fun/movie/007.avi
不带请求参数
请求示例
GET / HTTP/1.1
Host: mybucket.cos.chinac.com
Date: Fri, 24 Feb 2012 08:43:27 GMT
Authorization: COS qn6qrrqxo2oawuk53otfjbyc:BC+oQIXVR2/ZghT7cGa0ykboO4M=
返回示例
HTTP/1.1 200 OK
x-cos-request-id: 534B371674E88A4D8906008B
Date: Fri, 24 Feb 2012 08:43:27 GMT
Content-Type: application/json
Content-Length: 1866
Connection: keep-alive
Server: ChinacCOS
{
    "Name": "mybucket",
    "Prefix": "",
    "Marker": "",
    "Delimiter": "",
    "MaxKeys": 100,
    "IsTruncated": false,
    "Contents":[
    {
        "Key": "cos.jpg",
        "LastModified": "2016-02-25T14:57:52+0800",
        "ETag": "98e7e4b65139c5e2c90c0b7922c6bd62",
        "Size": 19,
        "StorageClass": "standard",
        "Owner":{"ID": "test", "DisplayName": ""}
    },
    {
        "Key": "fun/movie/001.avi",
        "LastModified": "2016-02-25T14:58:14+0800",
        "ETag": "13a76019ba6aba9d97a1f5839b23cd0f",
        "Size": 26,
        "StorageClass": "standard",
        "Owner":{"ID": "test", "DisplayName": ""}
    },
    {
        "Key": "fun/movie/007.avi",
        "LastModified": "2016-02-25T14:58:22+0800",
        "ETag": "93c96024fef8e18dbf6a478a9ed984c0",
        "Size": 38,
        "StorageClass": "standard",
        "Owner":{"ID": "test", "DisplayName": ""}
    },
    {
        "Key": "fun/test.jpg",
        "LastModified": "2016-02-25T14:58:03+0800",
        "ETag": "2cdd4b15a1768dcddd1675661015579e",
        "Size": 35,
        "StorageClass": "standard",
        "Owner":{"ID": "test", "DisplayName": ""}
    }
    ],
    "CommonPrefixes":[]
}

含Prefix参数

请求示例
GET /?prefix=fun HTTP/1.1
Host: mybucket.cos.chinac.com
Date: Fri, 24 Feb 2012 08:43:27 GMT
Authorization: COS qn6qrrqxo2oawuk53otfjbyc:BC+oQIXVR2/ZghT7cGa0ykboO4M=
返回示例
HTTP/1.1 200 OK
x-cos-request-id: 534B371674E88A4D8906008B
Date: Fri, 24 Feb 2012 08:43:27 GMT
Content-Type: application/xml
Content-Length: 1464
Connection: keep-alive
Server: ChinacCOS

{
    "Name": "mybucket",
    "Prefix": "fun",
    "Marker": "",
    "Delimiter": "",
    "MaxKeys": 100,
    "IsTruncated": false,
    "Contents":[
    {
        "Key": "fun/movie/001.avi",
        "LastModified": "2016-02-25T14:58:14+0800",
        "ETag": "13a76019ba6aba9d97a1f5839b23cd0f",
        "Size": 26,
        "StorageClass": "standard",
        "Owner":{"ID": "test", "DisplayName": ""}
    },
    {
        "Key": "fun/movie/007.avi",
        "LastModified": "2016-02-25T14:58:22+0800",
        "ETag": "93c96024fef8e18dbf6a478a9ed984c0",
        "Size": 38,
        "StorageClass": "standard",
        "Owner":{"ID": "test", "DisplayName": ""}
    },
    {
        "Key": "fun/test.jpg",
        "LastModified": "2016-02-25T14:58:03+0800",
        "ETag": "2cdd4b15a1768dcddd1675661015579e",
        "Size": 35,
        "StorageClass": "standard",
        "Owner":{"ID": "test", "DisplayName": ""}
    }
    ],
    "CommonPrefixes":[]
}

含prefix和delimiter参数

请求示例
GET /?prefix=fun/&delimiter=/ HTTP/1.1
Host: mybucket.cos.chinac.com
Date: Fri, 24 Feb 2012 08:43:27 GMT
Authorization: COS qn6qrrqxo2oawuk53otfjbyc:DNrnx7xHk3sgysx7I8U9I9IY1vY=
返回示例
HTTP/1.1 200 OK
x-cos-request-id: 534B371674E88A4D8906008B
Date: Fri, 24 Feb 2012 08:43:27 GMT
Content-Type: application/xml
Content-Length: 712
Connection: keep-alive
Server: ChinaCOS

{
    "Name": "mybucket",
    "Prefix": "fun/",
    "Marker": "",
    "Delimiter": "/",
    "MaxKeys": 100,
    "IsTruncated": false,
    "Contents":[
    {
        "Key": "fun/test.jpg",
        "LastModified": "2016-02-25T14:58:03+0800",
        "ETag": "2cdd4b15a1768dcddd1675661015579e",
        "Size": 35,
        "StorageClass": "standard",
        "Owner":{"ID": "test", "DisplayName": ""}
    }
    ],
    "CommonPrefixes":[
        { "Prefix": "fun/movie/"}
    ]
}

results matching ""

    No results matching ""