如何使用OSS Python SDK V2進行檔案下載 - Object Storage Service

本文針對檔案的傳輸情境，介紹如何使用Python SDK V2新增的下載管理員Downloader模組進行檔案下載。

注意事項

本文範例程式碼以華東1（杭州）的地區IDcn-hangzhou為例，預設使用外網Endpoint，如果您希望通過與OSS同地區的其他阿里雲產品訪問OSS，請使用內網Endpoint。關於OSS支援的Region與Endpoint的對應關係，請參見OSS地區和訪問網域名稱。
要進行檔案下載，您必須有oss:GetObject許可權。具體操作，請參見為RAM使用者授予自訂的權限原則。

方法定義

下載管理員功能簡介

Python SDK V2新增下載管理員Downloader提供了通用的下載方法，隱藏了底層方法的實現細節，提供便捷的檔案下載能力。

下載管理員Downloader底層利用範圍下載，把檔案自動分成多個較小的分區進行並發下載，提升下載的效能。
下載管理員Downloader同時提供了斷點續傳的能力，即在下載過程中，記錄已完成的分區狀態，如果出現網路中斷、程式異常退出等問題導致檔案下載失敗，甚至重試多次仍無法完成下載，再次下載時，可以通過斷點記錄檔案恢複下載。

下載管理員Downloader的常用方法如下：

class Downloader:
  ...

def downloader(self, **kwargs) -> Downloader:
  ...

def download_file(self, request: models.GetObjectRequest, filepath: str, **kwargs: Any) -> DownloadResult:
  ...
  
def download_to(self, request: models.GetObjectRequest, writer: IO[bytes], **kwargs: Any) -> DownloadResult:
  ...

請求參數列表

參數名	類型	說明
request	GetObjectRequest	下載對象的請求參數，和GetObject 方法的請求參數一致，具體請參見GetObjectRequest
filepath	str	本地檔案路徑
writer	IO[bytes]	下載的流
**kwargs	Any	(可選)任意參數，類型為字典

返回參數列表

類型	說明
DownloadResult	下載對象的返回參數，具體請參見DownloadResult

當您使用client.downloader初始化下載管理員執行個體時，您可以指定多個配置選項來自訂下載行為，也可以在每次調用下載介面時，指定多個配置選項來自訂每次下載對象的行為。例如指定分區大小如下所示。

設定downloader的配置參數

downloader = client.downloader(part_size=1024 * 1024)

設定每次下載請求的配置參數

result = downloader.download_file(oss.GetObjectRequest(
    bucket="example_bucket",
    key="example_key",
),
    filepath="/local/dir/example",
    part_size=10 * 1024 * 1024,
)

常用的配置選項說明列舉如下：

參數名	類型	說明
part_size	int	指定分區大小，預設值為 6MiB
parallel_num	int	指定下載任務的並發數，預設值為 3。針對的是單次調用的並發限制，而不是全域的並發限制
enable_checkpoint	bool	是否開啟斷點下載功能，預設不開啟
checkpoint_dir	str	指定記錄檔案的儲存路徑，例如 /local/dir/, 當enable_checkpoint 為True時有效
verify_data	bool	恢複下載時，是否要校正已下載資料的CRC64值，預設不校正, 當enable_checkpoint 為True時有效
use_temp_file	bool	下載檔案時，是否使用臨時檔案，預設使用。先下載到臨時檔案上，當成功後，再重新命名為目標檔案

關於檔案下載管理員方法的完整定義，請參見Downloader。

範例程式碼

您可以使用以下代碼將儲存空間中的檔案下載到本地。

import argparse
import alibabacloud_oss_v2 as oss

# 建立一個命令列參數解析器，並描述指令碼用途：下載檔案樣本
parser = argparse.ArgumentParser(description="download file sample")

