对象存储

产品文档

对象存储

帮助中心 > 产品文档 > 对象存储 > Get Bucket(ListObjects)

Get Bucket(List Objects)Version 2

描述

此操作可列举出Bukcet中的部分或全部(最多1000个)Object。您可以使请求参数作为选择过滤条件来列举部分对象。

注意:即使Bucket的访问权限为public,也不允许匿名使用此操作,需要指定Authorization。

请求

语法


GET /?list-type=2 HTTP/1.1
Host: <BUCKET_NAME>.s3.<REGION>.jdcloud-oss.com
Date: <date>
Authorization: <authorization string> (see Authenticating Requests (AWS Signature Version4))

请求参数

参数 描述 必须
delimiter 是一个用于对Object名字进行分组的字符。所有名字包含指定的前缀且第一次出现delimiter字符之间的object作为一组元素——CommonPrefixes。如果未指定prefix,则从名字开头算起。
Type: String
Default: None
encoding-type 对响应进行编码并指定编码类型。
Objcet Key可以包含任何Unicode字符。但是,XML1.0无法解析某些字符,例如ASCII值为0到10的字符。对于XML 1.0中不支持的字符,您可以添加此参数以请求OSS对响应中的键进行编码。
Type: String
Default: None
Valid value: url
max-keys 限定此次返回object的最大数。如果要检索少于默认的1,000个object,可以将其添加到您的请求中。
响应中object数量如果大于设定的最大数量,则超出的object不会返回,且响应中将包含true。如果要返回额外超出的object,请参阅 NextContinuationToken。
Type: String
Default: 1000
prefix 限定返回的object必须以prefix作为前缀。您可以使用prefix将object分成不同的组。
Type: String
Default: None
list-type API Version 2需要此参数,且该参数值必须设置为2。
Type: String
Default:2
continuation-token 当响应元素 IsTruncated 为true时,则响应中会包含 NextContinuationToken 元素,您可以使用 NextContinuationToken 作为下一个请求中的 continuation-token 返回下一批object。
Type: String
Default: None
fetch-owner 默认情况下不会返回Bucket所有者信息,如果需要返回所有者信息,需指定fetch-owner值为ture
Type: String
Default: false
start-after 如果您需要返回某个特定的object后的相关object,你可以将该特定object名称设为参数值。
Type: String
Default: None

请求元素

无请求元素

请求Header

该操作仅使用通用的请求Header,请参阅常见请求Header。

响应

响应Header

该操作仅使用通用的响应Header,请参阅常见响应Header。

响应元素

名称 描述
Contents 每个object返回的元数据
Type: XML metadata
Ancestor: ListBucketResult
CommonPrefixes 在返回时,将所有包含指定prefix且第一次出现delimiter的object作为单个CommonPrefixes返回。
只有在指定delimiter时返回CommonPrefixes。
Type: String
Ancestor: ListBucketResult
Delimiter 是一个用于对Object名字进行分组的字符。
Type: String
Ancestor: ListBucketResult
DisplayName object拥有者的名称
Type: String
Ancestor: ListBucketResult.Contents.Owner
Encoding-Type 对响应进行编码并指定编码类型。
Type: String
Ancestor: ListBucketResult
ETag ETag 是京东云存储中Object的Hash值,其仅反映Object的数据内容,而不包括元数据(Metadata)。
Type: String
Ancestor: ListBucketResult.Contents
ID object拥有者的ID。
Type: String
Ancestor: ListBucketResult.Contents.Owner
IsTruncated 如果object数量超过MaxKeys值,则更多的object可能返回,为ture;如果所有结果都返回,则为false。
Type: Boolean
Ancestor: ListBucketResult
Key object key
Type: String
Ancestor: ListBucketResult.Contents
LastModified object最后修改时间。
Type: Date
Ancestor: ListBucketResult.Contents
MaxKeys 限定此次返回object的最大数。
Type: Date
Ancestor: ListBucketResult.Contents
Name bucket的名称。
Type: String
Ancestor: ListBucketResult
Owner bucket拥有者。
Type: String
Children: DisplayName, ID
Ancestor: ListBucketResult.Contents
Prefix 限定返回的object key必须以prefix作为前缀。
Type: String
Ancestor: ListBucketResult
Size object大小。
Type: String
Ancestor: ListBucketResult.Contents
StorageClass 存储类型:STANDARD、REDUCED_REDUNDANCY
Type: String
Ancestor: ListBucketResult.Contents
ContinuationToken 请求中包含此元素,则响应中也包含此元素。
Type: String
Ancestor: ListBucketResult
KeyCount 响应中返回的object数量。
Type: String
Ancestor: ListBucketResult
NextContinuationToken 如果响应被截断,OSS将会返回延续Token。你可以使用该Token作为下一条请求中的continuation-token来取回剩余的object。
Type: String
Ancestor: ListBucketResult
StartAfter 请求中包含此元素,则响应中也包含此元素。
Type: String
Ancestor: ListBucketResult

