How to upload files using Python SDK V2 - - Alibaba Cloud Documentation Center

This topic describes how to quickly upload a local file to Object Storage Service (OSS) using simple upload. This method is straightforward and suitable for scenarios where you need to quickly upload a local file.

Considerations

This example uses the region ID cn-hangzhou of China (Hangzhou) and the public endpoint by default. If you want to access OSS from other Alibaba Cloud services in the same region as OSS, use the internal endpoint. For more information about the mapping between regions and endpoints supported by OSS, see OSS regions and endpoints.

Permissions

By default, an Alibaba Cloud account has full permissions. RAM users or RAM roles under an Alibaba Cloud account do not have any permissions by default. The Alibaba Cloud account or account administrator must grant operation permissions through RAM Policy or Bucket Policy.

API	Action	Definition
PutObject	`oss:PutObject`	Uploads an object.
	`oss:PutObjectTagging`	When uploading an object, if you specify object tags through x-oss-tagging, this permission is required.
	`kms:GenerateDataKey`	When uploading an object, if the object metadata contains X-Oss-Server-Side-Encryption: KMS, these two permissions are required.
	`kms:Decrypt`

Method definition

put_object(request: PutObjectRequest, **kwargs) → PutObjectResult

Request parameter list

Parameter name	Type	Description
request	PutObjectRequest	Set request parameters, such as setting the object access control method (Acl), forbid overwrite (ForbidOverwrite), custom metadata (Metadata), etc. For details, see PutObjectRequest

Return value list

Type	Description
PutObjectResult	Return value, for details, see PutObjectResult

For the complete definition of the simple upload method, see put_object.

Upload local files

If you upload an object that has the same name as an accessible existing object, the existing object will be overwritten by the uploaded object.

The following table lists the common parameters that you must configure when uploading an object.

Parameter	Description
bucket_name	Bucket name. Bucket names must comply with the following conventions: The name can contain only lowercase letters, digits, and hyphens (-). The name must start and end with a lowercase letter or a digit. The bucket name must be 3 to 63 characters in length.
object_name	Full path of the object. Do not include the bucket name in the full path of the object. Object names must comply with the following conventions: Use UTF-8 encoding. The object name must be 1 to 1,023 characters in length. The name cannot start with a forward slash (/) or a backslash (\).

You can use the put_object_from_file method to directly upload a local file to the target bucket.

import argparse
import alibabacloud_oss_v2 as oss

# Create a command line argument parser
parser = argparse.ArgumentParser(description="put object from file sample")

# Specify the --region parameter, which specifies the region in which the bucket is located. This parameter is required.
parser.add_argument('--region', help='The region in which the bucket is located.', required=True)

# Specify the --bucket parameter, which specifies the name of the bucket. This command line parameter is required.
parser.add_argument('--bucket', help='The name of the bucket.', required=True)

# Specify the --endpoint parameter, which specifies the endpoint that other services can use to access OSS. This parameter is optional.
parser.add_argument('--endpoint', help='The domain names that other services can use to access OSS')

# Specify the --key parameter, which specifies the name of the object. This command line parameter is required.
parser.add_argument('--key', help='The name of the object.', required=True)

# Specify the --file_path parameter, which specifies the path of the local file to upload. This parameter is required.
parser.add_argument('--file_path', help='The path of Upload file.', required=True)

def main():
    # Parse the command line parameters
    args = parser.parse_args()

    # Obtain access credentials from environment variables for authentication
    credentials_provider = oss.credentials.EnvironmentVariableCredentialsProvider()

    # Load the default configuration of the SDK and specify the credential provider
    cfg = oss.config.load_default()
    cfg.credentials_provider = credentials_provider

    # Set the region in the configuration to the one specified in the command line
    cfg.region = args.region

    # If the endpoint parameter is provided, specify the endpoint
    if args.endpoint is not None:
        cfg.endpoint = args.endpoint

    # Use the configurations to create an OSSClient instance
    client = oss.Client(cfg)

    # Execute the request to upload an object directly from a file
    # Specify the bucket name, object name, and local file path
    result = client.put_object_from_file(
        oss.PutObjectRequest(
            bucket=args.bucket,  # Bucket name
            key=args.key         # Object name
        ),
        args.file_path          # Local file path
    )

    # Display the result information, including status code, request ID, content MD5, ETag, CRC-64 value, version ID, and server response time
    print(f'status code: {result.status_code},'
          f' request id: {result.request_id},'
          f' content md5: {result.content_md5},'
          f' etag: {result.etag},'
          f' hash crc64: {result.hash_crc64},'
          f' version id: {result.version_id},'
          f' server time: {result.headers.get("x-oss-server-time")},'
    )

# Script entry point, calls the main function when the file is run directly
if __name__ == "__main__":
    main()

