您可以通过OSS API中的GetBucket (ListObjects)GetBucketV2 (ListObjectsV2) 接口列举您存储空间(Bucket)中的文件(Object)。

说明 GetBucket (ListObjects)接口已修订为 GetBucketV2 (ListObjectsV2)。建议您在开发应用程序时使用较新的版本 GetBucketV2 (ListObjectsV2)。为保证向后兼容性,OSS继续支持 GetBucket (ListObjects)。有关 GetBucketV2 (ListObjectsV2)的详情,请参见 GetBucketV2 (ListObjectsV2)

操作方式

操作方式 说明
控制台 可在控制台对应Bucket的文件管理内直接查看
图形化工具 ossbrowser 图形化工具,易操作
命令行工具 ossutil 命令行工具,性能好
Java SDK 丰富、完整的各类语言SDK demo
Python SDK
PHP SDK
Go SDK
C SDK
.NET SDK
Android SDK
Node.js SDK
Browser.js SDK
Ruby SDK

使用说明

您可以调用 GetBucketV2 (ListObjectsV2)GetBucket (ListObjects)接口,一次性列举某个Bucket下最多1000个Object。您可以通过以下参数实现多种列举功能:
  • GetBucketV2 (ListObjectsV2)
    参数 说明
    Delimiter 对Object名称进行分组的字符。所有Object名称包含指定的前缀,第一次出现Delimiter字符之间的Object作为一组元素(即CommonPrefixes)。
    Start-after 设定从Start-after之后按字母排序开始返回Object。

    Start-after用来实现分页显示效果,参数的长度必须小于1024字节。

    做条件查询时,即使Start-after在列表中不存在,也会从符合Start-after字母排序的下一个开始打印。

    Continuation-token 设定从此token开始返回Object。如果Max-keys的设定无法一次完成列举,返回结果会附加<NextContinuationToken>作为下一次列举的Continuation-token。
    Max-keys 指定返回Object的最大数。

    取值:0~1000

    默认值:100

    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/。

    说明
    • 参数的长度必须小于1024字节。
    • 使用Prefix查询时,返回的Key中仍会包含Prefix。
    Fetch-owner 指定是否在返回结果中包含owner信息。

    合法值:truefalse

    • true:表示返回结果中包含owner信息。
    • false:表示返回结果中不包含owner信息。
  • GetBucket (ListObjects)
    参数 说明
    Delimiter 对Object名称进行分组的字符。所有Object名称包含指定的前缀,第一次出现Delimiter字符之间的Object作为一组元素(即CommonPrefixes)。
    Marker 设定从Marker之后按字母排序开始返回Object。

    Marker用来实现分页显示效果,参数的长度必须小于1024字节。

    做条件查询时,即使Marker在列表中不存在,也会从符合Marker字母排序的下一个开始打印。

    Max-keys 指定返回Object的最大数。

    取值:0~1000

    默认值:100

    Prefix 限定返回文件的Key必须以Prefix作为前缀。

    如果把Prefix设为某个文件夹名,则列举以此Prefix开头的文件,即该文件夹下递归的所有文件和子文件夹。

    在设置Prefix的基础上,将Delimiter设置为正斜线(/)时,返回值就只列举该文件夹下的文件,文件夹下的子文件夹名返回在CommonPrefixes中,子文件夹下递归的所有文件和文件夹不显示。

    说明
    • 参数的长度必须小于1024字节。
    • 使用Prefix查询时,返回的Key中仍会包含Prefix。

文件夹功能

OSS是没有文件夹这个概念的,所有元素都是以Object来存储。创建模拟文件夹本质上来说是创建一个文件名以正斜线(/)结尾,大小为0 KB的Object。这个Object可以被上传和下载,只是控制台会对以正斜线(/)结尾的Object以文件夹的方式展示。

