全部产品
Search
文档中心

对象存储 OSS:Python列举文件

更新时间:Dec 20, 2023

本文介绍如何在开启版本控制状态下列举存储空间下(Bucket)的所有文件(Object)、指定个数的文件、指定前缀的文件等。

注意事项

  • 本文以华东1(杭州)外网Endpoint为例。如果您希望通过与OSS同地域的其他阿里云产品访问OSS,请使用内网Endpoint。关于OSS支持的Region与Endpoint的对应关系,请参见访问域名和数据中心

  • 本文以从环境变量读取访问凭证为例。如何配置访问凭证,请参见配置访问凭证

  • 本文以OSS域名新建OSSClient为例。如果您希望通过自定义域名、STS等方式新建OSSClient,请参见初始化

  • 要列举文件,您必须有oss:ListObjectVersions权限。具体操作,请参见为RAM用户授权自定义的权限策略

列举Bucket中所有Object的信息

以下代码用于列举指定Bucket中包括删除标记(Delete Marker)在内的所有Object的版本信息:

# -*- coding: utf-8 -*-
import oss2
from oss2.credentials import EnvironmentVariableCredentialsProvider
# 从环境变量中获取访问凭证。运行本代码示例之前,请确保已设置环境变量OSS_ACCESS_KEY_ID和OSS_ACCESS_KEY_SECRET。
auth = oss2.ProviderAuth(EnvironmentVariableCredentialsProvider())
# 填写Bucket所在地域对应的Endpoint。以华东1(杭州)为例,Endpoint填写为https://oss-cn-hangzhou.aliyuncs.com。
# yourBucketName填写存储空间名称。
bucket = oss2.Bucket(auth, 'https://oss-cn-hangzhou.aliyuncs.com', 'yourBucketName')

# 开启Bucket版本控制后,调用list_object_versions接口返回不同版本的Object信息。
# 列举Bucket中包括删除标记(Delete Marker)在内的所有Object的版本信息。
result = bucket.list_object_versions()

# 列举所有Object的版本信息。
next_key_marker = None
next_versionid_marker = None
while True:
    result = bucket.list_object_versions(key_marker=next_key_marker, versionid_marker=next_versionid_marker)

    # 查看列举Object的版本信息。
    for version_info in result.versions:
        print('version_info.versionid:', version_info.versionid)
        print('version_info.key:', version_info.key)
        print('version_info.is_latest:', version_info.is_latest)

    # 查看列举删除标记的版本信息。
    for del_maker_Info in result.delete_marker:
        print('del_maker.key:', del_maker_Info.key)
        print('del_maker.versionid:', del_maker_Info.versionid)
        print('del_maker.is_latest:', del_maker_Info.is_latest)

    is_truncated = result.is_truncated

    # 查看列举结果是否完整。如果结果不完整,则继续罗列。如果结果已完整,则退出循环。
    if is_truncated:
        next_key_marker = result.next_key_marker
        next_versionid_marker = result.next_versionid_marker
    else:
        break

列举指定前缀Object的版本信息

以下代码用于列举指定前缀Object的版本信息:

# -*- coding: utf-8 -*-
import oss2
from oss2.credentials import EnvironmentVariableCredentialsProvider
# 从环境变量中获取访问凭证。运行本代码示例之前,请确保已设置环境变量OSS_ACCESS_KEY_ID和OSS_ACCESS_KEY_SECRET。
auth = oss2.ProviderAuth(EnvironmentVariableCredentialsProvider())
# 填写Bucket所在地域对应的Endpoint。以华东1(杭州)为例,Endpoint填写为https://oss-cn-hangzhou.aliyuncs.com。
# yourBucketName填写存储空间名称。
bucket = oss2.Bucket(auth, 'https://oss-cn-hangzhou.aliyuncs.com', 'yourBucketName')

# 开启Bucket版本控制后,调用list_object_versions接口返回不同版本的Object信息。
# 列举Bucket中包括删除标记(Delete Marker)在内的所有Object的版本信息。
result = bucket.list_object_versions()

