Get started with OSS SDK for Python - Object Storage Service

This topic describes how to use Object Storage Service (OSS) SDK for Python to perform routine operations, such as creating buckets, uploading objects, and downloading objects.

Video tutorial

The following video shows how to use OSS SDK for Python.

Create a bucket

A bucket is a global namespace in OSS. A bucket is a container that is used to store objects.

Note

For more information about endpoints, see Regions, endpoints and open ports. For more information about bucket naming rules, see the Bucket section of the Terms topic.

The following sample code provides an example on how to create a bucket:

# -*- 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)

# Set the access control list (ACL) of the bucket to private. 
bucket.create_bucket(oss2.models.BUCKET_ACL_PRIVATE)

For more information about how to create a bucket, see Create buckets.

Upload an object

The following sample code provides an example on how to upload an object to OSS by using streaming 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)

# Upload the object to OSS. 
# Replace yourObjectName with the full path to the object. Include the extension in the full path. Do not include the bucket name in the full path. Example: abc/efg/123.jpg. 
# Replace yourLocalFileName with the full path to the local file. Include the file name and extension in the full path. Example: /users/local/myfile.txt. 
bucket.put_object_from_file('yourObjectName', 'yourLocalFile')

Download an object

The following sample code provides an example on how to download a specific object to your computer:

# -*- 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)

# Download the object to your computer. 
# Replace yourObjectName with the full path to the object. Include the extension in the full path. Do not include the bucket name in the full path. Example: abc/efg/123.jpg. 
# Replace yourLocalFileName with the full path to the local file. Include the file name and extension in the full path. Example: /users/local/myfile.txt. 
bucket.get_object_to_file('yourObjectName', 'yourLocalFile')

List objects

The following sample code provides an example on how to list 10 objects in a specific bucket:

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

# 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)

# oss2.ObjectIteratorr is used to traverse objects. 
for b in islice(oss2.ObjectIterator(bucket), 10):
    print(b.key)

Delete an object

The following sample code provides an example on how to delete an object:

# -*- 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)

# Replace yourObjectName with the full path to the object. Include the extension in the full path. Do not include the bucket name in the full path. Example: abc/efg/123.jpg. 
bucket.delete_object('yourObjectName')

For more information about how to delete objects, see Delete objects.