# 添加命令列參數 --region，表示儲存空間所在的地區，必需參數
parser.add_argument('--region', help='The region in which the bucket is located.', required=True)
# 添加命令列參數 --bucket，表示要下載檔案的儲存空間名稱，必需參數
parser.add_argument('--bucket', help='The name of the bucket.', required=True)
# 添加命令列參數 --endpoint，表示其他服務可用來訪問OSS的網域名稱，非必需參數
parser.add_argument('--endpoint', help='The domain names that other services can use to access OSS')
# 添加命令列參數 --key，表示對象（檔案）在OSS中的鍵名，必需參數
parser.add_argument('--key', help='The name of the object.', required=True)
# 添加命令列參數 --file_path，表示下載檔案儲存的本地路徑，必需參數，例如“/Users/yourLocalPath/yourFileName”
parser.add_argument('--file_path', help='The path to save the downloaded file.', required=True)

def main():
    # 解析命令列提供的參數，擷取使用者輸入的值
    args = parser.parse_args()

    # 從環境變數中載入訪問OSS所需的認證資訊，用於身分識別驗證
    credentials_provider = oss.credentials.EnvironmentVariableCredentialsProvider()

    # 使用SDK的預設配置建立設定物件，並設定認證提供者
    cfg = oss.config.load_default()
    cfg.credentials_provider = credentials_provider
    
    # 設定設定物件的地區屬性，根據使用者提供的命令列參數
    cfg.region = args.region

    # 如果提供了自訂endpoint，則更新設定物件中的endpoint屬性
    if args.endpoint is not None:
        cfg.endpoint = args.endpoint

    # 使用上述配置初始化OSS用戶端，準備與OSS互動
    client = oss.Client(cfg)

    # 建立一個用於下載檔案的對象
    downloader = client.downloader()

    # 調用方法執行檔案下載操作
    result = downloader.download_file(
        oss.GetObjectRequest(
            bucket=args.bucket,  # 指定目標儲存空間
            key=args.key,        # 指定檔案在OSS中的名稱
        ),
        filepath=args.file_path  # 指定下載檔案儲存的本地路徑
    )

    # 列印下載結果的相關資訊，包括已寫入的位元組數
    print(f'written: {result.written}')

# 當此指令碼被直接執行時，調用main函數開始處理邏輯
if __name__ == "__main__":
    main()  # 指令碼進入點，控製程序流程從這裡開始

常見使用情境

使用下載管理員設定分區大小和並發數

您可以使用以下代碼配置下載管理員，設定分區大小和並發數。

import argparse
import alibabacloud_oss_v2 as oss

# 建立一個命令列參數解析器，並描述指令碼用途：下載檔案樣本
parser = argparse.ArgumentParser(description="download file sample")

# 添加命令列參數 --region，表示儲存空間所在的地區，必需參數
parser.add_argument('--region', help='The region in which the bucket is located.', required=True)
# 添加命令列參數 --bucket，表示要下載檔案的儲存空間名稱，必需參數
parser.add_argument('--bucket', help='The name of the bucket.', required=True)
# 添加命令列參數 --endpoint，表示其他服務可用來訪問OSS的網域名稱，非必需參數
parser.add_argument('--endpoint', help='The domain names that other services can use to access OSS')
# 添加命令列參數 --key，表示對象（檔案）在OSS中的鍵名，必需參數
parser.add_argument('--key', help='The name of the object.', required=True)
# 添加命令列參數 --file_path，表示下載檔案儲存的本地路徑，必需參數，例如“/Users/yourLocalPath/yourFileName”
parser.add_argument('--file_path', help='The path to save the downloaded file.', required=True)

