使用Python SDK V1列舉Bucket中的檔案 - Object Storage Service

OSS Python SDK提供了封裝的迭代器來列舉儲存空間（Bucket）中的檔案（Object），支援按首碼、目錄、起始位置等條件式篩選檔案。

使用方式

OSS Python SDK提供兩種列舉檔案的方法：ObjectIterator（基於GetBucket (ListObjects)介面）和ObjectIteratorV2（基於ListObjectsV2（GetBucketV2）介面）。兩種方法的主要區別：

ObjectIterator：預設返迴文件的owner資訊。
ObjectIteratorV2：通過fetch_owner參數控制是否返回owner資訊。
使用ObjectIteratorV2需要Python SDK版本為2.12.0及以上。

推薦使用ObjectIteratorV2，對開啟版本控制的Bucket提供更好的支援。

ObjectIteratorV2構造器聲明

oss2.ObjectIteratorV2(bucket, prefix='', delimiter='', continuation_token='', start_after='', fetch_owner=False, encoding_type = 'url', max_keys=100, max_retries=None, headers=None)

點擊查看參數說明

參數	類型	是否必選	說明
bucket	oss2.Bucket	是	已初始化的Bucket對象。
prefix	str	否	指定檔案名稱首碼進行篩選。預設為空白，返回所有檔案。
delimiter	str	否	用於類比檔案夾的定界符。通常設定為正斜線（/）。
continuation_token	str	否	分頁標誌。首次調用傳空串，後續使用傳回值的next_continuation_token。
start_after	str	否	分頁列舉的起始位置，返回字典序大於指定字串的所有檔案。即使儲存空間中存在start_after的同名檔案，返回結果中也不會包含這個檔案。
fetch_owner	bool	否	控制是否在返回結果中包含owner資訊。取值： - `True`：返回owner資訊。 - `False`（預設）：不返回owner資訊。
max_keys	int	否	單次請求返回的最大檔案數。預設為100，最大為1000。
max_retries	int	否	請求失敗時的最大重試次數。

ObjectIterator構造器聲明

oss2.ObjectIterator(bucket, prefix='', delimiter='', marker='', max_keys=100, max_retries=None, headers=None)

點擊查看參數說明

參數	類型	是否必選	說明
bucket	oss2.Bucket	是	已初始化的Bucket對象。
prefix	str	否	指定檔案名稱首碼進行篩選。預設為空白，返回所有檔案。
delimiter	str	否	用於類比檔案夾的定界符。通常設定為正斜線（/）。
marker	str	否	分頁列舉的起始位置，返回字典序大於指定字串的所有檔案。即使儲存空間中存在marker的同名檔案，返回結果中也不會包含這個檔案。
max_keys	int	否	單次請求返回的最大檔案數。預設為100，最大為1000。
max_retries	int	否	請求失敗時的最大重試次數。

程式碼範例

運行代碼前請先安裝Python SDK並完成訪問憑證環境變數配置，具體操作參見Python SDK快速入門。阿里雲主帳號預設具有所有許可權，如果使用RAM使用者或RAM角色，需確保相應的使用者或角色具有oss:ListObjects許可權。

列舉所有檔案

ObjectIteratorV2（推薦）

#!/usr/bin/env python3
# -*- coding: utf-8 -*-
import oss2
from oss2.credentials import EnvironmentVariableCredentialsProvider

def main():
    # 從環境變數擷取訪問憑證
    auth = oss2.ProviderAuthV4(EnvironmentVariableCredentialsProvider())

    # 設定Bucket所在地區的Endpoint和Region
    endpoint = "https://oss-cn-hangzhou.aliyuncs.com"
    region = "cn-hangzhou"
    # 初始化Bucket
    bucket = oss2.Bucket(auth, endpoint, "example-bucket", region=region)

    # 列舉Bucket下的所有檔案
    print("列舉所有檔案：")
    for obj in oss2.ObjectIteratorV2(bucket):
        print(f"檔案名稱: {obj.key}, 大小: {obj.size} 位元組")


if __name__ == "__main__":
    main()

如果需要擷取檔案的owner資訊，需設定fetch_owner=True：

# 列舉所有檔案並擷取owner資訊
for obj in oss2.ObjectIteratorV2(bucket, fetch_owner=True):
    print(f"檔案名稱: {obj.key}")
    print(f"Owner名稱: {obj.owner.display_name}")
    print(f"Owner ID: {obj.owner.id}")

ObjectIterator

#!/usr/bin/env python3
# -*- coding: utf-8 -*-
import oss2
from oss2.credentials import EnvironmentVariableCredentialsProvider

