腾讯云对象存储GetBucket(ListObjects)

GetBucket(ListObjects)Version2描述

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

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

请求语法GET/?list-type=2HTTP/1.1Host:BUCKET_NAME.s3.REGION.jdcloud-oss.comDate:dateAuthorization:authorizationstring(seeAuthenticatingRequests(AWSSignatureVersion4))请求参数参数描述必须delimiter是一个用于对Object名字进行分组的字符。所有名字包含指定的前缀且第一次出现delimiter字符之间的object作为一组元素——CommonPrefixes。如果未指定prefix,则从名字开头算起。
Type:String
Default:None否encoding-type对响应进行编码并指定编码类型。
ObjcetKey可以包含任何Unicode字符。但是,XML1.0无法解析某些字符,例如ASCII值为0到10的字符。对于XML1.0中不支持的字符,你可以添加此参数以请求腾讯云对象存储对响应中的键进行编码。
Type:String
Default:None
Validvalue: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-typeAPIVersion2需要此参数,且该参数值必须设置为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:XMLmetadata
Ancestor:ListBucketResultCommonPrefixes在返回时,将所有包含指定prefix且第一次出现delimiter的object作为单个CommonPrefixes返回。
只有在指定delimiter时返回CommonPrefixes。
Type:String
Ancestor:ListBucketResultDelimiter是一个用于对Object名字进行分组的字符。
Type:String
Ancestor:ListBucketResultDisplayNameobject拥有者的名称
Type:String
Ancestor:ListBucketResult.Contents.OwnerEncoding-Type对响应进行编码并指定编码类型。
Type:String
Ancestor:ListBucketResultETagETag是腾讯云存储中Object的Hash值,其仅反映Object的数据内容,而不包括元数据(Metadata)。
Type:String
Ancestor:ListBucketResult.ContentsIDobject拥有者的ID。
Type:String
Ancestor:ListBucketResult.Contents.OwnerIsTruncated如果object数量超过MaxKeys值,则更多的object可能返回,为ture;如果所有结果都返回,则为false。
Type:Boolean
Ancestor:ListBucketResultKeyobjectkey
Type:String
Ancestor:ListBucketResult.ContentsLastModifiedobject最后修改时间。
Type:Date
Ancestor:ListBucketResult.ContentsMaxKeys限定此次返回object的最大数。
Type:Date
Ancestor:ListBucketResult.ContentsNamebucket的名称。
Type:String
Ancestor:ListBucketResultOwnerbucket拥有者。
Type:String
Children:DisplayName,ID
Ancestor:ListBucketResult.ContentsPrefix限定返回的objectkey必须以prefix作为前缀。
Type:String
Ancestor:ListBucketResultSizeobject大小。
Type:String
Ancestor:ListBucketResult.ContentsStorageClass存储类型:STANDARD、REDUCED_REDUNDANCY
Type:String
Ancestor:ListBucketResult.ContentsContinuationToken请求中包含此元素,则响应中也包含此元素。
Type:String
Ancestor:ListBucketResultKeyCount响应中返回的object数量。
Type:String
Ancestor:ListBucketResultNextContinuationToken如果响应被截断,腾讯云对象存储将会返回延续Token。你可以使用该Token作为下一条请求中的continuation-token来取回剩余的object。
Type:String
Ancestor:ListBucketResultStartAfter请求中包含此元素,则响应中也包含此元素。
Type:String
Ancestor:ListBucketResult示例示例1:ListingKeys

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

请求示例

GET/?list-type=2HTTP/1.1Host:BUCKET_NAME.s3.REGION.jdcloud-oss.comx-amz-date:20160430T233541ZAuthorization:authorizationstringContent-Type:text/plain

响应示例

HTTP/1.1200OKx-amz-request-id:3B3C7C725673C630Date:Sat,30Apr201623:29:37GMTContent-Type:application/xmlContent-Length:lengthConnection:closeServer:JDCloud腾讯云对象存储?xmlversion="1.0"encoding="UTF-8"?ListBucketResultxmlns="http://s3.amazonaws.com/doc/2006-03-01/"Nameoss-example/NamePrefix/KeyCount205/KeyCountMaxKeys1000/MaxKeysIsTruncatedfalse/IsTruncatedContentsKeymy-image.jpg/KeyLastModified2009-10-12T17:50:30.000Z/LastModifiedETag"fba9dede5f27731c9771645a39863328"/ETagSize434234/SizeStorageClassSTANDARD/StorageClass/ContentsContents.../Contents.../ListBucketResult示例2:ListingKeys(使用max-keys,prefix,start-after元素)

请求示例

GET/?list-type=2max-keys=3prefix=Estart-after=ExampleGuide.pdfHTTP/1.1Host:BUCKET_NAME.s3.REGION.jdcloud-oss.comx-amz-date:20160430T232933ZAuthorization:authorizationstring

响应示例