def main():
    # 解析命令列提供的參數，擷取使用者輸入的值
    args = parser.parse_args()

    # 從環境變數中載入訪問OSS所需的認證資訊，用於身分識別驗證
    credentials_provider = oss.credentials.EnvironmentVariableCredentialsProvider()

    # 使用SDK的預設配置建立設定物件，並設定認證提供者
    cfg = oss.config.load_default()
    cfg.credentials_provider = credentials_provider
    
    # 設定設定物件的地區屬性，根據使用者提供的命令列參數
    cfg.region = args.region

    # 如果提供了自訂endpoint，則更新設定物件中的endpoint屬性
    if args.endpoint is not None:
        cfg.endpoint = args.endpoint

    # 使用上述配置初始化OSS用戶端，準備與OSS互動
    client = oss.Client(cfg)

    # 建立一個用於下載檔案的對象，並設定進階選項
    downloader = client.downloader(
        part_size=1024 * 1024,  # 設定每個分區的大小為1MB
        parallel_num=5,         # 設定並行下載的線程數為5
        block_size=1024 * 1024  # 設定每次讀取的資料區塊大小為1MB
    )

    # 調用方法執行檔案下載操作
    result = downloader.download_file(
        oss.GetObjectRequest(
            bucket=args.bucket,  # 指定目標儲存空間
            key=args.key,        # 指定檔案在OSS中的名稱
        ),
        filepath=args.file_path  # 指定下載檔案儲存的本地路徑
    )

    # 列印下載結果的相關資訊，包括已寫入的位元組數
    print(f'written: {result.written}')

# 當此指令碼被直接執行時，調用main函數開始處理邏輯
if __name__ == "__main__":
    main()  # 指令碼進入點，控製程序流程從這裡開始

使用下載管理員啟動斷點續傳功能

您可以使用以下代碼配置下載管理員，啟動斷點續傳功能。

import argparse
import alibabacloud_oss_v2 as oss

# 建立一個命令列參數解析器，並描述指令碼用途：下載檔案樣本
parser = argparse.ArgumentParser(description="download file sample")

# 添加命令列參數 --region，表示儲存空間所在的地區，必需參數
parser.add_argument('--region', help='The region in which the bucket is located.', required=True)
# 添加命令列參數 --bucket，表示要下載檔案的儲存空間名稱，必需參數
parser.add_argument('--bucket', help='The name of the bucket.', required=True)
# 添加命令列參數 --endpoint，表示其他服務可用來訪問OSS的網域名稱，非必需參數
parser.add_argument('--endpoint', help='The domain names that other services can use to access OSS')
# 添加命令列參數 --key，表示對象（檔案）在OSS中的鍵名，必需參數
parser.add_argument('--key', help='The name of the object.', required=True)
# 添加命令列參數 --file_path，表示下載檔案儲存的本地路徑，必需參數，例如“/Users/yourLocalPath/yourFileName”
parser.add_argument('--file_path', help='The path to save the downloaded file.', required=True)

def main():
    # 解析命令列提供的參數，擷取使用者輸入的值
    args = parser.parse_args()

    # 從環境變數中載入訪問OSS所需的認證資訊，用於身分識別驗證
    credentials_provider = oss.credentials.EnvironmentVariableCredentialsProvider()

    # 使用SDK的預設配置建立設定物件，並設定認證提供者
    cfg = oss.config.load_default()
    cfg.credentials_provider = credentials_provider
    
    # 設定設定物件的地區屬性，根據使用者提供的命令列參數
    cfg.region = args.region

    # 如果提供了自訂endpoint，則更新設定物件中的endpoint屬性
    if args.endpoint is not None:
        cfg.endpoint = args.endpoint

    # 使用上述配置初始化OSS用戶端，準備與OSS互動
    client = oss.Client(cfg)

    # 建立一個用於下載檔案的對象，並設定進階選項
    downloader = client.downloader(
        use_temp_file=True,            # 使用臨時檔案
        enable_checkpoint=True,        # 啟用斷點續傳
        checkpoint_dir=args.file_path, # 儲存斷點續傳記錄檔案的目錄
        verify_data=True               # 是否校正資料
    )

    # 調用方法執行檔案下載操作
    result = downloader.download_file(
        oss.GetObjectRequest(
            bucket=args.bucket,  # 指定目標儲存空間
            key=args.key,        # 指定檔案在OSS中的名稱
        ),
        filepath=args.file_path  # 指定下載檔案儲存的本地路徑
    )

    # 列印下載結果的相關資訊，包括已寫入的位元組數
    print(f'written: {result.written}')