示例

示例1:Listing Keys

该请求可返回某bucket中的object。该请求指定list-type元素为2。

请求示例


GET /?list-type=2 HTTP/1.1
Host: <BUCKET_NAME>.s3.<REGION>.jdcloud-oss.com
x-amz-date: 20160430T233541Z
Authorization: <authorization string>
Content-Type: text/plain

响应示例


HTTP/1.1 200 OK
x-amz-request-id: 3B3C7C725673C630
Date: Sat, 30 Apr 2016 23:29:37 GMT
Content-Type: application/xml
Content-Length: length
Connection: close
Server: JDCloudOSS

<?xml version="1.0" encoding="UTF-8"?>
<ListBucketResult xmlns="http://s3.amazonaws.com/doc/2006-03-01/">
    <Name>oss-example</Name>
    <Prefix/>
    <KeyCount>205</KeyCount>
    <MaxKeys>1000</MaxKeys>
    <IsTruncated>false</IsTruncated>
    <Contents>
        <Key>my-image.jpg</Key>
        <LastModified>2009-10-12T17:50:30.000Z</LastModified>
        <ETag>"fba9dede5f27731c9771645a39863328"</ETag>
        <Size>434234</Size>
        <StorageClass>STANDARD</StorageClass>
    </Contents>
    <Contents>
       ...
    </Contents>
    ...
</ListBucketResult>

示例2:Listing Keys(使用max-keys,prefix,start-after元素)

请求示例


GET /?list-type=2&max-keys=3&prefix=E&start-after=ExampleGuide.pdf HTTP/1.1
Host: <BUCKET_NAME>.s3.<REGION>.jdcloud-oss.com
x-amz-date: 20160430T232933Z
Authorization: <authorization string>

响应示例


HTTP/1.1 200 OK
x-amz-request-id: 3B3C7C725673C630
Date: Sat, 30 Apr 2016 23:29:37 GMT
Content-Type: application/xml
Content-Length: length
Connection: close
Server: JDCloudOSS

<?xml version="1.0" encoding="UTF-8"?>
<ListBucketResult xmlns="http://s3.amazonaws.com/doc/2006-03-01/">
  <Name>oss-example</Name>
  <Prefix>E</Prefix>
  <StartAfter>ExampleGuide.pdf</StartAfter>
  <KeyCount>1</KeyCount>
  <MaxKeys>3</MaxKeys>
  <IsTruncated>false</IsTruncated>
  <Contents>
    <Key>ExampleObject.txt</Key>
    <LastModified>2013-09-17T18:07:53.000Z</LastModified>
    <ETag>"599bab3ed2c697f1d26842727561fd94"</ETag>
    <Size>857</Size>
    <StorageClass>REDUCED_REDUNDANCY</StorageClass>
  </Contents>
</ListBucketResult>

示例3:Listing Keys(使用prefix和delimiter元素)

该示例请求中使用prefix和delimiter元素,假如bucket中有以下object:
sample.jpg
photos/2006/January/sample.jpg
photos/2006/February/sample2.jpg
photos/2006/February/sample3.jpg
photos/2006/February/sample4.jpg

以下示例指定delimiter值为"/":


GET /?list-type=2&delimiter=/ HTTP/1.1
Host: <BUCKET_NAME>.s3.<REGION>.jdcloud-oss.com 
x-amz-date: 20160430T235931Z
Authorization: <authorization string>			

sample.jpg不包含delimiter字符,所以OSS将它返回到Contents元素中。其他object包含delimiter字符,且包含共同的prefix:photos/,所以OSS将其作为单个CommonPrefixes元素返回。


<ListBucketResult xmlns="http://s3.amazonaws.com/doc/2006-03-01/">
  <Name>oss-example</Name>
  <Prefix></Prefix>
  <KeyCount>2</KeyCount>
  <MaxKeys>1000</MaxKeys>
  <Delimiter>/</Delimiter>
  <IsTruncated>false</IsTruncated>
  <Contents>
    <Key>sample.jpg</Key>
    <LastModified>2011-02-26T01:56:20.000Z</LastModified>
    <ETag>"bf1d737a4d46a19f3bced6905cc8b902"</ETag>
    <Size>142863</Size>
    <StorageClass>STANDARD</StorageClass>
  </Contents>
  <CommonPrefixes>
    <Prefix>photos/</Prefix>
  </CommonPrefixes>