When using the put_object method to upload a local file, you must open the file in 'rb' mode to ensure that the original byte stream is uploaded rather than text content, to avoid cyclic redundancy check failures.

import argparse
import alibabacloud_oss_v2 as oss

# Create a command line argument parser
parser = argparse.ArgumentParser(description="put object from file sample")

# Specify the --region parameter, which specifies the region in which the bucket is located. This parameter is required.
parser.add_argument('--region', help='The region in which the bucket is located.', required=True)

# Specify the --bucket parameter, which specifies the name of the bucket. This command line parameter is required.
parser.add_argument('--bucket', help='The name of the bucket.', required=True)

# Specify the --endpoint parameter, which specifies the endpoint that other services can use to access OSS. This parameter is optional.
parser.add_argument('--endpoint', help='The domain names that other services can use to access OSS')

# Specify the --key parameter, which specifies the name of the object. This command line parameter is required.
parser.add_argument('--key', help='The name of the object.', required=True)

def main():
    # Parse the command line parameters
    args = parser.parse_args()

    # Obtain access credentials from environment variables for authentication
    credentials_provider = oss.credentials.EnvironmentVariableCredentialsProvider()

    # Load the default configuration of the SDK and specify the credential provider
    cfg = oss.config.load_default()
    cfg.credentials_provider = credentials_provider

    # Set the region in the configuration to the one specified in the command line
    cfg.region = args.region

    # If the endpoint parameter is provided, specify the endpoint
    if args.endpoint is not None:
        cfg.endpoint = args.endpoint

    # Use the configurations to create an OSSClient instance
    client = oss.Client(cfg)

    # Execute the request to upload an object directly from a local file
    # Specify the bucket name, object name, and local file path
    with open('your-test-file.md', 'rb') as f:
    result = client.put_object(
        oss.PutObjectRequest(
            bucket=args.bucket,  # Bucket name
            key=args.key,        # Object name
            body=f.read()        # Read file content
        )
    )

    # Display the HTTP status code in the response, the request ID, and the MD5 hash, ETag, CRC-64 value, and version ID of the object to check whether the request is successful
    print(f'status code: {result.status_code},'
          f' request id: {result.request_id},'
          f' content md5: {result.content_md5},'
          f' etag: {result.etag},'
          f' hash crc64: {result.hash_crc64},'
          f' version id: {result.version_id},'
          f' server time: {result.headers.get("x-oss-server-time")},'
    )

# Script entry point, calls the main function when the file is run directly
if __name__ == "__main__":
    main()

Common scenarios

Upload a string

The following sample code provides an example on how to upload a string to a specific bucket:

import argparse
import alibabacloud_oss_v2 as oss

# Create a command line argument parser
parser = argparse.ArgumentParser(description="put object sample")
# Specify the --region parameter, which specifies the region in which the bucket is located. This parameter is required.
parser.add_argument('--region', help='The region in which the bucket is located.', required=True)
# Specify the --bucket parameter, which specifies the name of the bucket. This command line parameter is required.
parser.add_argument('--bucket', help='The name of the bucket.', required=True)
# Specify the --endpoint parameter, which specifies the endpoint that other services can use to access OSS. This parameter is optional.
parser.add_argument('--endpoint', help='The domain names that other services can use to access OSS')
# Specify the --key parameter, which specifies the name of the object. This command line parameter is required.
parser.add_argument('--key', help='The name of the object.', required=True)

def main():
    args = parser.parse_args()  # Parse the command line parameters

    # Obtain access credentials from environment variables for authentication
    credentials_provider = oss.credentials.EnvironmentVariableCredentialsProvider()

    # Load the default configuration of the SDK and specify the credential provider
    cfg = oss.config.load_default()
    cfg.credentials_provider = credentials_provider
    # Set the region in the configuration to the one specified in the command line
    cfg.region = args.region
    # If the endpoint parameter is provided, specify the endpoint
    if args.endpoint is not None:
        cfg.endpoint = args.endpoint

    # Use the configurations to create an OSSClient instance
    client = oss.Client(cfg)

    # Specify the string that you want to upload
    text_string = "Hello, OSS!"
    data = text_string.encode('utf-8')  # Encode the string by using the UTF-8 encoding

    # Execute the request to upload an object, and specify the bucket name, object name, and data content
    result = client.put_object(oss.PutObjectRequest(
        bucket=args.bucket,
        key=args.key,
        body=data,
    ))

    # Display the HTTP status code, request ID, MD5 hash, ETag, CRC-64 value, and object version ID to check whether the request is successful
    print(f'status code: {result.status_code},'
          f' request id: {result.request_id},'
          f' content md5: {result.content_md5},'
          f' etag: {result.etag},'
          f' hash crc64: {result.hash_crc64},'
          f' version id: {result.version_id},'
    )