# 指定列举以test-为前缀的Object的版本信息。
prefix = 'test-'
next_key_marker = None
next_versionid_marker = None
while True:
    result = bucket.list_object_versions(prefix=prefix, key_marker=next_key_marker, versionid_marker=next_versionid_marker)

    # 查看列举的Object版本信息。
    for version_info in result.versions:
        print('version_info.versionid:', version_info.versionid)
        print('version_info.key:', version_info.key)
        print('version_info.is_latest:', version_info.is_latest)

    # 查看列举的删除标记版本信息。
    for del_maker_Info in result.delete_marker:
        print('del_maker.key:', del_maker_Info.key)
        print('del_maker.versionid:', del_maker_Info.versionid)
        print('del_maker.is_latest:', del_maker_Info.is_latest)

    is_truncated = result.is_truncated

    # 查看列举结果是否完整。如果结果不完整,则继续罗列。如果结果已完整,则退出循环。
    if is_truncated:
        next_key_marker = result.next_key_marker
        next_versionid_marker = result.next_versionid_marker
    else:
        break

列举指定个数Object的版本信息

以下代码用于列举指定个数Object的版本信息:

# -*- coding: utf-8 -*-
import oss2
from oss2.credentials import EnvironmentVariableCredentialsProvider
# 从环境变量中获取访问凭证。运行本代码示例之前,请确保已设置环境变量OSS_ACCESS_KEY_ID和OSS_ACCESS_KEY_SECRET。
auth = oss2.ProviderAuth(EnvironmentVariableCredentialsProvider())
# 填写Bucket所在地域对应的Endpoint。以华东1(杭州)为例,Endpoint填写为https://oss-cn-hangzhou.aliyuncs.com。
# yourBucketName填写存储空间名称。
bucket = oss2.Bucket(auth, 'https://oss-cn-hangzhou.aliyuncs.com', 'yourBucketName')

# 开启Bucket版本控制后,调用list_object_versions接口返回不同版本的Object信息。
# 列举Bucket中包括删除标记(Delete Marker)在内的所有Object的版本信息。
result = bucket.list_object_versions()

# 指定本次最多返回200个结果。
max_keys = 200

result = bucket.list_object_versions(max_keys=max_keys)

# 查看列举的Object版本信息。
for version_info in result.versions:
    print('version_info.versionid:', version_info.versionid)
    print('version_info.key:', version_info.key)
    print('version_info.is_latest:', version_info.is_latest)

# 查看列举的Object删除标记的版本信息。
for del_maker_Info in result.delete_marker:
    print('del_maker.key:', del_maker_Info.key)
    print('del_maker.versionid:', del_maker_Info.versionid)
    print('del_maker.is_latest:', del_maker_Info.is_latest)

# 查看列举结果是否有截断。
# 由于指定本次列举最多返回200个结果,若Bucket中Object的个数超过200,则列举结果存在截断,即is_truncated为True。若Bucket中Object的个数少于200,则列举结果没有截断,即is_truncated为False。
print('is truncated', result.is_truncated)

文件夹功能

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

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

  • 如果设置prefix为某个文件夹名称,则会列举以此prefix开头的文件,即该文件夹下所有的文件和子文件夹(目录)均显示为Object。

  • 如果在设置了prefix的情况下,将delimiter设置为正斜线(/),则只列举该文件夹下的文件和子文件夹(目录),该文件夹下的子文件夹(目录)显示为CommonPrefixes,子文件夹下的文件和文件夹不显示。

假设存储空间(examplebucket)中包含文件oss.jpgfun/test.jpgfun/movie/001.avifun/movie/007.txt,以正斜线(/)作为文件夹的分隔符。文件结构如下:

examplebucket           
 └── oss.jpg
 └── fun               
      └── test.jpg
      └── movie
           └── 001.avi
           └── 007.txt

