本文介绍如何列举指定存储空间下(Bucket)的所有文件(Object)、指定前缀的文件、指定目录下的文件和子目录等。

背景信息

您可以调用GetBucket (ListObjects)或GetBucketV2 (ListObjectsV2)接口,一次性列举某个Bucket下最多1000个Object。您可以通过指定参数实现多种列举功能,例如通过指定参数列举指定起始位置后的所有文件、列举指定目录下的文件和子目录、以及列举结果分页。这两个接口的主要区别如下:

  • 使用GetBucket (ListObjects)接口列举文件时,默认返回owner信息。
  • 使用GetBucketV2 (ListObjectsV2)接口列举文件时,需通过fetchOwner指定是否在返回结果中包含owner信息。
    说明 对于开启版本控制的Bucket,建议使用GetBucketV2 (ListObjectsV2)接口列举文件。

以下分别介绍通过GetBucket (ListObjects)以及GetBucketV2 (ListObjectsV2)方法列举文件时涉及的参数说明。

  • 通过GetBucket (ListObjects)方法列举文件

    GetBucket (ListObjects)涉及参数说明如下:

    参数 描述
    prefix 本次查询结果的前缀。
    delimiter 对文件名称进行分组的字符。
    marker 此次列举文件的起点。
  • 通过GetBucketV2 (ListObjectsV2)方法列举文件

    GetBucketV2 (ListObjectsV2)涉及参数说明如下:

    参数 描述
    prefix 本次查询结果的前缀。
    delimiter 对文件名称进行分组的字符。
    startAfter 此次列举文件的起点。
    fetchOwner 指定是否在返回结果中包含owner信息。
    • true:表示返回结果中包含owner信息。
    • false:表示返回结果中不包含owner信息。

简单列举

  • 通过GetBucket (ListObjects)方法列举

    通过GetBucket (ListObjects)方法列举指定存储空间下的10个文件的示例代码如下:

    # -*- coding: utf-8 -*-
    import oss2
    from itertools import islice
    
    # 阿里云主账号AccessKey拥有所有API的访问权限,风险很高。强烈建议您创建并使用RAM账号进行API访问或日常运维,请登录RAM控制台创建RAM账号。
    auth = oss2.Auth('<yourAccessKeyId>', '<yourAccessKeySecret>')
    # Endpoint以杭州为例,其它Region请按实际情况填写。
    bucket = oss2.Bucket(auth, 'http://oss-cn-hangzhou.aliyuncs.com', '<yourBucketName>')
    
    for b in islice(oss2.ObjectIterator(bucket), 10):
        print(b.key)
                        
  • 通过GetBucketV2 (ListObjectsV2)方法列举文件

    通过GetBucketV2 (ListObjectsV2)方法列举指定存储空间下的10个文件的示例代码如下:

    # -*- coding: utf-8 -*-
    import oss2
    from itertools import islice
    
    # 阿里云主账号AccessKey拥有所有API的访问权限,风险很高。强烈建议您创建并使用RAM账号进行API访问或日常运维,请登录RAM控制台创建RAM账号。
    auth = oss2.Auth('<yourAccessKeyId>', '<yourAccessKeySecret>')
    # Endpoint以杭州为例,其它Region请按实际情况填写。
    bucket = oss2.Bucket(auth, 'http://oss-cn-hangzhou.aliyuncs.com', '<yourBucketName>')
    
    for obj in islice(oss2.ObjectIteratorV2(bucket), 10):
        print(obj.key)
                        