if __name__ == "__main__":
    main()  # Script entry point, calls the main function when the file is run directly

Upload a byte array

import argparse
import alibabacloud_oss_v2 as oss

# Create a command line argument parser
parser = argparse.ArgumentParser(description="put object sample")
# Specify the --region parameter, which specifies the region in which the bucket is located. This parameter is required.
parser.add_argument('--region', help='The region in which the bucket is located.', required=True)
# Specify the --bucket parameter, which specifies the name of the bucket. This command line parameter is required.
parser.add_argument('--bucket', help='The name of the bucket.', required=True)
# Specify the --endpoint parameter, which specifies the endpoint that other services can use to access OSS. This parameter is optional.
parser.add_argument('--endpoint', help='The domain names that other services can use to access OSS')
# Specify the --key parameter, which specifies the name of the object. This command line parameter is required.
parser.add_argument('--key', help='The name of the object.', required=True)

def main():
    args = parser.parse_args()  # Parse the command line parameters

    # Obtain access credentials from environment variables for authentication
    credentials_provider = oss.credentials.EnvironmentVariableCredentialsProvider()

    # Load the default configuration of the SDK and specify the credential provider
    cfg = oss.config.load_default()
    cfg.credentials_provider = credentials_provider
    # Set the region in the configuration to the one specified in the command line
    cfg.region = args.region
    # If the endpoint parameter is provided, specify the endpoint
    if args.endpoint is not None:
        cfg.endpoint = args.endpoint

    # Use the configurations to create an OSSClient instance
    client = oss.Client(cfg)

    # Specify the data content that you want to upload
    data = b'hello world'

    # Execute the request to upload an object, and specify the bucket name, object name, and data content
    result = client.put_object(oss.PutObjectRequest(
        bucket=args.bucket,
        key=args.key,
        body=data,
    ))

    # Display the HTTP status code, request ID, MD5 hash, ETag, CRC-64 value, and object version ID to check whether the request is successful
    print(f'status code: {result.status_code},'
          f' request id: {result.request_id},'
          f' content md5: {result.content_md5},'
          f' etag: {result.etag},'
          f' hash crc64: {result.hash_crc64},'
          f' version id: {result.version_id},'
    )

if __name__ == "__main__":
    main()  # Script entry point, calls the main function when the file is run directly

Upload a network stream

The following sample code provides an example on how to upload a network stream to a specific bucket:

import argparse
import requests
import alibabacloud_oss_v2 as oss

# Create a command line argument parser
parser = argparse.ArgumentParser(description="put object sample")
# Specify the --region parameter, which specifies the region in which the bucket is located. This parameter is required.
parser.add_argument('--region', help='The region in which the bucket is located.', required=True)
# Specify the --bucket parameter, which specifies the name of the bucket. This command line parameter is required.
parser.add_argument('--bucket', help='The name of the bucket.', required=True)
# Specify the --endpoint parameter, which specifies the endpoint that other services can use to access OSS. This parameter is optional.
parser.add_argument('--endpoint', help='The domain names that other services can use to access OSS')
# Specify the --key parameter, which specifies the name of the object. This command line parameter is required.
parser.add_argument('--key', help='The name of the object.', required=True)

def main():
    args = parser.parse_args()  # Parse the command line parameters

    # Obtain access credentials from environment variables for authentication
    credentials_provider = oss.credentials.EnvironmentVariableCredentialsProvider()

    # Load the default configuration of the SDK and specify the credential provider
    cfg = oss.config.load_default()
    cfg.credentials_provider = credentials_provider
    # Set the region in the configuration to the one specified in the command line
    cfg.region = args.region
    # If the endpoint parameter is provided, specify the endpoint
    if args.endpoint is not None:
        cfg.endpoint = args.endpoint

    # Use the configurations to create an OSSClient instance
    client = oss.Client(cfg)

    # Send an HTTP GET request and get the response content
    response = requests.get('http://www.aliyun.com')

    # Execute the request to upload an object, and specify the bucket name, object name, and data content
    result = client.put_object(oss.PutObjectRequest(
        bucket=args.bucket,
        key=args.key,
        body=response.content,
    ))

    # Display the HTTP status code, request ID, MD5 hash, ETag, CRC-64 value, and object version ID to check whether the request is successful
    print(f'status code: {result.status_code},'
          f' request id: {result.request_id},'
          f' content md5: {result.content_md5},'
          f' etag: {result.etag},'
          f' hash crc64: {result.hash_crc64},'
          f' version id: {result.version_id},'
    )

if __name__ == "__main__":
    main()  # Script entry point, calls the main function when the file is run directly

Upload a file and set callback

If you want to notify the application server after the file is uploaded, you can refer to the following code example.

import base64
import argparse
import alibabacloud_oss_v2 as oss

