Initialization - Object Storage Service - Alibaba Cloud Documentation Center

This topic describes how to initialize Object Storage Service (OSS) SDK for Python.

Background information

Most operations of OSS SDK for Python are performed based on the oss2.Service and oss2.Bucket classes.

oss2.Service is used to list buckets.
oss2.Bucket is used to upload, download, and delete objects, and configure buckets.

When you initialize the oss2.Service and oss2.Bucket classes, you must specify the endpoint of the region in which the bucket is located. oss2.Service does not support access to buckets by using custom domain names that are mapped to the buckets. For more information about endpoints, see Regions and endpoints and Map custom domain names.

Initialize the oss2.Service class

For more information, see List buckets.

Initialize the oss2.Bucket class

You can use one of the following methods to initialize the oss2.Bucket class:

Use the endpoint of the region in which the bucket is located to initialize the class

The following code provides an example on how to use the endpoint of the region in which the bucket is located to initialize the class:

# -*- coding: utf-8 -*-
import oss2

# The AccessKey pair of an Alibaba Cloud account has permissions on all API operations. Using these credentials to perform operations in OSS is a high-risk operation. We recommend that you use a RAM user to call API operations or perform routine O&M. To create a RAM user, log on to the RAM console. 
auth = oss2.Auth('yourAccessKeyId', 'yourAccessKeySecret')

# 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 = 'yourEndpoint'

# Specify the name of the bucket. 
bucket = oss2.Bucket(auth, endpoint, 'examplebucket')

Use a custom domain name that is mapped to a bucket to initialize the class

The following code provides an example on how to use a custom domain name that is mapped to a bucket to initialize the class:

# -*- coding: utf-8 -*-
import oss2

# The AccessKey pair of an Alibaba Cloud account has permissions on all API operations. Using these credentials to perform operations in OSS is a high-risk operation. We recommend that you use a RAM user to call API operations or perform routine O&M. To create a RAM user, log on to the RAM console. 
auth = oss2.Auth('yourAccessKeyId', 'yourAccessKeySecret')

# Specify the custom domain name that is mapped to the bucket. Example: example.com. 
cname = 'http://example.com'

# Specify the name of the bucket, and set is_cname to true to enable CNAME. CNAME is used to map a custom domain name to a bucket. 
bucket = oss2.Bucket(auth, cname, 'examplebucket', is_cname=True)

Use STS to initialize the class

Note For more information about how to configure Security Token Service (STS), see Use temporary credentials provided by STS to access OSS. You can call the AssumeRole operation or use STS SDKs for various programming languages to obtain temporary access credentials. The temporary access credentials consist of an AccessKey pair and a security token. The AccessKey pair consists of an AccessKey ID and an AccessKey secret. The unit of the validity period of temporary access credentials is seconds. The minimum validity period of temporary access credentials is 900 seconds. The maximum validity period of temporary access credentials is the maximum session duration specified for the current role. For more information, see Specify the maximum session duration for a RAM role.

The following code provides an example on how to use STS to initialize the class:

# -*- coding: utf-8 -*-
import oss2

# Initialize the StsAuth instance based on the authentication information in the temporary access credentials. 
auth = oss2.StsAuth('yourAccessKeyId', 'yourAccessKeySecret', 'yourSecretToken')
    
# 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 = 'yourEndpoint'
# Specify the name of the bucket. Example: examplebucket.     
bucket_name = 'examplebucket'
    
# Initialize the class based on the StsAuth instance. 
bucket = oss2.Bucket(auth, endpoint, bucket_name)

Use anonymous access to initialize the class

Important Anonymous users can read only buckets whose access control list (ACL) is public read and read and write only buckets whose ACL is public read/write. Anonymous users cannot perform operations that are related to the oss2.Service and oss2.Bucket classes.

The following code provides an example on how to initialize the class for the examplebucket bucket whose ACL is public read/write:

# -*- coding: utf-8 -*-
import oss2

# 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 = 'yourEndpoint'
# Specify the name of the bucket. Example: examplebucket.     
bucket_name = 'examplebucket'

# Use anonymous access to initialize the class. 
bucket = oss2.Bucket(oss2.AnonymousAuth(), endpoint, bucket_name)

Parameters that are supported by the oss2.Bucket class

The following table describes the parameters that you can configure when you initialize the oss2.Bucket class.


Parameter	Example	Description	Method
is_cname	True	Specify whether the endpoint is a custom domain name. Default value: False. Valid values: True: The endpoint that you specify is a custom domain name. False: The endpoint that you specify is not a custom domain name.	oss2.Bucket(auth, cname, 'examplebucket', is_cname=True)
session	mytestsession	The name of the session, which indicates that a new session is started. If you set this parameter to the name of an existing session, the session is reused.	oss2.Bucket(auth, endpoint, 'examplebucket', session=oss2.Session())
connect_timeout	30	The timeout period of a connection. Default value: 60. Unit: seconds. For more information about the parameter, see Quickstart.	oss2.Bucket(auth, endpoint, 'examplebucket', connect_timeout=30)
app_name	mytool	The name of the app that uses the SDK. By default, the name of the app is empty. If the parameter is not empty, specify the corresponding value in the User-Agent field. Important The string must comply with HTTP standards because the string is transmitted as a value of HTTP headers.	oss2.Bucket(auth, endpoint, 'examplebucket', app_name='mytool')
enable_crc	False	Specify whether to enable cyclic redundancy check (CRC). Default value: True. True: indicates that CRC is enabled. False: indicates that CRC is disabled.	oss2.Bucket(auth, endpoint, 'examplebucket', enable_crc=False)

Sample oss2.Bucket class configurations

The following section provides examples on how to configure the oss2.Bucket class:

Configure the connection timeout period

The following code provides an example on how to configure the connection timeout period:

# -*- coding: utf-8 -*-
import oss2

# The AccessKey pair of an Alibaba Cloud account has permissions on all API operations. Using these credentials to perform operations in OSS is a high-risk operation. We recommend that you use a RAM user to call API operations or perform routine O&M. To create a RAM user, log on to the RAM console. 
auth = oss2.Auth('yourAccessKeyId', 'yourAccessKeySecret')

# 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 = 'yourEndpoint'

# Specify the name of the bucket, and set the connection timeout period to 30 seconds. 
bucket = oss2.Bucket(auth, endpoint, 'examplebucket', connect_timeout=30)

Disable CRC-64

By default, CRC-64 is enabled to ensure data integrity when you upload or download objects.

Warning We recommend that you do not disable CRC-64. If you disable CRC-64, data integrity may be affected when you upload or download objects.

The following code provides an example on how to disable CRC-64:

# -*- coding: utf-8 -*-
import oss2

# The AccessKey pair of an Alibaba Cloud account has permissions on all API operations. Using these credentials to perform operations in OSS is a high-risk operation. We recommend that you use a RAM user to call API operations or perform routine O&M. To create a RAM user, log on to the RAM console. 
auth = oss2.Auth('yourAccessKeyId', 'yourAccessKeySecret')

# 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 = 'yourEndpoint'

# Specify the name of the bucket, and set enable_crc to False to disable CRC-64. 
bucket = oss2.Bucket(auth, endpoint, 'examplebucket', enable_crc=False)