列举存储空间下所有文件

  • 通过GetBucket (ListObjects)方法列举

    通过GetBucket (ListObjects)方法列举指定存储空间下所有文件的示例代码如下:

    # -*- coding: utf-8 -*-
    import oss2
    
    # 阿里云主账号AccessKey拥有所有API的访问权限,风险很高。强烈建议您创建并使用RAM账号进行API访问或日常运维,请登录RAM控制台创建RAM账号。
    auth = oss2.Auth('<yourAccessKeyId>', '<yourAccessKeySecret>')
    # Endpoint以杭州为例,其它Region请按实际情况填写。
    bucket = oss2.Bucket(auth, 'http://oss-cn-hangzhou.aliyuncs.com', '<yourBucketName>')
    
    # 列举存储空间下所有文件。
    for obj in oss2.ObjectIterator(bucket):
        print(obj.key)
  • 通过GetBucketV2 (ListObjectsV2)方法列举文件

    通过GetBucketV2 (ListObjectsV2)方法列举指定存储空间下所有文件的示例代码如下:

    # -*- coding: utf-8 -*-
    import oss2
    
    # 阿里云主账号AccessKey拥有所有API的访问权限,风险很高。强烈建议您创建并使用RAM账号进行API访问或日常运维,请登录RAM控制台创建RAM账号。
    auth = oss2.Auth('<yourAccessKeyId>', '<yourAccessKeySecret>')
    # Endpoint以杭州为例,其它Region请按实际情况填写。
    bucket = oss2.Bucket(auth, 'http://oss-cn-hangzhou.aliyuncs.com', '<yourBucketName>')
    
    # 列举存储空间下所有文件。
    for obj in oss2.ObjectIteratorV2(bucket):
        print(obj.key)
  • 通过GetBucketV2 (ListObjectsV2)方法列举文件,并返回文件的owner信息

    通过GetBucketV2 (ListObjectsV2)方法列举指定存储空间下所有文件,并通过指定fetch_owner参数返回文件的owner信息的完整示例代码如下:

    # -*- coding: utf-8 -*-
    import oss2
    
    # 阿里云主账号AccessKey拥有所有API的访问权限,风险很高。强烈建议您创建并使用RAM账号进行API访问或日常运维,请登录RAM控制台创建RAM账号。
    auth = oss2.Auth('<yourAccessKeyId>', '<yourAccessKeySecret>')
    # Endpoint以杭州为例,其它Region请按实际情况填写。
    bucket = oss2.Bucket(auth, 'http://oss-cn-hangzhou.aliyuncs.com', '<yourBucketName>')
    
    # 列举存储空间下所有文件,并通过指定fetch_owner参数返回owner信息。
    for obj in oss2.ObjectIteratorV2(bucket, fetch_owner=True):
        print(obj.key)
        print('file owner display name: ' + obj.owner.display_name)
        print('file owner id: ' + obj.owner.id)

列举指定前缀的所有文件

假设存储空间中有4个文件: oss.jpg、fun/test.jpg、fun/movie/001.avi、fun/movie/007.avi,正斜线(/)作为文件夹的分隔符。

  • 通过GetBucket (ListObjects)方法列举

    通过GetBucket (ListObjects)方法列举指定前缀的所有文件的示例代码如下:

    # -*- coding: utf-8 -*-
    import oss2
    
    # 阿里云主账号AccessKey拥有所有API的访问权限,风险很高。强烈建议您创建并使用RAM账号进行API访问或日常运维,请登录RAM控制台创建RAM账号。
    auth = oss2.Auth('<yourAccessKeyId>', '<yourAccessKeySecret>')
    # Endpoint以杭州为例,其它Region请按实际情况填写。
    bucket = oss2.Bucket(auth, 'http://oss-cn-hangzhou.aliyuncs.com', '<yourBucketName>')
    
    # 列举fun文件夹下的所有文件,包括子目录下的文件。
    for obj in oss2.ObjectIterator(bucket, prefix='fun/'):
        print(obj.key)
  • 通过GetBucketV2 (ListObjectsV2)方法列举

    通过GetBucketV2 (ListObjectsV2)方法列举指定前缀的所有文件的示例代码如下:

    # -*- coding: utf-8 -*-
    import oss2
    
    # 阿里云主账号AccessKey拥有所有API的访问权限,风险很高。强烈建议您创建并使用RAM账号进行API访问或日常运维,请登录RAM控制台创建RAM账号。
    auth = oss2.Auth('<yourAccessKeyId>', '<yourAccessKeySecret>')
    # Endpoint以杭州为例,其它Region请按实际情况填写。
    bucket = oss2.Bucket(auth, 'http://oss-cn-hangzhou.aliyuncs.com', '<yourBucketName>')
    
    # 列举fun文件夹下的所有文件,包括子目录下的文件。
    for obj in oss2.ObjectIteratorV2(bucket, prefix='fun/'):
        print(obj.key)
  • 返回结果
    fun/movie/001.avi
    fun/movie/007.avi
    fun/test.jpg