def main():
    # 從環境變數擷取訪問憑證
    auth = oss2.ProviderAuthV4(EnvironmentVariableCredentialsProvider())

    # 設定Bucket所在地區的Endpoint和Region
    endpoint = "https://oss-cn-hangzhou.aliyuncs.com"
    region = "cn-hangzhou"
    # 初始化Bucket
    bucket = oss2.Bucket(auth, endpoint, "example-bucket", region=region)

    # 列舉Bucket下的所有檔案
    print("列舉所有檔案：")
    for obj in oss2.ObjectIterator(bucket):
        print(f"檔案名稱: {obj.key}, 大小: {obj.size} 位元組")


if __name__ == "__main__":
    main()

列舉指定個數的檔案

ObjectIteratorV2（推薦）

#!/usr/bin/env python3
# -*- coding: utf-8 -*-
import oss2
from oss2.credentials import EnvironmentVariableCredentialsProvider
from itertools import islice

def main():
    # 從環境變數擷取訪問憑證
    auth = oss2.ProviderAuthV4(EnvironmentVariableCredentialsProvider())

    # 設定Bucket所在地區的Endpoint和Region
    endpoint = "https://oss-cn-hangzhou.aliyuncs.com"
    region = "cn-hangzhou"
    # 初始化Bucket
    bucket = oss2.Bucket(auth, endpoint, "example-bucket", region=region)

    # 列舉Bucket下的前10個檔案
    print("列舉前10個檔案：")
    for obj in islice(oss2.ObjectIteratorV2(bucket), 10):
        print(f"檔案名稱: {obj.key}")


if __name__ == "__main__":
    main()

ObjectIterator

#!/usr/bin/env python3
# -*- coding: utf-8 -*-
import oss2
from oss2.credentials import EnvironmentVariableCredentialsProvider
from itertools import islice

def main():
    # 從環境變數擷取訪問憑證
    auth = oss2.ProviderAuthV4(EnvironmentVariableCredentialsProvider())

    # 設定Bucket所在地區的Endpoint和Region
    endpoint = "https://oss-cn-hangzhou.aliyuncs.com"
    region = "cn-hangzhou"
    # 初始化Bucket
    bucket = oss2.Bucket(auth, endpoint, "example-bucket", region=region)

    # 列舉Bucket下的前10個檔案
    print("列舉前10個檔案：")
    for obj in islice(oss2.ObjectIterator(bucket), 10):
        print(f"檔案名稱: {obj.key}")


if __name__ == "__main__":
    main()

列舉指定首碼的檔案

假設Bucket中有4個檔案：oss.jpg、fun/test.jpg、fun/movie/001.avi、fun/movie/007.avi，正斜線（/）作為檔案夾的分隔字元。

ObjectIteratorV2（推薦）

#!/usr/bin/env python3
# -*- coding: utf-8 -*-
import oss2
from oss2.credentials import EnvironmentVariableCredentialsProvider

def main():
    # 從環境變數擷取訪問憑證
    auth = oss2.ProviderAuthV4(EnvironmentVariableCredentialsProvider())
    
    # 設定Bucket所在地區的Endpoint和Region
    endpoint = "https://oss-cn-hangzhou.aliyuncs.com"
    region = "cn-hangzhou"
    # 初始化Bucket
    bucket = oss2.Bucket(auth, endpoint, "example-bucket", region=region)
    
    # 列舉fun檔案夾下的所有檔案，包括子目錄下的檔案
    print("列舉首碼為fun/的所有檔案：")
    for obj in oss2.ObjectIteratorV2(bucket, prefix='fun/'):
        print(f"檔案名稱: {obj.key}")

if __name__ == "__main__":
    main()

預期輸出：

列舉首碼為fun/的所有檔案：
檔案名稱: fun/
檔案名稱: fun/movie/
檔案名稱: fun/movie/001.avi
檔案名稱: fun/movie/007.avi
檔案名稱: fun/test.jpg

ObjectIterator

#!/usr/bin/env python3
# -*- coding: utf-8 -*-
import oss2
from oss2.credentials import EnvironmentVariableCredentialsProvider

def main():
    # 從環境變數擷取訪問憑證
    auth = oss2.ProviderAuthV4(EnvironmentVariableCredentialsProvider())
    
    # 設定Bucket所在地區的Endpoint和Region
    endpoint = "https://oss-cn-hangzhou.aliyuncs.com"
    region = "cn-hangzhou"
    # 初始化Bucket
    bucket = oss2.Bucket(auth, endpoint, "example-bucket", region=region)
    
    # 列舉fun檔案夾下的所有檔案，包括子目錄下的檔案
    print("列舉首碼為fun/的所有檔案：")
    for obj in oss2.ObjectIterator(bucket, prefix='fun/'):
        print(f"檔案名稱: {obj.key}")

