OSS Python SDK V2 を使用してファイルをダウンロードする方法 - Object Storage Service

このトピックでは、Python SDK V2 の Downloader モジュールを使用してファイルをダウンロードする方法について説明します。

使用上の注意

このトピックのサンプルコードでは、リージョン ID が cn-hangzhou の中国 (杭州) リージョンを例として使用します。デフォルトでは、パブリックエンドポイントが使用されます。同じリージョン内の他の Alibaba Cloud サービスから OSS にアクセスする場合は、内部エンドポイントを使用してください。OSS がサポートするリージョンとエンドポイントの詳細については、「リージョンとエンドポイント」をご参照ください。
ファイルをダウンロードするには、oss:GetObject 権限が必要です。詳細については、「RAM ユーザーへのカスタムポリシーのアタッチ」をご参照ください。

メソッド定義

Downloader の特徴

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 = 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	パートサイズを指定します。デフォルト値は 6 MiB です。
parallel_num	int	同時ダウンロードタスクの数を指定します。デフォルト値は 3 です。このパラメーターは、グローバルな同時実行数制限ではなく、単一の呼び出しの同時実行数制限を指定します。
enable_checkpoint	bool	再開可能なダウンロード機能を有効にするかどうかを指定します。デフォルトでは、この機能は無効になっています。
checkpoint_dir	str	レコードファイルを保存するパスを指定します。例: /local/dir/。このパラメーターは、enable_checkpoint が True に設定されている場合にのみ有効です。
verify_data	bool	ダウンロードが再開されたときに、ダウンロードされたデータの CRC-64 値を検証するかどうかを指定します。デフォルトでは、値は検証されません。このパラメーターは、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)
# 他のサービスが OSS にアクセスするために使用できるドメイン名を示すコマンドライン引数 --endpoint を追加します。この引数はオプションです。
parser.add_argument('--endpoint', help='The domain names that other services can use to access OSS')
# OSS 内のオブジェクト (ファイル) のキーを示すコマンドライン引数 --key を追加します。この引数は必須です。
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()

    # ID 検証のために、環境変数から OSS へのアクセスに必要な認証情報を読み込みます。
    credentials_provider = oss.credentials.EnvironmentVariableCredentialsProvider()

    # SDK のデフォルト構成を使用して構成オブジェクトを作成し、認証プロバイダーを設定します。
    cfg = oss.config.load_default()
    cfg.credentials_provider = credentials_provider
    
    # ユーザーが指定したコマンドライン引数に基づいて、構成オブジェクトのリージョンプロパティを設定します。
    cfg.region = args.region

    # カスタムエンドポイントが指定されている場合は、構成オブジェクトのエンドポイントプロパティを更新します。
    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)
# 他のサービスが OSS にアクセスするために使用できるドメイン名を示すコマンドライン引数 --endpoint を追加します。この引数はオプションです。
parser.add_argument('--endpoint', help='The domain names that other services can use to access OSS')
# OSS 内のオブジェクト (ファイル) のキーを示すコマンドライン引数 --key を追加します。この引数は必須です。
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()

    # ID 検証のために、環境変数から OSS へのアクセスに必要な認証情報を読み込みます。
    credentials_provider = oss.credentials.EnvironmentVariableCredentialsProvider()

    # SDK のデフォルト構成を使用して構成オブジェクトを作成し、認証プロバイダーを設定します。
    cfg = oss.config.load_default()
    cfg.credentials_provider = credentials_provider
    
    # ユーザーが指定したコマンドライン引数に基づいて、構成オブジェクトのリージョンプロパティを設定します。
    cfg.region = args.region

    # カスタムエンドポイントが指定されている場合は、構成オブジェクトのエンドポイントプロパティを更新します。
    if args.endpoint is not None:
        cfg.endpoint = args.endpoint

    # 前述の構成を使用して OSS クライアントを初期化し、OSS と対話します。
    client = oss.Client(cfg)

    # ファイルをダウンロードするためのオブジェクトを作成し、詳細オプションを設定します。
    downloader = client.downloader(
        part_size=1024 * 1024,  # 各パートのサイズを 1 MB に設定します。
        parallel_num=5,         # 同時ダウンロードスレッドの数を 5 に設定します。
        block_size=1024 * 1024  # 毎回読み取るデータブロックのサイズを 1 MB に設定します。
    )

    # メソッドを呼び出して、ファイルダウンロード操作を実行します。
    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)
# 他のサービスが OSS にアクセスするために使用できるドメイン名を示すコマンドライン引数 --endpoint を追加します。この引数はオプションです。
parser.add_argument('--endpoint', help='The domain names that other services can use to access OSS')
# OSS 内のオブジェクト (ファイル) のキーを示すコマンドライン引数 --key を追加します。この引数は必須です。
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()

    # ID 検証のために、環境変数から OSS へのアクセスに必要な認証情報を読み込みます。
    credentials_provider = oss.credentials.EnvironmentVariableCredentialsProvider()

    # SDK のデフォルト構成を使用して構成オブジェクトを作成し、認証プロバイダーを設定します。
    cfg = oss.config.load_default()
    cfg.credentials_provider = credentials_provider
    
    # ユーザーが指定したコマンドライン引数に基づいて、構成オブジェクトのリージョンプロパティを設定します。
    cfg.region = args.region

    # カスタムエンドポイントが指定されている場合は、構成オブジェクトのエンドポイントプロパティを更新します。
    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)
# 他のサービスが OSS にアクセスするために使用できるドメイン名を示すコマンドライン引数 --endpoint を追加します。この引数はオプションです。
parser.add_argument('--endpoint', help='The domain names that other services can use to access OSS')
# OSS 内のオブジェクト (ファイル) のキーを示すコマンドライン引数 --key を追加します。この引数は必須です。
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()

    # ID 検証のために、環境変数から OSS へのアクセスに必要な認証情報を読み込みます。
    credentials_provider = oss.credentials.EnvironmentVariableCredentialsProvider()

    # SDK のデフォルト構成を使用して構成オブジェクトを作成し、認証プロバイダーを設定します。
    cfg = oss.config.load_default()
    cfg.credentials_provider = credentials_provider

    # ユーザーが指定したコマンドライン引数に基づいて、構成オブジェクトのリージョンプロパティを設定します。
    cfg.region = args.region

    # カスタムエンドポイントが指定されている場合は、構成オブジェクトのエンドポイントプロパティを更新します。
    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 が現在の行を上書きするようにします。
        print(f'\rDownload progress: {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()  # スクリプトのエントリポイント。ここからプログラムフローが開始されます。

参照

ダウンロードマネージャーの詳細については、「開発者ガイド」をご参照ください。
ダウンロードマネージャーの完全なサンプルコードについては、「download_file.py」をご参照ください。