列举指定起始位置后的所有文件

  • 通过GetBucket (ListObjects)方法列举

    通过设置marker参数可以指定列举的起始位置,OSS将会返回字符串marker的字典序后的所有文件。假设存储空间中包含4个文件,分别为x1.txt、x2.txt、z1.txt和z2.txt。

    通过GetBucket (ListObjects)方法列举指定起始位置后的所有文件的示例代码如下:

    # -*- coding: utf-8 -*-
    import oss2
    
    # 阿里云主账号AccessKey拥有所有API的访问权限,风险很高。强烈建议您创建并使用RAM账号进行API访问或日常运维,请登录RAM控制台创建RAM账号。
    auth = oss2.Auth('<yourAccessKeyId>', '<yourAccessKeySecret>')
    # Endpoint以杭州为例,其它Region请按实际情况填写。
    bucket = oss2.Bucket(auth, 'http://oss-cn-hangzhou.aliyuncs.com', '<yourBucketName>')
    
    # 列举指定字符串之后的所有文件。即使存储空间中存在marker的同名object,返回结果中也不会包含这个object。
    for obj in oss2.ObjectIterator(bucket, marker="x2.txt"):
        print(obj.key)
  • 通过GetBucketV2 (ListObjectsV2)方法列举

    通过设置start_after参数可以指定列举的起始位置,OSS将会返回字符串start_after的字典序后的所有文件。假设存储空间中包含4个文件,分别为x1.txt、x2.txt、z1.txt和z2.txt。

    通过GetBucketV2 (ListObjectsV2)方法列举指定起始位置后的所有文件的示例代码如下:

    # -*- coding: utf-8 -*-
    import oss2
    
    # 阿里云主账号AccessKey拥有所有API的访问权限,风险很高。强烈建议您创建并使用RAM账号进行API访问或日常运维,请登录RAM控制台创建RAM账号。
    auth = oss2.Auth('<yourAccessKeyId>', '<yourAccessKeySecret>')
    # Endpoint以杭州为例,其它Region请按实际情况填写。
    bucket = oss2.Bucket(auth, 'http://oss-cn-hangzhou.aliyuncs.com', '<yourBucketName>')
    
    # 列举指定字符串之后的所有文件。即使存储空间中存在start_after的同名object,返回结果中也不会包含这个object。
    for obj in oss2.ObjectIteratorV2(bucket, start_after="x2.txt"):
        print(obj.key)

列举指定目录下的文件和子目录

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

通过delimiter和prefix两个参数可以模拟文件夹功能:

  • 如果设置prefix为某个文件夹名称,则会列举以此prefix开头的文件,即该文件夹下所有的文件和子文件夹(目录)。
  • 如果再设置delimiter为正斜线(/),则只列举该文件夹下的文件和子文件夹(目录)名称,子文件夹下的文件和文件夹不显示。

