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

OSS SDK for Python allows you to use oss2.Service and oss2.Bucket to perform most operations.

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

To initialize the oss2.Service and oss2.Bucket, you must specify the endpoint of the region in which the bucket you want to access is located. The oss2.Service class cannot be initialized by using custom domain names. 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

  • Use the default domain name of a bucket to initialize the class

    The following code provides an example on how to use the default domain name of a bucket to initialize the oss2.Bucket class:

    # -*- coding: utf-8 -*-
    import oss2
    
    # Security risks may arise if you use the AccessKey pair of an Alibaba Cloud account to access OSS because the account has permissions on all API operations. We recommend that you use a Resource Access Management (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')
    
    # Set yourEndpoint to the endpoint of the region in which the bucket is located. For example, if your bucket is located in the China (Hangzhou) region, set yourEndpoint to https://oss-cn-hangzhou.aliyuncs.com. 
    endpoint = 'yourEndpoint'
    
    # Specify the bucket name. 
    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 oss2.Bucket class:

    # -*- coding: utf-8 -*-
    import oss2
    
    # Security risks may arise if you use the AccessKey pair of an Alibaba Cloud account to access OSS because the account has permissions on all API operations. 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 bucket name, and set is_cname to true to enable CNAME. If CNAME is enabled, custom domain names can be mapped to the bucket. 
    bucket = oss2.Bucket(auth, cname, 'examplebucket', is_cname=True)                    
  • Use Security Token Service (STS) to initialize the class

    The following code provides an example on how to use STS to initialize the oss2.Bucket class.

    # -*- coding: utf-8 -*-
    import oss2
    
    # Initialize the StsAuth instance based on the authentication information in the temporary access credential. 
    auth = oss2.StsAuth('yourAccessKeyId', 'yourAccessKeySecret', 'yourSecretToken')
        
    # Set yourEndpoint to the endpoint of the region in which the bucket is located. For example, if your bucket is located in the China (Hangzhou) region, set yourEndpoint to https://oss-cn-hangzhou.aliyuncs.com. 
    endpoint = 'yourEndpoint'
    # Specify the name of the bucket. Example: examplebucket.     
    bucket_name = 'examplebucket'
        
    # Initialize a bucket based on the StsAuth instance. 
    bucket = oss2.Bucket(auth, endpoint, bucket_name)
  • Use anonymous access to initialize the class
    Notice 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 oss2.Service- and oss2.Bucket-related operations.

    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
    
    # Set yourEndpoint to the endpoint of the region in which the bucket is located. For example, if your bucket is located in the China (Hangzhou) region, set yourEndpoint 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)

Configure parameters when you initialize 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 Specify the connection timeout period. Default value: None, which indicates that the connection timeout period is unlimited. Unit: seconds. 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.
Notice 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)
Common examples for the configurations of these parameters:
  • Configure the connection timeout period

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

    # -*- coding: utf-8 -*-
    import oss2
    
    # Security risks may arise if you use the AccessKey pair of an Alibaba Cloud account to access OSS because the account has permissions on all API operations. 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')
    
    # Set yourEndpoint to the endpoint of the region in which the bucket is located. For example, if your bucket is located in the China (Hangzhou) region, set yourEndpoint to https://oss-cn-hangzhou.aliyuncs.com. 
    endpoint = 'yourEndpoint'
    
    # Specify the bucket name and set the connection timeout period to 30 seconds. 
    bucket = oss2.Bucket(auth, endpoint, 'examplebucket', connect_timeout=30)                    
  • Disable CRC

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

    Warning We recommend that you do not disable CRC. If you disable CRC, data integrity may be affected during object upload and download.

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

    # -*- coding: utf-8 -*-
    import oss2
    
    # Security risks may arise if you use the AccessKey pair of an Alibaba Cloud account to access OSS because the account has permissions on all API operations. 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')
    
    # Set yourEndpoint to the endpoint of the region in which the bucket is located. For example, if your bucket is located in the China (Hangzhou) region, set yourEndpoint to https://oss-cn-hangzhou.aliyuncs.com. 
    endpoint = 'yourEndpoint'
    
    # Specify the bucket name, and set enable_crc to False to disable CRC. 
    bucket = oss2.Bucket(auth, endpoint, 'examplebucket', enable_crc=False)