When you upload an object to Object Storage Service (OSS) by using resumable upload, you can specify a directory for the checkpoint file that stores resumable upload progress. If an object fails to be uploaded because of a network exception or program error, the upload task is resumed from the position recorded in the checkpoint file.
Usage notes
In this topic, the public endpoint of the China (Hangzhou) region is used. If you want to access OSS from other Alibaba Cloud services in the same region as OSS, use an internal endpoint. For more information about OSS regions and endpoints, see Regions, endpoints and open ports.
In this topic, access credentials are obtained from environment variables. For more information about how to configure access credentials, see Configure access credentials.
In this topic, an OSSClient instance is created by using an OSS endpoint. If you want to create an OSSClient instance by using custom domain names or Security Token Service (STS), see Initialization.
To perform resumable upload, you must have the
oss:PutObject
and oss:ListParts permissions. For more information, see Attach a custom policy to a RAM user.Multiple threads are used in resumable upload. Therefore, you do not need to encapsulate multiple upload threads when you use the resumable upload method. Otherwise, data may be transmitted repeatedly.
We recommend that you increase the size of each part when the network connection is stable and decrease the size of each part when the network connection is unstable.
Examples
The following sample code provides an example on how to perform resumable upload:
# -*- coding: utf-8 -*-
import oss2
from oss2.credentials import EnvironmentVariableCredentialsProvider
# Obtain access credentials from environment variables. Before you run the sample code, make sure that the OSS_ACCESS_KEY_ID and OSS_ACCESS_KEY_SECRET environment variables are configured.
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. By default, if you do not specify the full path of the local file, the local file is uploaded from the path of the project to which the sample program belongs.
oss2.resumable_upload(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.
# OSS SDK for Python 2.1.0 and later support the configuration of optional parameters in resumable upload. The following code provides an example on how to configure optional parameters in resumable upload:
# import sys
# # If the length of the data that you want to upload 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 upload threads, make sure that the value of oss2.defaults.connection_pool_size is greater than or equal to the number of concurrent upload threads. The default number of concurrent upload threads is 1.
# oss2.resumable_upload(bucket, '<yourObjectName>', '<yourLocalFile>',
# store=oss2.ResumableStore(root='/tmp'),
# # Specify that multipart upload is used when the object size is greater than or equal to the value of multipart_threshold. The default value of multipart_threshold is 10 MB.
# multipart_threshold=100*1024,
# # Specify the size of each part. Unit: bytes. Valid values: 100 KB to 5 GB. Default value: 100 KB.
# part_size=100*1024,
# # Configure the function used to indicate the progress of the resumable upload task by implementing upload callback.
# progress_callback=percentage,
# # If you use the num_threads parameter to specify the number of concurrent upload threads, make sure that the value of oss2.defaults.connection_pool_size is greater than or equal to the number of concurrent upload threads. The default number of concurrent upload threads is 1.
# num_threads=4)
References
For the complete sample code for resumable upload, visit GitHub.