AI 助理
备案控制台
文档
输入文档关键字查找
首页 对象存储 开发参考 开发指南 API参考 关于Bucket操作 基础操作 GetBucket (ListObjects)

GetBucket（ListObjects）

更新时间：
产品详情
我的收藏

当您需要列举存储空间（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参数的长度必须小于1024字节。

  • 使用prefix查询时，返回的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

  • true表示本次没有返回全部结果。

  • false表示本次已经返回了全部结果。

父节点：ListBucketResult

NextMarker

字符串

test100.txt

下一次列举文件的起点。

父节点：ListBucketResult

Contents

容器

不涉及

保存每个返回Object元数据的容器。

父节点：ListBucketResult

Key

字符串

fun/test.jpg

Object的Key。

父节点：ListBucketResult.Contents

TransitionTime

时间

2024-04-23T07:21:42.000Z

Object通过生命周期规则转储为冷归档或者深度冷归档存储类型的时间。

说明

  • 如果获取的转储时间距离当前时间超过180天，则提前删除冷归档或者深度冷归档Object不会产生存储不足规定时长费用。如果转储时间距离当前时间不超过180天，则提前删除冷归档或者深度冷归档Object会产生存储不足规定时长费用。

  • 不支持通过该字段统计Object通过生命周期规则转储为低频或者归档存储类型的时间。判断低频或者归档存储类型是否满足最低存储时长的要求取决于Last-Modified时间。

父节点：ListBucketResult.Contents

LastModified

时间

2012-02-24T08:42:32.000Z

Object最后被修改的时间。

说明

  • 低频访问类型最低存储时间（30天）以Object存储在OSS的Last Modified时间开始计算。如果获取到Object的Last-Modified时间距离当前时间超过30天，则提前删除Object不会产生低频存储不足规定时长费用。

  • 归档类型最低存储时间（60天）以Object存储在OSS的Last Modified时间开始计算。如果获取到Object的Last-Modified时间距离当前时间超过60天，则提前删除Object不会产生归档存储不足规定时长费用。

父节点：ListBucketResult.Contents

ETag

字符串

5B3C1A2E053D763E1B002CC607C5A0FE1****

ETag（Entity Tag）在每个Object生成时创建，用于标识一个Object的内容。

  • 对于PutObject请求创建的Object，ETag值是其内容的MD5值。

  • 对于其他方式创建的Object，ETag值是基于一定计算规则生成的唯一值，但不是其内容的MD5值。

  • ETag值可以用于检查Object内容是否发生变化。不建议使用ETag值作为Object内容的MD5校验数据完整性的依据。

父节点：ListBucketResult.Contents

Type

字符串

Normal

Object类型，分为以下三种：

  • Normal：通过简单上传生成的Object类型为Normal。

  • Multipart：通过分片上传生成的Object类型为Multipart。

  • Appendable：通过追加上传生成的Object类型为Appendable。

Size

字符串

344606

返回Object大小，单位为字节。

父节点：ListBucketResult.Contents

StorageClass

字符串

Standard

Object的存储类型。

父节点：ListBucketResult.Contents

RestoreInfo

字符串

ongoing-request="true”

Object的解冻状态。

  • 如果没有提交RestoreObject请求或者RestoreObject请求已过期，则不返回该字段。

  • 如果已经提交RestoreObject请求，但解冻操作未完成，则返回的RestoreInfo值为ongoing-request="true"。

  • 如果已经提交RestoreObject请求，且解冻操作已完成，则返回的RestoreInfo值为ongoing-request="false", expiry-date="Thu, 24 Sep 2020 12:40:33 GMT"。其中，expiry-date字段表示解冻完成后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>
      <TransitionTime>2024-04-23T07:21:42.000Z</TransitionTime>
      <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拥有者以及被授予oss:ListObjects权限的用户可以访问该Bucket。

InvalidArgument

400

  • max-keys小于0或者大于1000。

  • prefix、marker、delimiter参数的长度不符合要求。

上一篇：DeleteBucket下一篇：ListObjectsV2（GetBucketV2）
文档推荐