if __name__ == "__main__":
    main()

預期輸出：

列舉首碼為fun/的所有檔案：
檔案名稱: fun/
檔案名稱: fun/movie/
檔案名稱: fun/movie/001.avi
檔案名稱: fun/movie/007.avi
檔案名稱: fun/test.jpg

OSS沒有檔案夾的概念，所有元素都是以檔案來儲存。建立檔案夾本質上是建立了一個大小為0並以正斜線（/）結尾的檔案。控制台會將以正斜線（/）結尾的檔案以檔案夾的方式展示。

通過delimiter和prefix兩個參數可以類比檔案夾功能：

如果設定prefix為某個檔案夾名稱，會列舉以此prefix開頭的檔案，即該檔案夾下所有的檔案和子檔案夾（包括子檔案夾下的檔案）。
如果再設定delimiter為正斜線（/），則只列舉該檔案夾下的檔案和子檔案夾（目錄）名稱，子檔案夾下的檔案不會顯示。

ObjectIteratorV2（推薦）

#!/usr/bin/env python3
# -*- coding: utf-8 -*-
import oss2
from oss2.credentials import EnvironmentVariableCredentialsProvider

def main():
    # 從環境變數擷取訪問憑證
    auth = oss2.ProviderAuthV4(EnvironmentVariableCredentialsProvider())
    
    # 設定Bucket所在地區的Endpoint和Region
    endpoint = "https://oss-cn-hangzhou.aliyuncs.com"
    region = "cn-hangzhou"
    # 初始化Bucket
    bucket = oss2.Bucket(auth, endpoint, "example-bucket", region=region)
    
    # 列舉fun檔案夾下的檔案與子檔案夾名稱，不列舉子檔案夾下的檔案
    print("列舉fun目錄下的檔案和子目錄：")
    for obj in oss2.ObjectIteratorV2(bucket, prefix='fun/', delimiter='/', start_after='fun/'):
        # 通過is_prefix方法判斷obj是否為檔案夾
        if obj.is_prefix():
            print(f"子目錄: {obj.key}")
        else:
            print(f"檔案: {obj.key}")

if __name__ == "__main__":
    main()

預期輸出：

列舉fun目錄下的檔案和子目錄：
子目錄: fun/movie/
檔案: fun/test.jpg

ObjectIterator

#!/usr/bin/env python3
# -*- coding: utf-8 -*-
import oss2
from oss2.credentials import EnvironmentVariableCredentialsProvider

def main():
    # 從環境變數擷取訪問憑證
    auth = oss2.ProviderAuthV4(EnvironmentVariableCredentialsProvider())
    
    # 設定Bucket所在地區的Endpoint和Region
    endpoint = "https://oss-cn-hangzhou.aliyuncs.com"
    region = "cn-hangzhou"
    # 初始化Bucket
    bucket = oss2.Bucket(auth, endpoint, "example-bucket", region=region)
    
    # 列舉fun檔案夾下的檔案與子檔案夾名稱，不列舉子檔案夾下的檔案
    print("列舉fun目錄下的檔案和子目錄：")
    for obj in oss2.ObjectIterator(bucket, prefix='fun/', delimiter='/', marker='fun/'):
        # 通過is_prefix方法判斷obj是否為檔案夾
        if obj.is_prefix():
            print(f"子目錄: {obj.key}")
        else:
            print(f"檔案: {obj.key}")

if __name__ == "__main__":
    main()

預期輸出：

列舉fun目錄下的檔案和子目錄：
子目錄: fun/movie/
檔案: fun/test.jpg

列舉指定起始位置後的檔案

假設Bucket中包含4個檔案，分別為x1.txt、x2.txt、z1.txt和z2.txt。

ObjectIteratorV2（推薦）

#!/usr/bin/env python3
# -*- coding: utf-8 -*-
import oss2
from oss2.credentials import EnvironmentVariableCredentialsProvider

def main():
    # 從環境變數擷取訪問憑證
    auth = oss2.ProviderAuthV4(EnvironmentVariableCredentialsProvider())
    
    # 設定Bucket所在地區的Endpoint和Region
    endpoint = "https://oss-cn-hangzhou.aliyuncs.com"
    region = "cn-hangzhou"
    # 初始化Bucket
    bucket = oss2.Bucket(auth, endpoint, "example-bucket", region=region)
    
    # 列舉x2.txt之後的所有檔案（不包含x2.txt本身）
    print("列舉x2.txt之後的所有檔案：")
    for obj in oss2.ObjectIteratorV2(bucket, start_after="x2.txt"):
        print(f"檔案名稱: {obj.key}")

if __name__ == "__main__":
    main()

預期輸出：

列舉x2.txt之後的所有檔案：
檔案名稱: z1.txt
檔案名稱: z2.txt