parser = argparse.ArgumentParser(description="put object sample")

# Add required parameters
parser.add_argument('--region', help='The region in which the bucket is located.', required=True)
parser.add_argument('--bucket', help='The name of the bucket.', required=True)
parser.add_argument('--endpoint', help='The domain names that other services can use to access OSS')
parser.add_argument('--key', help='The name of the object.', required=True)
parser.add_argument('--call_back_url', help='Callback server address.', required=True)


def main():

    args = parser.parse_args()

    # Load access credentials from environment variables
    credentials_provider = oss.credentials.EnvironmentVariableCredentialsProvider()

    # Configure SDK client
    cfg = oss.config.load_default()
    cfg.credentials_provider = credentials_provider
    cfg.region = args.region
    if args.endpoint is not None:
        cfg.endpoint = args.endpoint

    # Create OSS client
    client = oss.Client(cfg)

    # Content to upload (string)
    data = 'hello world'

    # Construct callback parameters: specify callback address and callback request body, using Base64 encoding
    callback=base64.b64encode(str('{\"callbackUrl\":\"' + args.call_back_url + '\",\"callbackBody\":\"bucket=${bucket}&object=${object}&my_var_1=${x:var1}&my_var_2=${x:var2}\"}').encode()).decode(),
    # Construct custom variables (callback-var), using Base64 encoding
    callback_var=base64.b64encode('{\"x:var1\":\"value1\",\"x:var2\":\"value2\"}'.encode()).decode(),

    # Initiate upload request with callback parameters
    result = client.put_object(oss.PutObjectRequest(
        bucket=args.bucket,
        key=args.key,
        body=data,
        callback=callback,
        callback_var=callback_var,
    ))
    # Print return results (including status code, request ID, etc.)
    print(vars(result))


if __name__ == "__main__":
    main()

Upload a file with progress bar

The following sample code shows how to use a progress bar to view the upload progress when uploading a local file.

import argparse
import alibabacloud_oss_v2 as oss

# Create a command line argument parser
parser = argparse.ArgumentParser(description="put object sample")
# Specify the --region parameter, which specifies the region in which the bucket is located. This parameter is required.
parser.add_argument('--region', help='The region in which the bucket is located.', required=True)
# Specify the --bucket parameter, which specifies the name of the bucket. This command line parameter is required.
parser.add_argument('--bucket', help='The name of the bucket.', required=True)
# Specify the --endpoint parameter, which specifies the endpoint that other services can use to access OSS. This parameter is optional.
parser.add_argument('--endpoint', help='The domain names that other services can use to access OSS')
# Specify the --key parameter, which specifies the name of the object. This command line parameter is required.
parser.add_argument('--key', help='The name of the object.', required=True)

def main():
    args = parser.parse_args()  # Parse the command line parameters

    # Obtain access credentials from environment variables for authentication
    credentials_provider = oss.credentials.EnvironmentVariableCredentialsProvider()

    # Load the default configuration of the SDK and specify the credential provider
    cfg = oss.config.load_default()
    cfg.credentials_provider = credentials_provider
    # Set the region in the configuration to the one specified in the command line
    cfg.region = args.region
    # If the endpoint parameter is provided, specify the endpoint
    if args.endpoint is not None:
        cfg.endpoint = args.endpoint

    # Use the configurations to create an OSSClient instance
    client = oss.Client(cfg)

    # Define a dictionary variable progress_state to store upload progress status, with initial value 0
    progress_state = {'saved': 0}
    def _progress_fn(n, written, total):
        # Use dictionary to store accumulated written bytes, avoiding global variables
        progress_state['saved'] += n

        # Calculate current upload percentage by dividing written bytes by total bytes and rounding
        rate = int(100 * (float(written) / float(total)))

        # Print current upload progress, \r means return to line start, achieving real-time refresh in command line
        # end='' means no line break, allowing next print to overwrite current line
        print(f'\rUpload progress: {rate}% ', end='')

    # Execute the request to upload an object, specifying bucket name, object name and data content
    result = client.put_object_from_file(oss.PutObjectRequest(
            bucket=args.bucket,
            key=args.key,
            progress_fn=_progress_fn,
        ),
        "/local/dir/example", # Specify local file path
    )

    # Display the HTTP status code, request ID, MD5 hash, ETag, CRC-64 value, and object version ID to check whether the request is successful
    print(f'status code: {result.status_code},'
          f' request id: {result.request_id},'
          f' content md5: {result.content_md5},'
          f' etag: {result.etag},'
          f' hash crc64: {result.hash_crc64},'
          f' version id: {result.version_id},'
    )

if __name__ == "__main__":
    main()  # Script entry point, calls the main function when the file is run directly

References

For the complete sample code for simple upload, see put_object.py.