# 當此指令碼被直接執行時，調用main函數開始處理邏輯
if __name__ == "__main__":
    main()  # 指令碼進入點，控製程序流程從這裡開始

使用下載管理員並顯示下載進度條

以下範例程式碼展示了在使用下載管理員下載檔案時，使用進度條查看下載檔案的進度。

import argparse
import alibabacloud_oss_v2 as oss

# 建立一個命令列參數解析器，並描述指令碼用途：下載檔案樣本
parser = argparse.ArgumentParser(description="download file sample")

# 添加命令列參數 --region，表示儲存空間所在的地區，必需參數
parser.add_argument('--region', help='The region in which the bucket is located.', required=True)
# 添加命令列參數 --bucket，表示要下載檔案的儲存空間名稱，必需參數
parser.add_argument('--bucket', help='The name of the bucket.', required=True)
# 添加命令列參數 --endpoint，表示其他服務可用來訪問OSS的網域名稱，非必需參數
parser.add_argument('--endpoint', help='The domain names that other services can use to access OSS')
# 添加命令列參數 --key，表示對象（檔案）在OSS中的鍵名，必需參數
parser.add_argument('--key', help='The name of the object.', required=True)
# 添加命令列參數 --file_path，表示下載檔案儲存的本地路徑，必需參數，例如“/Users/yourLocalPath/yourFileName”
parser.add_argument('--file_path', help='The path to save the downloaded file.', required=True)

def main():
    # 解析命令列提供的參數，擷取使用者輸入的值
    args = parser.parse_args()

    # 從環境變數中載入訪問OSS所需的認證資訊，用於身分識別驗證
    credentials_provider = oss.credentials.EnvironmentVariableCredentialsProvider()

    # 使用SDK的預設配置建立設定物件，並設定認證提供者
    cfg = oss.config.load_default()
    cfg.credentials_provider = credentials_provider

    # 設定設定物件的地區屬性，根據使用者提供的命令列參數
    cfg.region = args.region

    # 如果提供了自訂endpoint，則更新設定物件中的endpoint屬性
    if args.endpoint is not None:
        cfg.endpoint = args.endpoint

    # 使用上述配置初始化OSS用戶端，準備與OSS互動
    client = oss.Client(cfg)

    # 建立一個用於下載檔案的對象
    downloader = client.downloader()

    # 定義一個字典變數 progress_state 用於儲存下載進度狀態，初始值為 0
    progress_state = {'saved': 0}

    # 定義進度回呼函數 _progress_fn
    def _progress_fn(n, written, total):
        # 使用字典儲存累計寫入的位元組數
        progress_state['saved'] += n

        # 計算當前下載百分比，將已寫入位元組數與總位元組數進行除法運算後取整
        rate = int(100 * (float(written) / float(total)))

        # 列印當前下載進度，\r 表示回到行首，實現命令列中即時重新整理效果
        # end='' 表示不換行，使下一次列印覆蓋當前行
        print(f'\r下載進度：{rate}% ', end='')

    # 調用方法執行檔案下載操作
    result = downloader.download_file(
        oss.GetObjectRequest(
            bucket=args.bucket,  # 指定目標儲存空間
            key=args.key,        # 指定檔案在OSS中的名稱
            progress_fn=_progress_fn,  # 設定進度回呼函數
        ),
        filepath=args.file_path  # 指定下載檔案儲存的本地路徑
    )

    # 列印下載結果的相關資訊，包括已寫入的位元組數
    print(f'written: {result.written}')

# 當此指令碼被直接執行時，調用main函數開始處理邏輯
if __name__ == "__main__":
    main()  # 指令碼進入點，控製程序流程從這裡開始

Object Storage Service：檔案下載管理員（Python SDK V2）