Object Storage Service:Resumable download (Python SDK V1)

Prerequisites

Before you begin, ensure that you have:

• An OSS bucket with the object to download

• The oss:GetObject permission. For details, see Attach a custom policy to a RAM user

• The OSS_ACCESS_KEY_ID and OSS_ACCESS_KEY_SECRET environment variables set with valid access credentials

How it works

1. OSS creates a temporary file on the local disk. The file name is the target file name plus a random suffix.

2. OSS reads the object in ranges using the Range header in each HTTP request and writes the data to the corresponding position in the temporary file.

3. After all parts are downloaded, OSS renames the temporary file to the target file name. If a file with the same name already exists, it is overwritten.

Download an object

The following example downloads an object from OSS to a local file using resumable download.

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

# Load access credentials from environment variables.
# Set OSS_ACCESS_KEY_ID and OSS_ACCESS_KEY_SECRET before running this example.
auth = oss2.ProviderAuthV4(EnvironmentVariableCredentialsProvider())

# Replace the endpoint with the one for your bucket's region.
# Example: https://oss-cn-hangzhou.aliyuncs.com for the China (Hangzhou) region.
endpoint = "https://oss-cn-hangzhou.aliyuncs.com"

# region is required for V4 signatures.
region = "cn-hangzhou"

bucket = oss2.Bucket(auth, endpoint, "examplebucket", region=region)

# Download the object to a local file.
# Replace exampledir/exampleobject.txt with the full object path (without the bucket name).
# Replace D:\\localpath\\examplefile.txt with the full path of the destination file.
oss2.resumable_download(
    bucket,
    "exampledir/exampleobject.txt",
    "D:\\localpath\\examplefile.txt"
)
# Breakpoint information is saved in the .py-oss-upload folder in your HOME directory by default.

If you access OSS from another Alibaba Cloud service in the same region, use the internal endpoint to reduce latency and avoid data transfer costs. For endpoint formats, see Regions and endpoints.

Configure download options (Python SDK 2.1.0+)

Use optional parameters to control part size, concurrency, breakpoint storage, and progress reporting.

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

auth = oss2.ProviderAuthV4(EnvironmentVariableCredentialsProvider())
endpoint = "https://oss-cn-hangzhou.aliyuncs.com"
region = "cn-hangzhou"
bucket = oss2.Bucket(auth, endpoint, "examplebucket", region=region)

# Progress callback: prints download percentage to stdout.
# If the total size cannot be determined, 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()

# Set the connection pool size to at least the number of concurrent threads.
oss2.defaults.connection_pool_size = 4

oss2.resumable_download(
    bucket,
    "exampledir/exampleobject.txt",
    "D:\\localpath\\examplefile.txt",
    store=oss2.ResumableDownloadStore(root="/tmp"),  # Save breakpoints to /tmp
    multiget_threshold=10 * 1024 * 1024,             # Trigger resumable download for objects >= 10 MB
    part_size=100 * 1024,                            # Download in 100 KB parts
    num_threads=4,                                   # Use 4 concurrent threads
    progress_callback=percentage
)

What's next

• For the complete sample code, see GitHub examples.

• For the underlying API operation, see GetObject.

• To create an OSSClient instance using custom domain names or Security Token Service (STS), see Initialization.