全部产品
Search

搜索本产品

    对象存储 OSS：Python列举文件

    文档中心

    对象存储 OSS：Python列举文件

    更新时间：Nov 08, 2024

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

    注意事项

    • 仅Python SDK 2.12.0及以上版本支持使用GetBucketV2（ListObjectsV2）方法。

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

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

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

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

    背景信息

    您可以调用GetBucket（ListObjects）或GetBucketV2（ListObjectsV2）接口，一次性列举某个Bucket下最多1000个Object。您可以通过指定参数实现多种列举功能，例如通过指定参数列举指定起始位置后的所有文件、列举指定目录下的文件和子目录、以及通过分页列举超过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个文件的示例代码如下。

    说明

    ObjectIterator封装了ListObjects接口，以迭代器的方式提供，方便您使用。

    # -*- coding: utf-8 -*-
import oss2
from oss2.credentials import EnvironmentVariableCredentialsProvider
from itertools import islice

# 从环境变量中获取访问凭证。运行本代码示例之前，请确保已设置环境变量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下的10个文件。
for b in islice(oss2.ObjectIterator(bucket), 10):
    print(b.key)

    通过GetBucketV2（ListObjectsV2）方法列举文件

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

    说明

    ObjectIteratorV2封装了ListObjectsV2接口，以迭代器的方式提供，方便您使用。

    # -*- coding: utf-8 -*-
import oss2
from oss2.credentials import EnvironmentVariableCredentialsProvider
from itertools import islice
# 从环境变量中获取访问凭证。运行本代码示例之前，请确保已设置环境变量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下的10个文件。
for obj in islice(oss2.ObjectIteratorV2(bucket), 10):
    print(obj.key)

    列举存储空间下所有文件

    通过GetBucket（ListObjects）方法列举

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

    # -*- 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下的所有文件。
for obj in oss2.ObjectIterator(bucket):
    print(obj.key)

    通过GetBucketV2（ListObjectsV2）方法列举文件

    • 仅列举文件，不返回文件的owner信息

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

      # -*- 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下的所有文件。
for obj in oss2.ObjectIteratorV2(bucket):
    print(obj.key)

    • 列举文件，并返回文件的owner信息

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

      # -*- 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下的所有文件，并通过指定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
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)

# 列举fun文件夹下的所有文件，包括子目录下的文件。
for obj in oss2.ObjectIterator(bucket, prefix='fun/'):
    print(obj.key)

    通过GetBucketV2（ListObjectsV2）方法列举

    通过GetBucketV2（ListObjectsV2）方法列举指定前缀的所有文件的示例代码如下。

    # -*- 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)

# 列举fun文件夹下的所有文件，包括子目录下的文件。
for obj in oss2.ObjectIteratorV2(bucket, prefix='fun/'):
    print(obj.key)

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

    通过GetBucket（ListObjects）方法列举

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

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

    # -*- 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)

# 列举指定字符串之后的所有文件。即使存储空间中存在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
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。
# 填写Bucket名称，例如examplebucket。
bucket = oss2.Bucket(auth, 'https://oss-cn-hangzhou.aliyuncs.com', 'examplebucket')

# 列举指定字符串之后的所有文件。即使存储空间中存在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）方法列举

    通过GetBucket（ListObjects）方法列举指定目录下的文件和子目录的示例代码如下。

    # -*- 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)

# 列举fun文件夹下的文件与子文件夹名称，不列举子文件夹下的文件。
for obj in oss2.ObjectIterator(bucket, prefix='fun/', delimiter ='/'):
    # 通过is_prefix方法判断obj是否为文件夹。（请注意判断是否为文件夹需要配置delimiter和prefix来完成模拟文件夹功能）
    if obj.is_prefix():  # 判断obj为文件夹。
        print('directory: ' + obj.key)
    else:                # 判断obj为文件。
        print('file: ' + obj.key)

    通过GetBucketV2（ListObjectsV2）方法列举

    通过GetBucketV2（ListObjectsV2）方法列举指定目录下的文件和子目录的示例代码如下。

    # -*- 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)

# 列举fun文件夹下的文件与子文件夹名称，不列举子文件夹下的文件。如果不需要返回owner信息可以不设置fetch_owner参数。
for obj in oss2.ObjectIteratorV2(bucket, prefix = 'fun/', delimiter = '/', start_after='fun/', 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)

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

    通过GetBucket（ListObjects）方法列举

    通过GetBucket（ListObjects）方法列举指定目录下的文件大小的示例代码如下。

    # -*- coding: utf-8 -*-
import oss2
from oss2.credentials import EnvironmentVariableCredentialsProvider

def CalculateFolderLength(bucket, folder):
    length = 0
    for obj in oss2.ObjectIterator(bucket, prefix=folder):
        length += obj.size
    return length
# 从环境变量中获取访问凭证。运行本代码示例之前，请确保已设置环境变量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)

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
from oss2.credentials import EnvironmentVariableCredentialsProvider

def CalculateFolderLength(bucket, folder):
    length = 0
    for obj in oss2.ObjectIteratorV2(bucket, prefix=folder):
        length += obj.size
    return length
# 从环境变量中获取访问凭证。运行本代码示例之前，请确保已设置环境变量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)


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.")

    相关文档