您可以通过Delimiter和Prefix参数的配合实现文件夹功能:

  • 如果把Prefix设为某个文件夹名,就可以列举以此Prefix开头的文件,即该文件夹下递归的所有的文件和子文件夹(目录)。文件名在Contents中显示。
  • 如果再把Delimiter设置为正斜线(/)时,返回值就只列举该文件夹下的文件和子文件夹(目录),该文件夹下的子文件名(目录)返回在CommonPrefixes部分,子文件夹下递归的文件和文件夹不被显示。

示例:

在名为oss-sample的Bucket下有如下Object:
文件D
目录A/文件C
目录A/文件D
目录A/目录B/文件B
目录A/目录B/目录C/文件A
目录A/目录C/文件A
目录A/目录D/文件B
目录B/文件A
  • 列出第一层目录和文件
    将Prefix设置为空,Delimiter为正斜线(/)。返回结果如下:
    <?xml version="1.0" encoding="UTF-8"?>
    <ListBucketResult>
      <Name>oss-sample</Name>
      <Prefix></Prefix>
      <Marker></Marker>
      <MaxKeys>1000</MaxKeys>
      <Delimiter>/</Delimiter>
      <IsTruncated>false</IsTruncated>
      <Contents>
        <Key>文件D</Key>
        <LastModified>2015-11-06T10:07:11.000Z</LastModified>
        <ETag>"8110930DA5E04B1ED5D84D6CC4DC9080"</ETag>
        <Type>Normal</Type>
        <Size>3340</Size>
        <StorageClass>Standard</StorageClass>
        <Owner>
          <ID>oss</ID>
          <DisplayName>oss</DisplayName>
        </Owner>
      </Contents>
      <CommonPrefixes>
        <Prefix>目录A/</Prefix>
      </CommonPrefixes>
      <CommonPrefixes>
        <Prefix>目录B/</Prefix>
      </CommonPrefixes>
    </ListBucketResult>

    Contents返回的是第一层的文件“文件D”;CommonPrefixes返回的是第一层的目录“目录A/” 和“目录B/”,而“目录A/” 和“目录B/”下的文件名不显示。

  • 列出目录A下的第二层目录和文件
    将Prefix设置目录A,Delimiter为正斜线(/)。返回结果如下:
    <?xml version="1.0" encoding="UTF-8"?>
    <ListBucketResult>
      <Name>oss-sample</Name>
      <Prefix>目录A/</Prefix>
      <Marker></Marker>
      <MaxKeys>1000</MaxKeys>
      <Delimiter>/</Delimiter>
      <IsTruncated>false</IsTruncated>
      <Contents>
        <Key>目录A/文件C</Key>
        <LastModified>2015-11-06T09:36:00.000Z</LastModified>
        <ETag>"B026324C6904B2A9CB4B88D6D61C81D1"</ETag>
        <Type>Normal</Type>
        <Size>2</Size>
        <StorageClass>Standard</StorageClass>
        <Owner>
          <ID>oss</ID>
          <DisplayName>oss</DisplayName>
        </Owner>
      </Contents>
      <Contents>
        <Key>目录A/文件D</Key>
        <LastModified>2015-11-06T09:36:00.000Z</LastModified>
        <ETag>"B026324C6904B2A9CB4B88D6D61C81D1"</ETag>
        <Type>Normal</Type>
        <Size>2</Size>
        <StorageClass>Standard</StorageClass>
        <Owner>
          <ID>oss</ID>
          <DisplayName>oss</DisplayName>
        </Owner>
      </Contents>
      <CommonPrefixes>
        <Prefix>目录A/目录B/</Prefix>
      </CommonPrefixes>
      <CommonPrefixes>
        <Prefix>目录A/目录C/</Prefix>
      </CommonPrefixes>
      <CommonPrefixes>
        <Prefix>目录A/目录D/</Prefix>
      </CommonPrefixes>
    </ListBucketResult>

    Contents返回的是第二层的文件“目录A/文件C”、“目录A/文件D”;CommonPrefixes返回的是第二层的目录“目录A/目录B/”、“目录A/目录C/”和“目录A/目录D/”,而目录下的文件名不会被显示。