以下分别介绍如何通过GetBucket (ListObjects)和GetBucketV2 (ListObjectsV2)方法列举指定目录下的文件和子目录。

  • 通过GetBucket (ListObjects)方法列举

    通过GetBucket (ListObjects)方法列举指定目录下的文件和子目录的示例代码如下:

    # -*- coding: utf-8 -*-
    import oss2
    
    # 阿里云主账号AccessKey拥有所有API的访问权限,风险很高。强烈建议您创建并使用RAM账号进行API访问或日常运维,请登录RAM控制台创建RAM账号。
    auth = oss2.Auth('<yourAccessKeyId>', '<yourAccessKeySecret>')
    # Endpoint以杭州为例,其它Region请按实际情况填写。
    bucket = oss2.Bucket(auth, 'http://oss-cn-hangzhou.aliyuncs.com', '<yourBucketName>')
    
    # 列举fun文件夹下的文件与子文件夹名称,不列举子文件夹下的文件。
    for obj in oss2.ObjectIterator(bucket, prefix = 'fun/', delimiter = '/'):
        # 通过is_prefix方法判断obj是否为文件夹。
        if obj.is_prefix():  # 判断obj为文件夹。
            print('directory: ' + obj.key)
        else:                # 判断obj为文件。
            print('file: ' + obj.key)
  • 通过GetBucketV2 (ListObjectsV2)方法列举

    通过GetBucketV2 (ListObjectsV2)方法列举指定目录下的文件和子目录的示例代码如下:

    # -*- coding: utf-8 -*-
    import oss2
    
    # 阿里云主账号AccessKey拥有所有API的访问权限,风险很高。强烈建议您创建并使用RAM账号进行API访问或日常运维,请登录RAM控制台创建RAM账号。
    auth = oss2.Auth('<yourAccessKeyId>', '<yourAccessKeySecret>')
    # Endpoint以杭州为例,其它Region请按实际情况填写。
    bucket = oss2.Bucket(auth, 'http://oss-cn-hangzhou.aliyuncs.com', '<yourBucketName>')
    
    # 列举fun文件夹下的文件与子文件夹名称,不列举子文件夹下的文件。如果不需要返回owenr信息可以不设置fetch_owner参数。
    for obj in oss2.ObjectIteratorV2(bucket, prefix = 'fun/', delimiter = '/', fetch_owner=True):
        # 通过is_prefix方法判断obj是否为文件夹。
        if obj.is_prefix():  # 判断obj为文件夹。
            print('directory: ' + obj.key)
        else:                # 判断obj为文件。
            print('file: ' + obj.key)
            print('file owner display name: ' + obj.owner.display_name)
            print('file owner id: ' + obj.owner.id)
  • 返回结果
    directory: fun/movie/
    file: fun/test.jpg

获取指定目录下的文件大小

  • 通过GetBucket (ListObjects)方法列举

    通过GetBucket (ListObjects)方法列举指定目录下的文件大小的示例代码如下:

    # -*- coding: utf-8 -*-
    import oss2
    
    def CalculateFolderLength(bucket, folder):
        length = 0
        for obj in oss2.ObjectIterator(bucket, prefix=folder):
            length += obj.size
        return length
    
    # 阿里云主账号AccessKey拥有所有API的访问权限,风险很高。强烈建议您创建并使用RAM账号进行API访问或日常运维,请登录RAM控制台创建RAM账号。
    auth = oss2.Auth('<yourAccessKeyId>', '<yourAccessKeySecret>')
    # Endpoint以杭州为例,其它Region请按实际情况填写。
    bucket = oss2.Bucket(auth, 'http://oss-cn-hangzhou.aliyuncs.com', '<yourBucketName>')
    
    for obj in oss2.ObjectIterator(bucket, delimiter='/'):
        if obj.is_prefix():  # 判断obj为文件夹。
            length = CalculateFolderLength(bucket, obj.key)
            print('directory: ' + obj.key + '  length:' + str(length) + "Byte.")
        else: # 判断obj为文件。
            print('file:' + obj.key + '  length:' + str(obj.size) + "Byte.")
  • 通过GetBucketV2 (ListObjectsV2)方法列举文件

    通过GetBucketV2 (ListObjectsV2)方法列举指定目录下的文件大小的示例代码如下:

    # -*- coding: utf-8 -*-
    import oss2
    
    def CalculateFolderLength(bucket, folder):
        length = 0
        for obj in oss2.ObjectIteratorV2(bucket, prefix=folder):
            length += obj.size
        return length
    
    # 阿里云主账号AccessKey拥有所有API的访问权限,风险很高。强烈建议您创建并使用RAM账号进行API访问或日常运维,请登录RAM控制台创建RAM账号。
    auth = oss2.Auth('<yourAccessKeyId>', '<yourAccessKeySecret>')
    # Endpoint以杭州为例,其它Region请按实际情况填写。
    bucket = oss2.Bucket(auth, 'http://oss-cn-hangzhou.aliyuncs.com', '<yourBucketName>')
    
    for obj in oss2.ObjectIteratorV2(bucket, delimiter='/'):
        if obj.is_prefix():  # 判断obj为文件夹。
            length = CalculateFolderLength(bucket, obj.key)
            print('directory: ' + obj.key + '  length:' + str(length) + "Byte.")
        else: # 判断obj为文件。
            print('file:' + obj.key + '  length:' + str(obj.size) + "Byte.")