全部产品
Search

搜索本产品

    对象存储 OSS：Python列举文件

    文档中心

    对象存储 OSS：Python列举文件

    更新时间：Nov 08, 2024

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

    注意事项

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

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

    • 本文以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.ProviderAuthV4(EnvironmentVariableCredentialsProvider())

# 填写Bucket所在地域对应的Endpoint。以华东1（杭州）为例，Endpoint填写为https://oss-cn-hangzhou.aliyuncs.com。
endpoint = "https://oss-cn-hangzhou.aliyuncs.com"
# 填写Endpoint对应的Region信息，例如cn-hangzhou。注意，v4签名下，必须填写该参数
region = "cn-hangzhou"

# yourBucketName填写存储空间名称。
bucket = oss2.Bucket(auth, endpoint, "yourBucketName", region=region)


# 开启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.ProviderAuthV4(EnvironmentVariableCredentialsProvider())

# 填写Bucket所在地域对应的Endpoint。以华东1（杭州）为例，Endpoint填写为https://oss-cn-hangzhou.aliyuncs.com。
endpoint = "https://oss-cn-hangzhou.aliyuncs.com"
# 填写Endpoint对应的Region信息，例如cn-hangzhou。注意，v4签名下，必须填写该参数
region = "cn-hangzhou"

# yourBucketName填写存储空间名称。
bucket = oss2.Bucket(auth, endpoint, "yourBucketName", region=region)

# 开启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.ProviderAuthV4(EnvironmentVariableCredentialsProvider())

# 填写Bucket所在地域对应的Endpoint。以华东1（杭州）为例，Endpoint填写为https://oss-cn-hangzhou.aliyuncs.com。
endpoint = "https://oss-cn-hangzhou.aliyuncs.com"
# 填写Endpoint对应的Region信息，例如cn-hangzhou。注意，v4签名下，必须填写该参数
region = "cn-hangzhou"

# yourBucketName填写存储空间名称。
bucket = oss2.Bucket(auth, endpoint, "yourBucketName", region=region)

# 开启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.jpg、fun/test.jpg、fun/movie/001.avi和fun/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.ProviderAuthV4(EnvironmentVariableCredentialsProvider())

# 填写Bucket所在地域对应的Endpoint。以华东1（杭州）为例，Endpoint填写为https://oss-cn-hangzhou.aliyuncs.com。
endpoint = "https://oss-cn-hangzhou.aliyuncs.com"
# 填写Endpoint对应的Region信息，例如cn-hangzhou。注意，v4签名下，必须填写该参数
region = "cn-hangzhou"

# yourBucketName填写存储空间名称。
bucket = oss2.Bucket(auth, endpoint, "yourBucketName", region=region)

# 开启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.ProviderAuthV4(EnvironmentVariableCredentialsProvider())

# 填写Bucket所在地域对应的Endpoint。以华东1（杭州）为例，Endpoint填写为https://oss-cn-hangzhou.aliyuncs.com。
endpoint = "https://oss-cn-hangzhou.aliyuncs.com"
# 填写Endpoint对应的Region信息，例如cn-hangzhou。注意，v4签名下，必须填写该参数
region = "cn-hangzhou"

# yourBucketName填写存储空间名称。
bucket = oss2.Bucket(auth, endpoint, "yourBucketName", region=region)

# 开启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）。