ObjectIterator

#!/usr/bin/env python3
# -*- coding: utf-8 -*-
import oss2
from oss2.credentials import EnvironmentVariableCredentialsProvider

def main():
    # 從環境變數擷取訪問憑證
    auth = oss2.ProviderAuthV4(EnvironmentVariableCredentialsProvider())
    
    # 設定Bucket所在地區的Endpoint和Region
    endpoint = "https://oss-cn-hangzhou.aliyuncs.com"
    region = "cn-hangzhou"
    # 初始化Bucket
    bucket = oss2.Bucket(auth, endpoint, "example-bucket", region=region)
    
    # 列舉x2.txt之後的所有檔案（不包含x2.txt本身）
    print("列舉x2.txt之後的所有檔案：")
    for obj in oss2.ObjectIterator(bucket, marker="x2.txt"):
        print(f"檔案名稱: {obj.key}")

if __name__ == "__main__":
    main()

預期輸出：

列舉x2.txt之後的所有檔案：
檔案名稱: z1.txt
檔案名稱: z2.txt

擷取指定目錄下的檔案大小

ObjectIteratorV2（推薦）

#!/usr/bin/env python3
# -*- coding: utf-8 -*-
import oss2
from oss2.credentials import EnvironmentVariableCredentialsProvider

def calculate_folder_size(bucket, folder):
    """計算指定檔案夾的總大小"""
    total_size = 0
    for obj in oss2.ObjectIteratorV2(bucket, prefix=folder):
        total_size += obj.size
    return total_size

def main():
    # 從環境變數擷取訪問憑證
    auth = oss2.ProviderAuthV4(EnvironmentVariableCredentialsProvider())
    
    # 設定Bucket所在地區的Endpoint和Region
    endpoint = "https://oss-cn-hangzhou.aliyuncs.com"
    region = "cn-hangzhou"
    # 初始化Bucket
    bucket = oss2.Bucket(auth, endpoint, "example-bucket", region=region)
    
    # 列舉根目錄下的所有檔案和檔案夾，並顯示大小
    print("列舉根目錄下的檔案和檔案夾大小：")
    for obj in oss2.ObjectIteratorV2(bucket, delimiter='/'):
        if obj.is_prefix():
            # 計算檔案夾的總大小
            folder_size = calculate_folder_size(bucket, obj.key)
            print(f"目錄: {obj.key}, 大小: {folder_size} 位元組")
        else:
            # 直接顯示檔案大小
            print(f"檔案: {obj.key}, 大小: {obj.size} 位元組")

if __name__ == "__main__":
    main()

ObjectIterator

#!/usr/bin/env python3
# -*- coding: utf-8 -*-
import oss2
from oss2.credentials import EnvironmentVariableCredentialsProvider

def calculate_folder_size(bucket, folder):
    """計算指定檔案夾的總大小"""
    total_size = 0
    for obj in oss2.ObjectIterator(bucket, prefix=folder):
        total_size += obj.size
    return total_size

def main():
    # 從環境變數擷取訪問憑證
    auth = oss2.ProviderAuthV4(EnvironmentVariableCredentialsProvider())
    
    # 設定Bucket所在地區的Endpoint和Region
    endpoint = "https://oss-cn-hangzhou.aliyuncs.com"
    region = "cn-hangzhou"
    # 初始化Bucket
    bucket = oss2.Bucket(auth, endpoint, "example-bucket", region=region)
    
    # 列舉根目錄下的所有檔案和檔案夾，並顯示大小
    print("列舉根目錄下的檔案和檔案夾大小：")
    for obj in oss2.ObjectIterator(bucket, delimiter='/'):
        if obj.is_prefix():
            # 計算檔案夾的總大小
            folder_size = calculate_folder_size(bucket, obj.key)
            print(f"目錄: {obj.key}, 大小: {folder_size} 位元組")
        else:
            # 直接顯示檔案大小
            print(f"檔案: {obj.key}, 大小: {obj.size} 位元組")

if __name__ == "__main__":
    main()

Object Storage Service：列舉檔案（Python SDK V1）

使用方式

程式碼範例

列舉所有檔案

ObjectIteratorV2（推薦）

ObjectIterator

列舉指定個數的檔案

ObjectIteratorV2（推薦）

ObjectIterator

列舉指定首碼的檔案

ObjectIteratorV2（推薦）

ObjectIterator

列舉指定目錄下的檔案和子目錄

ObjectIteratorV2（推薦）

ObjectIterator

列舉指定起始位置後的檔案

ObjectIteratorV2（推薦）

ObjectIterator

擷取指定目錄下的檔案大小

ObjectIteratorV2（推薦）

ObjectIterator