HTTP/1.1200OKx-amz-request-id:3B3C7C725673C630Date:Sat,30Apr201623:29:37GMTContent-Type:application/xmlContent-Length:lengthConnection:closeServer:JDCloud腾讯云对象存储?xmlversion="1.0"encoding="UTF-8"?ListBucketResultxmlns="http://s3.amazonaws.com/doc/2006-03-01/"Nameoss-example/NamePrefixE/PrefixStartAfterExampleGuide.pdf/StartAfterKeyCount1/KeyCountMaxKeys3/MaxKeysIsTruncatedfalse/IsTruncatedContentsKeyExampleObject.txt/KeyLastModified2013-09-17T18:07:53.000Z/LastModifiedETag"599bab3ed2c697f1d26842727561fd94"/ETagSize857/SizeStorageClassREDUCED_REDUNDANCY/StorageClass/Contents/ListBucketResult示例3:ListingKeys(使用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=2delimiter=/HTTP/1.1Host:BUCKET_NAME.s3.REGION.jdcloud-oss.comx-amz-date:20160430T235931ZAuthorization:authorizationstring

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

ListBucketResultxmlns="http://s3.amazonaws.com/doc/2006-03-01/"Nameoss-example/NamePrefix/PrefixKeyCount2/KeyCountMaxKeys1000/MaxKeysDelimiter//DelimiterIsTruncatedfalse/IsTruncatedContentsKeysample.jpg/KeyLastModified2011-02-26T01:56:20.000Z/LastModifiedETag"bf1d737a4d46a19f3bced6905cc8b902"/ETagSize142863/SizeStorageClassSTANDARD/StorageClass/ContentsCommonPrefixesPrefixphotos//Prefix/CommonPrefixes/ListBucketResult

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

GET/?list-type=2prefix=photos/2006/delimiter=/HTTP/1.1Host:BUCKET_NAME.s3.REGION.jdcloud-oss.comx-amz-date:20160501T000433ZAuthorization:authorizationstring

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

ListBucketResultxmlns="http://s3.amazonaws.com/doc/2006-03-01/"Nameoss-example/NamePrefixphotos/2006//PrefixKeyCount3/KeyCountMaxKeys1000/MaxKeysDelimiter//DelimiterIsTruncatedfalse/IsTruncatedContentsKeyphotos/2006//KeyLastModified2016-04-30T23:51:29.000Z/LastModifiedETag"d41d8cd98f00b204e9800998ecf8427e"/ETagSize0/SizeStorageClassSTANDARD/StorageClass/ContentsCommonPrefixesPrefixphotos/2006/February//Prefix/CommonPrefixesCommonPrefixesPrefixphotos/2006/January//Prefix/CommonPrefixes/ListBucketResult示例4:使用ContinuationToken

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

GET/?list-type=2HTTP/1.1Host:BUCKET_NAME.s3.REGION.jdcloud-oss.comDate:Mon,02May201623:17:07GMTAuthorization:authorizationstring

以下为响应示例:

HTTP/1.1200OKx-amz-request-id:3B3C7C725673C630Date:Sat,30Apr201623:29:37GMTContent-Type:application/xmlContent-Length:lengthConnection:closeServer:JDCloud腾讯云对象存储ListBucketResultxmlns="http://s3.amazonaws.com/doc/2006-03-01/"Nameoss-example/NamePrefix/PrefixNextContinuationToken1ueGcxLPRx1Tr/XYExHnhbYLgveDs2J/wm36Hy4vbOwM=/NextContinuationTokenKeyCount1000/KeyCountMaxKeys1000/MaxKeysIsTruncatedtrue/IsTruncatedContentsKeyhappyface.jpg/KeyLastModified2014-11-21T19:40:05.000Z/LastModifiedETag"70ee1738b6b21e2c8a43f3a5ab0eee71"/ETagSize11/SizeStorageClassSTANDARD/StorageClass/Contents.../ListBucketResult

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

GET/?list-type=2continuation-token=1ueGcxLPRx1Tr/XYExHnhbYLgveDs2J/wm36Hy4vbOwM=HTTP/1.1Host:BUCKET_NAME.s3.REGION.jdcloud-oss.comDate:Mon,02May201623:17:07GMTAuthorization:authorizationstring

在如下返回示例中,腾讯云对象存储将返回上次请求超出未返会的object。

HTTP/1.1200OKx-amz-request-id:3B3C7C725673C630Date:Sat,30Apr201623:29:37GMTContent-Type:application/xmlContent-Length:lengthConnection:closeServer:JDCloud腾讯云对象存储ListBucketResultxmlns="http://s3.amazonaws.com/doc/2006-03-01/"Nameoss-example/NamePrefix/PrefixContinuationToken1ueGcxLPRx1Tr/XYExHnhbYLgveDs2J/wm36Hy4vbOwM=/ContinuationTokenKeyCount112/KeyCountMaxKeys1000/MaxKeysIsTruncatedfalse/IsTruncatedContentsKeyhappyfacex.jpg/KeyLastModified2014-11-21T19:40:05.000Z/LastModifiedETag"70ee1738b6b21e2c8a43f3a5ab0eee71"/ETagSize1111/SizeStorageClassSTANDARD/StorageClass/Contents.../ListBucketResult