</ListBucketResult>

以下示例指定delimiter值为"/",prefix值为"photos/2006/"


GET /?list-type=2&prefix=photos/2006/&delimiter=/ HTTP/1.1
Host: <BUCKET_NAME>.s3.<REGION>.jdcloud-oss.com
x-amz-date: 20160501T000433Z
Authorization: <authorization string>

在响应中,OSS将会返回指定的prefix,并将包含prefix且第一次出现delimiter字符的不同字符串作为不同的CommonPrefixes进行分组并返回。


<ListBucketResult xmlns="http://s3.amazonaws.com/doc/2006-03-01/">
  <Name>oss-example</Name>
  <Prefix>photos/2006/</Prefix>
  <KeyCount>3</KeyCount>
  <MaxKeys>1000</MaxKeys>
  <Delimiter>/</Delimiter>
  <IsTruncated>false</IsTruncated>
  <Contents>
    <Key>photos/2006/</Key>
    <LastModified>2016-04-30T23:51:29.000Z</LastModified>
    <ETag>"d41d8cd98f00b204e9800998ecf8427e"</ETag>
    <Size>0</Size>
    <StorageClass>STANDARD</StorageClass>
  </Contents>

  <CommonPrefixes>
    <Prefix>photos/2006/February/</Prefix>
  </CommonPrefixes>
  <CommonPrefixes>
    <Prefix>photos/2006/January/</Prefix>
  </CommonPrefixes>
</ListBucketResult>

示例4:使用Continuation Token

在这个示例中,初次请求返回object数量超过1000个。在响应中,OSS返回了值为true的IsTruncated元素以及NextContinuationToken元素。


GET /?list-type=2 HTTP/1.1
Host: <BUCKET_NAME>.s3.<REGION>.jdcloud-oss.com
Date: Mon, 02 May 2016 23:17:07 GMT
Authorization: <authorization string>

以下为响应示例:


HTTP/1.1 200 OK
x-amz-request-id: 3B3C7C725673C630
Date: Sat, 30 Apr 2016 23:29:37 GMT
Content-Type: application/xml
Content-Length: length
Connection: close
Server: JDCloudOSS

<ListBucketResult xmlns="http://s3.amazonaws.com/doc/2006-03-01/">
  <Name>oss-example</Name>
  <Prefix></Prefix>
  <NextContinuationToken>1ueGcxLPRx1Tr/XYExHnhbYLgveDs2J/wm36Hy4vbOwM=</NextContinuationToken>
  <KeyCount>1000</KeyCount>
  <MaxKeys>1000</MaxKeys>
  <IsTruncated>true</IsTruncated>
  <Contents>
    <Key>happyface.jpg</Key>
    <LastModified>2014-11-21T19:40:05.000Z</LastModified>
    <ETag>"70ee1738b6b21e2c8a43f3a5ab0eee71"</ETag>
    <Size>11</Size>
    <StorageClass>STANDARD</StorageClass>
  </Contents>
   ...
</ListBucketResult>

如下随后的请求中,我们加入了continuation-token作为请求参数,并将之前返回的 作为该参数值。


GET /?list-type=2&continuation-token=1ueGcxLPRx1Tr/XYExHnhbYLgveDs2J/wm36Hy4vbOwM= HTTP/1.1
Host: <BUCKET_NAME>.s3.<REGION>.jdcloud-oss.com
Date: Mon, 02 May 2016 23:17:07 GMT
Authorization: <authorization string>  

在如下返回示例中,OSS将返回上次请求超出未返会的object。


HTTP/1.1 200 OK
x-amz-request-id: 3B3C7C725673C630
Date: Sat, 30 Apr 2016 23:29:37 GMT
Content-Type: application/xml
Content-Length: length
Connection: close
Server: JDCloudOSS

<ListBucketResult xmlns="http://s3.amazonaws.com/doc/2006-03-01/">
  <Name>oss-example</Name>
  <Prefix></Prefix>
  <ContinuationToken>1ueGcxLPRx1Tr/XYExHnhbYLgveDs2J/wm36Hy4vbOwM=</ContinuationToken>
  <KeyCount>112</KeyCount>
  <MaxKeys>1000</MaxKeys>
  <IsTruncated>false</IsTruncated>
  <Contents>
    <Key>happyfacex.jpg</Key>
    <LastModified>2014-11-21T19:40:05.000Z</LastModified>
    <ETag>"70ee1738b6b21e2c8a43f3a5ab0eee71"</ETag>
    <Size>1111</Size>
    <StorageClass>STANDARD</StorageClass>
  </Contents>
   ...
</ListBucketResult>
更新时间:2019-06-26 19:28:22