ネットワークが不安定な場合やその他の例外が発生した場合、大きなオブジェクトのダウンロードに失敗することがあります。 場合によっては、複数回試行してもオブジェクトのダウンロードに失敗することがあります。 この問題を解決するために、Object Storage Service (OSS) は再開可能なダウンロード機能を提供しています。 再開可能ダウンロードでは、OSSはオブジェクトを複数のパーツに分割し、各パーツを個別にダウンロードします。 すべてのパーツがダウンロードされた後、OSSはパーツを完全なオブジェクトに結合します。
使用上の注意
このトピックでは、中国 (杭州) リージョンのパブリックエンドポイントを使用します。 OSSと同じリージョンにある他のAlibaba CloudサービスからOSSにアクセスする場合は、内部エンドポイントを使用します。 OSSリージョンとエンドポイントの詳細については、「リージョン、エンドポイント、オープンポート」をご参照ください。
このトピックでは、アクセス資格情報は環境変数から取得します。 アクセス資格情報の設定方法の詳細については、「アクセス資格情報の設定」をご参照ください。
このトピックでは、OSSエンドポイントを使用してOSSClientインスタンスを作成します。 カスタムドメイン名またはSTS (Security Token Service) を使用してOSSClientインスタンスを作成する場合は、「初期化」をご参照ください。
再開可能ダウンロードを使用するには、
oss:GetObject権限が必要です。 詳細については、「RAMユーザーへのカスタムポリシーのアタッチ」をご参照ください。
手順
再開可能ダウンロードを使用するには、次の手順を実行します。
元のオブジェクト名とランダムなサフィックスで構成される名前を持つ一時ローカルファイルを作成します。
範囲に基づいてオブジェクトが読み取られるように、HTTPリクエストにRangeヘッダーを指定します。 そして、読み出されたコンテンツは、一時ローカルファイルの対応する位置に書き込まれる。
ダウンロードが完了したら、一時ファイルの名前を宛先ファイルに変更します。 宛先ファイルがすでに存在する場合、ダウンロードされたデータは既存のファイルのデータを上書きします。 それ以外の場合は、新しいファイルが作成されます。
1つのチェックポイント情報がローカルディスク上の別のチェックポイント情報を上書きするか、1つの一時ファイル名が別のファイル名と競合します。 したがって、複数のプログラムまたはスレッドを使用してoss2.resumable_downloadメソッドを同時に呼び出して、同じオブジェクトを同じ宛先ファイルにダウンロードしないでください。
例
次のサンプルコードは、再開可能ダウンロードの実行方法の例を示しています。
# -*- coding: utf-8 -*-
import oss2
from oss2.credentials import EnvironmentVariableCredentialsProvider
# Obtain access credentials from the environment variables. Before you run the sample code, make sure that you have configured environment variables OSS_ACCESS_KEY_ID and OSS_ACCESS_KEY_SECRET.
auth = oss2.ProviderAuthV4(EnvironmentVariableCredentialsProvider())
# Specify the endpoint of the region in which the bucket is located. For example, if the bucket is located in the China (Hangzhou) region, set the endpoint to https://oss-cn-hangzhou.aliyuncs.com.
endpoint = "https://oss-cn-hangzhou.aliyuncs.com"
# Specify the ID of the region that maps to the endpoint. Example: cn-hangzhou. This parameter is required if you use the signature algorithm V4.
region = "cn-hangzhou"
# Specify the name of your bucket.
bucket = oss2.Bucket(auth, endpoint, "yourBucketName", region=region)
# Specify the full path of the object. Do not include the bucket name in the full path. Example: exampledir/exampleobject.txt.
# Specify the full path of the local file. Example: D:\\localpath\\examplefile.txt.
oss2.resumable_download(bucket, 'exampledir/exampleobject.txt', 'D:\\localpath\\examplefile.txt')
# If you do not specify a directory by using the store parameter, the .py-oss-upload directory is created in the HOME directory to store the checkpoint information.
# You can configure the following optional parameters if you use OSS SDK for Python version 2.1.0 or later.
# import sys
# # If the length of the data to download cannot be determined, the value of total_bytes is None.
# def percentage(consumed_bytes, total_bytes):
# if total_bytes:
# rate = int(100 * (float(consumed_bytes) / float(total_bytes)))
# print('\r{0}% '.format(rate), end='')
# sys.stdout.flush()
# # If you use the store parameter to specify a directory, the checkpoint information is stored in the specified directory. If you use the num_threads parameter to specify the number of concurrent download threads, make sure that the value of oss2.defaults.connection_pool_size is greater than or equal to the number of concurrent download threads. The default number of concurrent threads is 1.
# oss2.resumable_download(bucket, 'exampledir/exampleobject.txt', 'D:\\localpath\\examplefile.txt',
# store=oss2.ResumableDownloadStore(root='/tmp'),
# # Specify that resumable download is used when the length of the object is greater than or equal to the value of the multipart_threshold parameter. The multipart_threshold parameter is optional and its default value is 10 MB.
# multiget_threshold=100*1024,
# # Specify the size of each part. Unit: bytes. The valid part size ranges from 100 KB to 5 GB. The default part size is 100 KB.
# part_size=100*1024,
# # Configure the callback function that you want to use to indicate the progress of the resumable download task.
# progress_callback=percentage,
# # If you use num_threads to set the number of concurrent download threads, set oss2.defaults.connection_pool_size to a value that is greater than or equal to the number of concurrent download threads. The default number of concurrent threads is 1.
# num_threads=4)