当您需要列举存储空间(Bucket)中所有文件(Object)的信息,例如文件名称、文件大小、文件最后修改时间等,可以调用GetBucket (ListObjects)接口进行获取。
注意事项
GetBucket (ListObjects)接口已修订为GetBucketV2 (ListObjectsV2)。建议您在开发应用程序时使用较新的版本GetBucketV2 (ListObjectsV2)。为保证向后兼容性,OSS继续支持GetBucket (ListObjects)。有关GetBucketV2 (ListObjectsV2)的更多信息,请参见ListObjectsV2(GetBucketV2)。
执行GetBucket (ListObjects)请求时不会返回Object中自定义的元数据。
GetBucket (ListObjects)是Bucket级别的操作,按照Bucket存储类型收取Put类请求费用。调用一次该接口只收取一次Put类请求费用。更多信息,请参见Put类请求。
请求语法
GET / HTTP/1.1
Host: BucketName.oss-cn-hangzhou.aliyuncs.com
Date: GMT Date
Authorization: SignatureValue
请求头
此接口仅涉及公共请求头,例如Authorization
、Host
等。更多信息,请参见公共请求头(Common Request Headers)。
请求参数
名称 | 类型 | 是否必选 | 示例值 | 描述 |
delimiter | 字符串 | 否 | / | 对Object名字进行分组的字符。所有Object名字包含指定的前缀,第一次出现delimiter字符之间的Object作为一组元素(即CommonPrefixes)。 默认值:无 |
marker | 字符串 | 否 | test1.txt | 设定从marker之后按字母排序开始返回Object。 marker用来实现分页显示效果,参数的长度必须小于1024字节。 做条件查询时,即使marker在列表中不存在,也会从符合marker字母排序的下一个开始打印。 默认值:无 |
max-keys | 字符串 | 否 | 200 | 指定返回Object的最大数。 如果因为max-keys的设定无法一次完成列举,返回结果会附加NextMarker元素作为下一次列举的marker。 取值:大于0小于等于1000 默认值:100 |
prefix | 字符串 | 否 | fun | 限定返回文件的Key必须以prefix作为前缀。
如果把prefix设为某个文件夹名,则列举以此prefix开头的文件,即该文件夹下递归的所有文件和子文件夹。 在设置prefix的基础上,将delimiter设置为正斜线(/)时,返回值中只列举该文件夹下的文件,文件夹下的子文件夹名返回在CommonPrefixes中,子文件夹下递归的所有文件和文件夹不显示。 例如,一个Bucket中有三个Object,分别为fun/test.jpg、 fun/movie/001.avi和fun/movie/007.avi。如果设定prefix为fun/,则返回三个Object;如果在prefix设置为fun/的基础上,将delimiter设置为正斜线(/),则返回fun/test.jpg和fun/movie/。 默认值:无 |
encoding-type | 字符串 | 否 | URL | 对返回的内容进行编码并指定编码的类型。 默认值:无 可选值:URL 重要 delimiter、marker、prefix、NextMarker以及Key使用UTF-8字符。如果delimiter、marker、prefix、NextMarker以及Key中包含XML 1.0标准不支持的控制字符,您可以通过指定encoding-type对返回结果中的Delimiter、Marker、Prefix、NextMarker以及Key进行编码。 |
响应元素
名称 | 类型 | 示例值 | 描述 |
ListBucketResult | 容器 | 不涉及 | 保存GetBucket请求结果的容器。 子节点:Name、Prefix、 Marker、MaxKeys、 Delimiter、IsTruncated、Nextmarker、Contents 父节点:None |
Name | 字符串 | oss-example | Bucket名称。 父节点:ListBucketResult |
Prefix | 字符串 | fun/ | 本次查询结果的前缀。 父节点:ListBucketResult或者CommonPrefixes |
Marker | 字符串 | test1.txt | 标识此次GetBucket(ListObjects)的起点。 父节点:ListBucketResult |
MaxKeys | 字符串 | 100 | 响应请求内返回结果的最大数目。 父节点:ListBucketResult |
Delimiter | 字符串 | / | 对Object名字进行分组的字符。所有名字包含指定的前缀且第一次出现Delimiter字符之间的Object作为一组元素CommonPrefixes。 父节点:ListBucketResult |
EncodingType | 字符串 | url | 指明了返回结果中编码使用的类型。如果请求的参数中指定了encoding-type,则会对返回结果中的Delimiter、Marker、Prefix、NextMarker和Key这些元素进行编码。 父节点:ListBucketResult |
IsTruncated | 枚举字符串 | false | 请求中返回的结果是否被截断。 返回值:true、false
父节点:ListBucketResult |
NextMarker | 字符串 | test100.txt | 下一次列举文件的起点。 父节点:ListBucketResult |
Contents | 容器 | 不涉及 | 保存每个返回Object元数据的容器。 父节点:ListBucketResult |
Key | 字符串 | fun/test.jpg | Object的Key。 父节点:ListBucketResult.Contents |
LastModified | 时间 | 2012-02-24T08:42:32.000Z | Object最后被修改的时间。 父节点:ListBucketResult.Contents |
ETag | 字符串 | 5B3C1A2E053D763E1B002CC607C5A0FE1**** | ETag(Entity Tag)在每个Object生成时创建,用于标识一个Object的内容。
父节点:ListBucketResult.Contents |
Type | 字符串 | Normal | Object类型,分为以下三种:
|
Size | 字符串 | 344606 | 返回Object大小,单位为字节。 父节点:ListBucketResult.Contents |
StorageClass | 字符串 | Standard | Object的存储类型。 父节点:ListBucketResult.Contents |
RestoreInfo | 字符串 | ongoing-request="true” | Object的解冻状态。
|
Owner | 容器 | 不涉及 | 保存Bucket拥有者信息的容器。 子节点:DisplayName、ID 父节点:Contents |
ID | 字符串 | 0022012**** | Bucket拥有者的用户ID。 父节点:ListBucketResult.Contents.Owner |
DisplayName | 字符串 | user_example | Object拥有者名称。 父节点:ListBucketResult.Contents.Owner |
CommonPrefixes | 容器 | 不涉及 | 如果请求中指定了Delimiter参数,则会在返回的响应中包含CommonPrefixes元素。该元素表明以Delimiter结尾,并有共同前缀的Object名称的集合。 父节点:ListBucketResult |
此接口涉及的其他公共响应头,例如x-oss-request-id
、Content-Type
等的更多信息,请参见公共响应头(Common Response Headers)。
示例
简单请求示例
GET / HTTP/1.1 Host: examplebucket.oss-cn-hangzhou.aliyuncs.com Date: Fri, 24 Feb 2012 08:43:27 GMT Authorization: OSS qn6q**************:77Dv****************
返回示例
HTTP/1.1 200 OK x-oss-request-id: 534B371674E88A4D8906**** Date: Fri, 24 Feb 2012 08:43:27 GMT Content-Type: application/xml Content-Length: 1866 Connection: keep-alive Server: AliyunOSS <?xml version="1.0" encoding="UTF-8"?> <ListBucketResult xmlns=”http://doc.oss-cn-hangzhou.aliyuncs.com”> <Name>examplebucket</Name> <Prefix></Prefix> <Marker></Marker> <MaxKeys>100</MaxKeys> <Delimiter></Delimiter> <IsTruncated>false</IsTruncated> <Contents> <Key>fun/movie/001.avi</Key> <LastModified>2012-02-24T08:43:07.000Z</LastModified> <ETag>"5B3C1A2E053D763E1B002CC607C5A0FE1****"</ETag> <Type>Normal</Type> <Size>344606</Size> <StorageClass>Standard</StorageClass> <Owner> <ID>0022012****</ID> <DisplayName>user-example</DisplayName> </Owner> </Contents> <Contents> <Key>fun/movie/007.avi</Key> <LastModified>2012-02-24T08:43:27.000Z</LastModified> <ETag>"5B3C1A2E053D763E1B002CC607C5A0FE1****"</ETag> <Type>Normal</Type> <Size>344606</Size> <StorageClass>Standard</StorageClass> <Owner> <ID>0022012****</ID> <DisplayName>user-example</DisplayName> </Owner> </Contents> <Contents> <Key>fun/test.jpg</Key> <LastModified>2012-02-24T08:42:32.000Z</LastModified> <ETag>"5B3C1A2E053D763E1B002CC607C5A0FE1****"</ETag> <Type>Normal</Type> <Size>344606</Size> <StorageClass>Standard</StorageClass> <Owner> <ID>0022012****</ID> <DisplayName>user-example</DisplayName> </Owner> </Contents> <Contents> <Key>oss.jpg</Key> <LastModified>2012-02-24T06:07:48.000Z</LastModified> <ETag>"5B3C1A2E053D763E1B002CC607C5A0FE1****"</ETag> <Type>Normal</Type> <Size>344606</Size> <StorageClass>Standard</StorageClass> <Owner> <ID>0022012****</ID> <DisplayName>user-example</DisplayName> </Owner> </Contents> </ListBucketResult>
带prefix参数的请求示例
GET /?prefix=fun HTTP/1.1 Host: examplebucket.oss-cn-hangzhou.aliyuncs.com Date: Fri, 24 Feb 2012 08:43:27 GMT Authorization: OSS qn6q**************:77Dv****************
返回示例
HTTP/1.1 200 OK x-oss-request-id: 534B371674E88A4D8906**** Date: Fri, 24 Feb 2012 08:43:27 GMT Content-Type: application/xml Content-Length: 1464 Connection: keep-alive Server: AliyunOSS <?xml version="1.0" encoding="UTF-8"?> <ListBucketResult xmlns=”http://doc.oss-cn-hangzhou.aliyuncs.com”> <Name>examplebucket</Name> <Prefix>fun</Prefix> <Marker></Marker> <MaxKeys>100</MaxKeys> <Delimiter></Delimiter> <IsTruncated>false</IsTruncated> <Contents> <Key>fun/movie/001.avi</Key> <LastModified>2012-02-24T08:43:07.000Z</LastModified> <ETag>"5B3C1A2E053D763E1B002CC607C5A0FE1****"</ETag> <Type>Normal</Type> <Size>344606</Size> <StorageClass>Standard</StorageClass> <Owner> <ID>0022012****</ID> <DisplayName>user_example</DisplayName> </Owner> </Contents> <Contents> <Key>fun/movie/007.avi</Key> <LastModified>2012-02-24T08:43:27.000Z</LastModified> <ETag>"5B3C1A2E053D763E1B002CC607C5A0FE1****"</ETag> <Type>Normal</Type> <Size>344606</Size> <StorageClass>Standard</StorageClass> <Owner> <ID>0022012****</ID> <DisplayName>user_example</DisplayName> </Owner> </Contents> <Contents> <Key>fun/test.jpg</Key> <LastModified>2012-02-24T08:42:32.000Z</LastModified> <ETag>"5B3C1A2E053D763E1B002CC607C5A0FE1****"</ETag> <Type>Normal</Type> <Size>344606</Size> <StorageClass>Standard</StorageClass> <Owner> <ID>0022012****</ID> <DisplayName>user_example</DisplayName> </Owner> </Contents> </ListBucketResult>
带prefix和delimiter参数的请求示例
GET /?prefix=fun/&delimiter=/ HTTP/1.1 Host: examplebucket.oss-cn-hangzhou.aliyuncs.com Date: Fri, 24 Feb 2012 08:43:27 GMT Authorization: OSS qn6q**************:77Dv****************
返回示例
HTTP/1.1 200 OK x-oss-request-id: 534B371674E88A4D8906**** Date: Fri, 24 Feb 2012 08:43:27 GMT Content-Type: application/xml Content-Length: 712 Connection: keep-alive Server: AliyunOSS <?xml version="1.0" encoding="UTF-8"?> <ListBucketResult xmlns=”http://doc.oss-cn-hangzhou.aliyuncs.com”> <Name>examplebucket</Name> <Prefix>fun/</Prefix> <Marker></Marker> <MaxKeys>100</MaxKeys> <Delimiter>/</Delimiter> <IsTruncated>false</IsTruncated> <Contents> <Key>fun/test.jpg</Key> <LastModified>2012-02-24T08:42:32.000Z</LastModified> <ETag>"5B3C1A2E053D763E1B002CC607C5A0FE1****"</ETag> <Type>Normal</Type> <Size>344606</Size> <StorageClass>Standard</StorageClass> <Owner> <ID>0022012****</ID> <DisplayName>user_example</DisplayName> </Owner> </Contents> <CommonPrefixes> <Prefix>fun/movie/</Prefix> </CommonPrefixes> </ListBucketResult>
指定marker分页列举的请求示例
此示例中指定了max-keys=2,即最多返回2条列举信息。
GET /?max-keys=2&marker=test1.txt HTTP/1.1 Host: examplebucket.oss-cn-shenzhen.aliyuncs.com Accept-Encoding: identity Accept: */* Connection: keep-alive User-Agent: aliyun-sdk-python/2.11.0(Darwin/18.2.0/x86_64;3.4.1) date: Tue, 26 May 2020 08:39:48 GMT authorization: OSS qn6q**************:77Dv****************
返回示例
结果中的NextMarker可以作为下次列举请求的Marker。
HTTP/1.1 200 OK Server: AliyunOSS Date: Tue, 26 May 2020 08:39:48 GMT Content-Type: application/xml Content-Length: 1032 Connection: keep-alive x-oss-request-id: 5ECCD5D4881816373582xxx x-oss-server-time: 3 <?xml version="1.0" encoding="UTF-8"?> <ListBucketResult> <Name>examplebucket</Name> <Prefix></Prefix> <Marker>test1.txt</Marker> <MaxKeys>2</MaxKeys> <Delimiter></Delimiter> <EncodingType>url</EncodingType> <IsTruncated>true</IsTruncated> <NextMarker>test100.txt</NextMarker> <Contents> <Key>test10.txt</Key> <LastModified>2020-05-26T07:50:18.000Z</LastModified> <ETag>"C4CA4238A0B923820DCC509A6F75****"</ETag> <Type>Normal</Type> <Size>1</Size> <StorageClass>Standard</StorageClass> <Owner> <ID>1305433xxx</ID> <DisplayName>1305433xxx</DisplayName> </Owner> </Contents> <Contents> <Key>test100.txt</Key> <LastModified>2020-05-26T07:50:20.000Z</LastModified> <ETag>"C4CA4238A0B923820DCC509A6F75****"</ETag> <Type>Normal</Type> <Size>1</Size> <StorageClass>Standard</StorageClass> <Owner> <ID>1305433xxx</ID> <DisplayName>1305433xxx</DisplayName> </Owner> </Contents> </ListBucketResult>
请求的Bucket包含归档或冷归档类型文件
假设examplebucket中包含文件exampleobject1.txt、exampleobject2.txt和exampleobject3.txt,其存储类型均为冷归档存储类型(ColdArchive)。这三个文件所处的状态说明如下:
exampleobject1.txt未提交RestoreObject请求或者RestoreObject请求已过期。
exampleobject2.txt已提交RestoreObject请求,但解冻操作未完成。
exampleobject3.txt已提交RestoreObject请求,并且解冻操作已完成。
请求示例
GET / HTTP/1.1 Host: examplebucket.oss-cn-hangzhou.aliyuncs.com Date: Fri, 24 Feb 2012 08:43:27 GMT Authorization: OSS qn6q**************:77Dv****************
返回示例
HTTP/1.1 200 OK x-oss-request-id: 534B371674E88A4D8906**** Date: Date: Fri, 24 Feb 2012 08:43:27 GMT Content-Type: application/xml Content-Length: 1866 Connection: keep-alive Server: AliyunOSS <?xml version="1.0" encoding="UTF-8"?> <ListBucketResult xmlns=”http://doc.oss-cn-hangzhou.aliyuncs.com”> <Name>examplebucket</Name> <Prefix></Prefix> <Marker></Marker> <MaxKeys></MaxKeys> <Delimiter></Delimiter> <IsTruncated>false</IsTruncated> <Contents> <Key>exampleobject1.txt</Key> <LastModified>2020-06-22T11:42:32.000Z</LastModified> <ETag>"5B3C1A2E053D763E1B002CC607C5A0FE1****"</ETag> <Type>Normal</Type> <Size>344606</Size> <StorageClass>ColdArchive</StorageClass> <Owner> <ID>0022012****</ID> <DisplayName>user-example</DisplayName> </Owner> </Contents> <Contents> <Key>exampleobject2.txt</Key> <LastModified>2020-06-22T11:42:32.000Z</LastModified> <ETag>"5B3C1A2E053D763E1B002CC607C5A0FE1****"</ETag> <Type>Normal</Type> <Size>344606</Size> <StorageClass>Standard</StorageClass> <RestoreInfo>ongoing-request="true"</RestoreInfo> <Owner> <ID>0022012****</ID> <DisplayName>user-example</DisplayName> </Owner> </Contents> <Contents> <Key>exampleobject3.txt</Key> <LastModified>2020-06-22T11:42:32.000Z</LastModified> <ETag>"5B3C1A2E053D763E1B002CC607C5A0FE1****"</ETag> <Type>Normal</Type> <Size>344606</Size> <StorageClass>Standard</StorageClass> <RestoreInfo>ongoing-request="false", expiry-date="Thu, 24 Sep 2020 12:40:33 GMT"</RestoreInfo> <Owner> <ID>0022012****</ID> <DisplayName>user-example</DisplayName> </Owner> </Contents> </ListBucketResult>
SDK
此接口所对应的各语言SDK如下:
错误码
错误码 | HTTP状态码 | 描述 |
NoSuchBucket | 404 | 请求的目标Bucket不存在。请检查请求的Bucket名称是否符合规范。 |
AccessDenied | 403 | 没有访问该Bucket的权限。只有Bucket拥有者以及被授予 |
InvalidArgument | 400 |
|