:Initialization

Usage notes

• Before you initialize OSS SDK for Python, you must configure access credentials. In this topic, access credentials are obtained from environment variables. For more information, see Configure access credentials.

• If you want to obtain information about OSS regions and endpoints, see Regions and endpoints.

• If you want to create an AccessKey pair for a RAM user, see Create an AccessKey pair.

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

  • The oss2.Service class is used to list buckets.

  • The oss2.Bucket class 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. The oss2.Service class does not support access to buckets by using custom domain names that are mapped to the buckets.

Prerequisites

Default examples

This section provides examples on how to use the V4 signature algorithm and the V1 signature algorithm to initialize OSS SDK for Python.

Note that the following sample code uses the public endpoint of the bucket and the AccessKey pair of the RAM user.

# -*- 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 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 = 'yourEndpoint'
# Specify the region of the endpoint. Example: cn-hangzhou. 
region = 'cn-hangzhou'

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

# -*- 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 environment variables are configured. 
auth = oss2.ProviderAuth(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 = 'yourEndpoint'

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

Configuration examples in common scenarios

This section provides configuration examples in common scenarios. The sample code uses the V4 signature algorithm and the AccessKey pair of the RAM user to initialize OSS SDK for Python by default.

Use an internal endpoint to initialize OSS SDK for Python

If your applications are deployed on an ECS instance and you need to frequently access OSS data in a bucket in the same region as the ECS instance, use an internal endpoint to significantly reduce network latency and bandwidth costs.

The following sample code provides an example on how to use an internal endpoint to configure an OSSClient instance:

# -*- 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 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-internal.aliyuncs.com. 
endpoint = 'yourEndpoint'
# Specify the region of the endpoint. Example: cn-hangzhou. 
region = 'cn-hangzhou'

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

Use a custom domain name to initialize OSS SDK for Python

If you have multiple buckets for different usage, you can specify different subdomains for each bucket to better manage and organize resources.

The following sample code provides an example on how to use a custom domain name to configure an OSSClient instance.

# -*- 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 environment variables are configured. 
auth = oss2.ProviderAuthV4(EnvironmentVariableCredentialsProvider())
// Specify a custom domain name. Example: https://static.example.com. 
endpoint = 'yourEndpoint'
# Specify the region of the endpoint. Example: cn-hangzhou. 
region = 'cn-hangzhou'

# Specify the name of the bucket. Set is_cname to true to enable CNAME.
bucket = oss2.Bucket(auth, endpoint, 'examplebucket', is_cname=True, region=region) 

Configure the connection timeout period

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

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

# We recommend that you do not save access credentials in the project code. Otherwise, access credentials may be leaked. As a result, the security of all resources in your account is compromised. In this example, access credentials are obtained from environment variables. Before you run the sample code, make sure that the 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 region of the endpoint. Example: cn-hangzhou. This parameter is required if you use the V4 signature algorithm.
region = "cn-hangzhou"

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

Disable CRC-64

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

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

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

# We recommend that you do not save access credentials in the project code. Otherwise, access credentials may be leaked. As a result, the security of all resources in your account is compromised. In this example, access credentials are obtained from environment variables. Before you run the sample code, make sure that the 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 region of the endpoint. Example: cn-hangzhou. This parameter is required if you use the V4 signature algorithm.
region = "cn-hangzhou"

# 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,region=region)                   

Specify the connection pool size

The following sample code provides an example on how to specify the connection pool size:

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

# We recommend that you do not save access credentials in the project code. Otherwise, access credentials may be leaked. As a result, the security of all resources in your account is compromised. In this example, access credentials are obtained from environment variables. Before you run the sample code, make sure that the 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 region of the endpoint. Example: cn-hangzhou. This parameter is required if you use the V4 signature algorithm.
region = "cn-hangzhou"

# Specify the connection pool size. Default value: 10. 
session = oss2.Session(pool_size=20)

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

Specify the TLS version

Different Transport Layer Security (TLS) versions have different security and performance features. Select a TLS version based on your scenario.

The following sample code provides an example on how to set the TLS version to 1.2:

# -*- coding: utf-8 -*-
import ssl
import oss2
from requests.adapters import HTTPAdapter
from oss2.credentials import EnvironmentVariableCredentialsProvider

# Obtain access credentials from environment variables. Before you run the sample code, make sure that the environment variables are configured. 
auth = oss2.ProviderAuthV4(EnvironmentVariableCredentialsProvider())

# Configure the SSL adapter. 
class SSLAdapter(HTTPAdapter):
    def init_poolmanager(self, *args, **kwargs):
        # Set the TLS version to 1.2. 
        kwargs["ssl_version"] = ssl.PROTOCOL_TLSv1_2
        return super().init_poolmanager(*args, **kwargs)

# Create a session object and configure the adapter by using the session object. 
session = oss2.Session(adapter=SSLAdapter())

# 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 region of the endpoint. Example: cn-hangzhou. This parameter is required if you use the V4 signature algorithm.
region = "cn-hangzhou"

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

# Upload an object. 
bucket.put_object("example.txt", "hello")

Parameters supported by the oss2.Bucket class

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

FAQ