以下示例说明了如何通过模拟文件夹的方式列举文件。

  • 列举根目录下的Object的版本信息

    以下代码用于列举根目录下的Object的版本信息:

    # -*- coding: utf-8 -*-
    import oss2
    from oss2.credentials import EnvironmentVariableCredentialsProvider
    # 从环境变量中获取访问凭证。运行本代码示例之前,请确保已设置环境变量OSS_ACCESS_KEY_ID和OSS_ACCESS_KEY_SECRET。
    auth = oss2.ProviderAuth(EnvironmentVariableCredentialsProvider())
    # 填写Bucket所在地域对应的Endpoint。以华东1(杭州)为例,Endpoint填写为https://oss-cn-hangzhou.aliyuncs.com。
    # yourBucketName填写存储空间名称。
    bucket = oss2.Bucket(auth, 'https://oss-cn-hangzhou.aliyuncs.com', 'yourBucketName')
    
    # 开启Bucket版本控制后,调用list_object_versions接口返回不同版本的Object信息。
    # 列举Bucket中包括删除标记(Delete Marker)在内的所有Object的版本信息。
    result = bucket.list_object_versions()
    
    # 指定delimiter为正斜线(/)。
    delimiter = "/"
    next_key_marker = None
    next_versionid_marker = None
    while True:
        result = bucket.list_object_versions(delimiter=delimiter, key_marker=next_key_marker, versionid_marker=next_versionid_marker)
    
        # 查看列举的Object版本信息。
        for version_info in result.versions:
            print('version_info.versionid:', version_info.versionid)
            print('version_info.key:', version_info.key)
            print('version_info.is_latest:', version_info.is_latest)
    
        # 查看列举的删除标记版本信息。
        for del_maker_Info in result.delete_marker:
            print('del_maker.key:', del_maker_Info.key)
            print('del_maker.versionid:', del_maker_Info.versionid)
            print('del_maker.is_latest:', del_maker_Info.is_latest)
    
        # 查看以正斜线(/)结尾的目录名称。
        for common_prefix in result.common_prefix:
            print("common_prefix:", common_prefix)
    
        is_truncated = result.is_truncated
    
        # 查看列举结果是否完整。如果结果不完整,则继续罗列。如果结果已完整,则退出循环。
        if is_truncated:
            next_key_marker = result.next_key_marker
            next_versionid_marker = result.next_versionid_marker
        else:
            break

    返回结果:

    ('version_info.versionid:', 'CAEQEhiBgMCw8Y7FqBciIGIzMDE3MTEzOWRiMDRmZmFhMmRlMjljZWI0MWU4****')
    ('version_info.key:', 'oss.jpg')
    ('version_info.is_latest:', True)
    ('common_prefix:', 'fun/')
  • 列举目录下的文件和子目录

    以下代码用于列举指定目录下的文件和子目录:

    # -*- coding: utf-8 -*-
    import oss2
    from oss2.credentials import EnvironmentVariableCredentialsProvider
    # 从环境变量中获取访问凭证。运行本代码示例之前,请确保已设置环境变量OSS_ACCESS_KEY_ID和OSS_ACCESS_KEY_SECRET。
    auth = oss2.ProviderAuth(EnvironmentVariableCredentialsProvider())
    # 填写Bucket所在地域对应的Endpoint。以华东1(杭州)为例,Endpoint填写为https://oss-cn-hangzhou.aliyuncs.com。
    # yourBucketName填写存储空间名称。
    bucket = oss2.Bucket(auth, 'https://oss-cn-hangzhou.aliyuncs.com', 'yourBucketName')
    
    # 开启Bucket版本控制后,调用list_object_versions接口返回不同版本的Object信息。
    # 列出Bucket中包括删除标记(Delete Marker)在内的所有Object的版本信息。
    result = bucket.list_object_versions()
    
    # 指定delimiter为正斜线(/),prefix为fun/。
    prefix = "fun/"
    delimiter = "/"
    next_key_marker = None
    next_versionid_marker = None
    while True:
        result = bucket.list_object_versions(prefix=prefix, delimiter=delimiter, key_marker=next_key_marker, versionid_marker=next_versionid_marker)
    
        # 查看列举的Object版本信息。
        for version_info in result.versions:
            print('version_info.versionid:', version_info.versionid)
            print('version_info.key:', version_info.key)
            print('version_info.is_latest:', version_info.is_latest)
    
        # 查看列举的删除标记的版本信息。
        for del_maker_Info in result.delete_marker:
            print('del_maker.key:', del_maker_Info.key)
            print('del_maker.versionid:', del_maker_Info.versionid)
            print('del_maker.is_latest:', del_maker_Info.is_latest)
    
        # 查看以正斜线(/)结尾的文件夹名称。
        for common_prefix in result.common_prefix:
            print("common_prefix:", common_prefix)
    
        is_truncated = result.is_truncated
    
        # 查看列举结果是否完整。如果结果不完整,则继续罗列。如果结果已完整,则退出循环。
        if is_truncated:
            next_key_marker = result.next_key_marker
            next_versionid_marker = result.next_versionid_marker
        else:
            break

    返回结果:

    ('version_info.versionid:', 'CAEQFRiBgMCh9JDkrxciIGE3OTNkYzFhYTc2YzQzOTQ4Y2MzYjg2YjQ4ODg*****')
    ('version_info.key:', 'fun/test.jpg')
    ('version_info.is_latest:', True)
    ('commonPrefix:', 'fun/movie/')

相关文档

关于列举文件的API接口说明,请参见ListObjectVersions(GetBucketVersions)