Object Storage Service:OSS SDK for Python 2.0

Quick integration

Follow these steps to integrate OSS SDK for Python 2.0:

Environment preparation

Python 3.8 or later is required.

Check the Python version by running the python --version command. If Python is not installed or the version is earlier than Python 3.8, download and install Python.

Install the SDK

• Run the following command to install the OSS SDK for Python 2.0 package. Use the latest version to ensure that the code examples in this topic run correctly.

  pip install alibabacloud-oss-v2

• Use the following code to import the OSS SDK for Python 2.0 package.

  import alibabacloud_oss_v2 as oss

Initialize the OSSClient

Initialize the OSSClient with a region and endpoint and then run the test code.

import alibabacloud_oss_v2 as oss

def main():
    """
    Python SDK V2 client initialization configuration:

    1. Signature version: Python SDK V2 uses V4 signature by default for higher security.
    2. Region configuration: When you initialize the client, you must specify an Alibaba Cloud region ID. For example, the region ID for China (Hangzhou) is cn-hangzhou.
    3. Endpoint configuration:
       - Use the Endpoint parameter to customize the endpoint for service requests.
       - If you do not specify an endpoint, a public endpoint is automatically constructed based on the region. For example, if the region is cn-hangzhou, the endpoint is https://oss-cn-hangzhou.aliyuncs.com.
    4. Protocol configuration:
       - The SDK uses HTTPS by default to construct the endpoint.
       - To use HTTP, specify it in the endpoint, for example, http://oss-cn-hangzhou.aliyuncs.com.
    """

    # Load credentials from environment variables for authentication.
    credentials_provider = oss.credentials.EnvironmentVariableCredentialsProvider()

    # Load the default SDK configurations and set the credentials provider.
    cfg = oss.config.load_default()
    cfg.credentials_provider = credentials_provider

    # Method 1: Specify only the region (Recommended)
    # You must specify a region ID. For example, set the region to cn-hangzhou for China (Hangzhou). The SDK automatically constructs an HTTPS endpoint based on the region.
    cfg.region = 'cn-hangzhou' 

    # # Method 2: Specify both the region and the endpoint
    # # You must specify a region ID. For example, set the region to cn-hangzhou for China (Hangzhou).
    # cfg.region = 'cn-hangzhou'
    # # Specify the public endpoint of the region where the bucket is located. For example, for China (Hangzhou), set the endpoint to 'https://oss-cn-hangzhou.aliyuncs.com'.
    # cfg.endpoint = 'https://oss-cn-hangzhou.aliyuncs.com'

    # Create an OSS client with the specified configurations.
    client = oss.Client(cfg)

    # Define the string to upload.
    text_string = "Hello, OSS!"
    data = text_string.encode('utf-8')  # Encode the string into a UTF-8 byte string.

    # Execute the request to upload the object. Specify the bucket name, object key, and data.
    result = client.put_object(oss.PutObjectRequest(
        bucket="Your Bucket Name",
        key="Your Object Key",
        body=data,
    ))

    # Print the status code, request ID, and ETag of the result to check if the request was successful.
    print(f'status code: {result.status_code}\n'
          f'request id: {result.request_id}\n'
          f'etag: {result.etag}'
    )

# When this script is run directly, call the main function.
if __name__ == "__main__":
    main()  # Script entry point. Calls the main function when the file is run directly.

import asyncio
import alibabacloud_oss_v2 as oss
import alibabacloud_oss_v2.aio as oss_aio


async def main():
    """
    Python SDK V2 async client initialization configuration:

    1. Signature version: Python SDK V2 uses V4 signature by default for higher security.

    2. Region configuration: When you initialize the AsyncClient, you must specify an Alibaba Cloud region ID. For example, the region ID for China (Hangzhou) is cn-hangzhou.

    3. Endpoint configuration:
       - Use the Endpoint parameter to customize the endpoint for service requests.
       - If you do not specify an endpoint, a public endpoint is automatically constructed based on the region. For example, if the region is cn-hangzhou, the endpoint is https://oss-cn-hangzhou.aliyuncs.com.

    4. Protocol configuration:
       - The SDK uses HTTPS by default to construct the endpoint.
       - To use HTTP, specify it in the endpoint, for example, http://oss-cn-hangzhou.aliyuncs.com.
    
    5. Asynchronous features:
       - Import the async module: import alibabacloud_oss_v2.aio as oss_aio
       - Create an async client: oss_aio.AsyncClient(cfg)
       - All operations require the await keyword.
       - You must call await client.close() in the finally block to close the connection.
       - Install the aiohttp dependency: pip install aiohttp
    """

    # Load credentials from environment variables for authentication.
    credentials_provider = oss.credentials.EnvironmentVariableCredentialsProvider()

    # Load the default SDK configurations and set the credentials provider.
    cfg = oss.config.load_default()
    cfg.credentials_provider = credentials_provider

    # Method 1: Specify only the region (Recommended)
    # You must specify a region ID. For example, set the region to cn-hangzhou for China (Hangzhou). The SDK automatically constructs an HTTPS endpoint based on the region.
    cfg.region = 'cn-hangzhou'

    # # Method 2: Specify both the region and the endpoint
    # # You must specify a region ID. For example, set the region to cn-hangzhou for China (Hangzhou).
    # cfg.region = 'cn-hangzhou'
    # # Specify the public endpoint of the region where the bucket is located. For example, for China (Hangzhou), set the endpoint to 'https://oss-cn-hangzhou.aliyuncs.com'.
    # cfg.endpoint = 'https://oss-cn-hangzhou.aliyuncs.com'

    # Create an OSS async client with the specified configurations.
    client = oss_aio.AsyncClient(cfg)

    try:
        # Define the string to upload.
        text_string = "Hello, OSS!"
        data = text_string.encode('utf-8')  # Encode the string into a UTF-8 byte string.

        # Execute the async request to upload the object. Specify the bucket name, object key, and data.
        # Note: Use the await keyword to wait for the async operation to complete.
        result = await client.put_object(
            oss.PutObjectRequest(
                bucket="Your Bucket Name",
                key="Your Object Key",
                body=data,
            )
        )

        # Print the status code, request ID, and ETag of the result to check if the request was successful.
        print(f'status code: {result.status_code}\n'
              f'request id: {result.request_id}\n'
              f'etag: {result.etag}'
        )

    except Exception as e:
        print(f'Upload failed: {e}')

    finally:
        # Close the async client connection (Important: to avoid resource leaks).
        await client.close()


# When this script is run directly, call the main function.
if __name__ == "__main__":
    # Use asyncio.run() to run the async main function.
    asyncio.run(main())

After you run the code, the following output indicates a successful upload:

status code: 200
request id: 6875F95738B0ED3030F086A0
etag: "56AAD346F0899BFE8BDD02C06BBE511E"

Client configurations

Use a custom domain name

When you use a default OSS endpoint, you may encounter issues such as being unable to access or preview objects. By accessing OSS through a custom domain name, preview objects directly in a browser and accelerate content delivery using CDN.

import alibabacloud_oss_v2 as oss

def main():
    # Load credentials from environment variables for authentication.
    credentials_provider = oss.credentials.EnvironmentVariableCredentialsProvider()

    # Load the default SDK configurations and set the credentials provider.
    cfg = oss.config.load_default()
    cfg.credentials_provider = credentials_provider

    # Specify the region where the bucket is located. For example, set the region to cn-hangzhou for China (Hangzhou).
    cfg.region = 'cn-hangzhou'

    # Specify your custom domain name. For example, www.example-***.com.
    cfg.endpoint = 'https://www.example-***.com'

    # Note that you must set use_cname to true to use a custom domain name.
    cfg.use_cname = True

    # Create an OSS client with the specified configurations.
    client = oss.Client(cfg)

    # Use the created client to perform subsequent operations...

# When this script is run directly, call the main function.
if __name__ == "__main__":
    main()  # Script entry point. Calls the main function when the file is run directly.

Timeout control

import alibabacloud_oss_v2 as oss
from typing import Dict, Any

def main():
    # Load credentials from environment variables for authentication.
    credentials_provider = oss.credentials.EnvironmentVariableCredentialsProvider()

    # Load the default configurations.
    cfg = oss.config.load_default()

    # Set the timeout period for establishing a connection. The default value is 10 seconds.
    cfg.connect_timeout = 30

    # Set the timeout period for reading and writing data. The default value is 20 seconds.
    cfg.readwrite_timeout = 30

    # Set the credentials provider.
    cfg.credentials_provider = credentials_provider

    # Specify the region where the bucket is located. For example, set the region to cn-hangzhou for China (Hangzhou).
    cfg.region = 'cn-hangzhou'

    # Create an OSS client with the specified configurations.
    client = oss.Client(cfg)

    # Use the created client to perform subsequent operations...

# When this script is run directly, call the main function.
if __name__ == "__main__":
    main()  # Script entry point. Calls the main function when the file is run directly.

Retry policy

import alibabacloud_oss_v2 as oss

def main():
    """
    SDK retry policy configuration:

    Default retry policy:
    If no retry policy is configured, the SDK uses StandardRetryer() as the default client implementation with the following configurations:
    - max_attempts: The maximum number of retries. Default: 3.
    - max_backoff: The maximum backoff time in seconds. Default: 20.
    - base_delay: The base delay time in seconds. Default: 0.2.
    - backoff_delayer: The backoff algorithm. The FullJitter algorithm is used by default.
      Formula: [0.0, 1.0) * min(2^attempts * baseDelay, maxBackoff)
    - error_retryables: The types of retryable errors. For more information, see https://gosspublic.alicdn.com/sdk-doc/alibabacloud-oss-python-sdk-v2/latest/_modules/alibabacloud_oss_v2/retry/error_retryable.html

    When a retryable error occurs, the provided configuration is used to delay and then retry the request.
    The overall latency of the request increases with the number of retries. If the default configuration does not meet your requirements,
    you can configure retry parameters or modify the retry implementation.
    """

    # Load credentials from environment variables for authentication.
    credentials_provider = oss.credentials.EnvironmentVariableCredentialsProvider()

    # Load the default configurations.
    cfg = oss.config.load_default()

    # Retry policy configuration examples:

    # 1. Customize the maximum number of retries (default is 3, set to 5 here).
    cfg.retryer = oss.retry.StandardRetryer(max_attempts=5)

    # 2. Customize the backoff delay time.
    # Adjust the base delay time (base_delay) to 0.5 seconds (default is 0.2) and the maximum backoff time (max_backoff) to 25 seconds (default is 20).
    # cfg.retryer = oss.retry.StandardRetryer(max_backoff=25, base_delay=0.5)

    # 3. Customize the backoff algorithm.
    # Use a fixed-time backoff algorithm instead of the default FullJitter algorithm, with a delay of 2 seconds each time.
    # cfg.retryer = oss.retry.StandardRetryer(backoff_delayer=oss.retry.FixedDelayBackoff(2))

    # 4. Disable the retry policy.
    # To disable all retry attempts, use the retry.NopRetryer implementation.
    # cfg.retryer = oss.retry.NopRetryer()

    # Set the credentials provider.
    cfg.credentials_provider = credentials_provider

    # Specify the region where the bucket is located. For example, set the region to cn-hangzhou for China (Hangzhou).
    cfg.region = 'cn-hangzhou'

    # Create an OSS client with the specified configurations.
    client = oss.Client(cfg)

    # Use the created client to perform subsequent operations...

# When this script is run directly, call the main function.
if __name__ == "__main__":
    main()  # Script entry point. Calls the main function when the file is run directly.

Set the connection pool size

In http_client, specify the max_connections parameter to configure the connection pool size.

#!/usr/bin/env python3
# -*- coding: utf-8 -*-

# OSS SDK for Python 2.0 connection pool configuration example

import alibabacloud_oss_v2 as oss

def main():

    # Load access credentials from environment variables (OSS_ACCESS_KEY_ID and OSS_ACCESS_KEY_SECRET must be set).
    credentials_provider = oss.credentials.EnvironmentVariableCredentialsProvider()

    # Load the default SDK configurations and set the credentials provider.
    config = oss.config.load_default()
    config.credentials_provider = credentials_provider

    # Set the OSS service region.
    config.region = "cn-hangzhou"

    # ============ Custom HTTPClient configuration ============
    # Create a dictionary for HTTP client configuration parameters.
    http_client_config = {}
    
    # Set the connection pool size to 100. The default is 20.
    http_client_config["max_connections"] = 100
    
    # Create an HTTP client with the custom configuration.
    http_client = oss.transport.RequestsHttpClient(**http_client_config)
    
    # Set the custom HTTP client in the configuration object.
    config.http_client = http_client
    # ============================================
    
    # Initialize the OSS client instance.
    client = oss.Client(config)

    # Configure bucket and file information.
    bucket = "example-bucket"             # Bucket name
    key = "dest.jpg"                      # Object path in OSS
    file_path = "dest.jpg"                # Local save path

    # Download the object from OSS to the specified local path.
    client.get_object_to_file(oss.GetObjectRequest(bucket, key), file_path)
    print(f"File download complete: {key} -> {file_path}")
    print(f"Connection pool size set to: {http_client_config['max_connections']}")

if __name__ == "__main__":
    # Program entry point
    try:
        main()
    except Exception as e:
        print(f"An error occurred during execution: {e}")
        raise

HTTP/HTTPS protocol

Use cfg.disable_ssl = True to disable the HTTPS protocol.

import alibabacloud_oss_v2 as oss

def main():
    # Load credentials from environment variables for authentication.
    credentials_provider = oss.credentials.EnvironmentVariableCredentialsProvider()

    # Load the default SDK configurations and set the credentials provider.
    cfg = oss.config.load_default()
    cfg.credentials_provider = credentials_provider

    # Specify the region where the bucket is located. For example, set the region to cn-hangzhou for China (Hangzhou).
    cfg.region = 'cn-hangzhou'

    # Disable HTTPS requests.
    cfg.disable_ssl = True

    # Create an OSS client with the specified configurations.
    client = oss.Client(cfg)

    # Use the created client to perform subsequent operations...

# When this script is run directly, call the main function.
if __name__ == "__main__":
    main()  # Script entry point. Calls the main function when the file is run directly.

Proxy server

Corporate security policies often restrict direct access to the internet. Configure a proxy server to access OSS resources.

import alibabacloud_oss_v2 as oss

def main():
    # Load credentials from environment variables for authentication.
    credentials_provider = oss.credentials.EnvironmentVariableCredentialsProvider()

    # Load the default SDK configurations and set the credentials provider.
    cfg = oss.config.load_default()
    cfg.credentials_provider = credentials_provider

    # Specify the region where the bucket is located. For example, set the region to cn-hangzhou for China (Hangzhou).
    cfg.region = 'cn-hangzhou'

    # Set the user agent.
    cfg.user_agent = 'aliyun-sdk-python'

    # Set the proxy server.
    cfg.proxy_host = 'http://user:passswd@proxy.example-***.com'

    # Create an OSS client with the specified configurations.
    client = oss.Client(cfg)

    # Use the created client to perform subsequent operations...

# When this script is run directly, call the main function.
if __name__ == "__main__":
    main()  # Script entry point. Calls the main function when the file is run directly.

Use an internal same-region endpoint

Using an internal same-region endpoint to access OSS resources in the same region can reduce traffic costs and improve access speed.

import alibabacloud_oss_v2 as oss

def main():
    # Load credentials from environment variables for authentication.
    credentials_provider = oss.credentials.EnvironmentVariableCredentialsProvider()

    # Load the default SDK configurations and set the credentials provider.
    cfg = oss.config.load_default()
    cfg.credentials_provider = credentials_provider

    # Method 1: Specify the region and set use_internal_endpoint to true.
    # Specify the region where the bucket is located. For example, set the region to cn-hangzhou for China (Hangzhou).
    cfg.region = 'cn-hangzhou'
    cfg.use_internal_endpoint = True

    # # Method 2: Directly specify the region and endpoint.
    # # Specify the region where the bucket is located. For example, set the region to cn-hangzhou for China (Hangzhou).
    # cfg.region = 'cn-hangzhou'
    # # Specify the internal endpoint of the region where the bucket is located. For example, for China (Hangzhou), set the endpoint to 'oss-cn-hangzhou-internal.aliyuncs.com'.
    # cfg.endpoint = 'oss-cn-hangzhou-internal.aliyuncs.com'

    # Create an OSS client with the specified configurations.
    client = oss.Client(cfg)

    # Use the created client to perform subsequent operations...

# When this script is run directly, call the main function.
if __name__ == "__main__":
    main()  # Script entry point. Calls the main function when the file is run directly.

Use an acceleration endpoint

import alibabacloud_oss_v2 as oss

def main():
    # Load credentials from environment variables for authentication.
    credentials_provider = oss.credentials.EnvironmentVariableCredentialsProvider()

    # Load the default SDK configurations and set the credentials provider.
    cfg = oss.config.load_default()
    cfg.credentials_provider = credentials_provider

    # Method 1: Specify the region and set use_accelerate_endpoint to true.
    # Specify the region where the bucket is located. For example, set the region to cn-hangzhou for China (Hangzhou).
    cfg.region = 'cn-hangzhou'
    cfg.use_accelerate_endpoint = True

    # # Method 2: Directly specify the region and the acceleration endpoint.
    # # Specify the region where the bucket is located. For example, set the region to cn-hangzhou for China (Hangzhou).
    # cfg.region = 'cn-hangzhou'
    # # Specify the acceleration endpoint of the region where the bucket is located, for example, 'https://oss-accelerate.aliyuncs.com'.
    # cfg.endpoint = 'https://oss-accelerate.aliyuncs.com'

    # Create an OSS client with the specified configurations.
    client = oss.Client(cfg)

    # Use the created client to perform subsequent operations...

# When this script is run directly, call the main function.
if __name__ == "__main__":
    main()  # Script entry point. Calls the main function when the file is run directly.

Use a dedicated domain

import alibabacloud_oss_v2 as oss

def main():
    # Load credentials from environment variables for authentication.
    credentials_provider = oss.credentials.EnvironmentVariableCredentialsProvider()

    # Load the default SDK configurations and set the credentials provider.
    cfg = oss.config.load_default()
    cfg.credentials_provider = credentials_provider

    # Specify the region where the bucket is located. For example, set the region to cn-hangzhou for China (Hangzhou).
    cfg.region = 'cn-hangzhou'

    # Specify your dedicated domain. For example, https://service.corp.example.com.
    cfg.endpoint = 'https://service.corp.example.com'

    # Create an OSS client with the specified configurations.
    client = oss.Client(cfg)

    # Use the created client to perform subsequent operations...

# When this script is run directly, call the main function.
if __name__ == "__main__":
    main()  # Script entry point. Calls the main function when the file is run directly.

Use a custom HTTP client

If the standard configuration parameters do not meet your needs, use cfg.http_client to replace the default HTTP client.

import alibabacloud_oss_v2 as oss
from typing import Dict, Any

def main():
    # Load credentials from environment variables for authentication.
    credentials_provider = oss.credentials.EnvironmentVariableCredentialsProvider()

    # Load the default configurations.
    cfg = oss.config.load_default()

    # Set the parameters for the HTTP client.
    kwargs: Dict[str, Any] = {}

    # Set the session.
    # kwargs["session"] = requests.Session()

    # Set the adapter.
    # kwargs["adapter"] = HTTPAdapter()

    # Specify whether to skip certificate verification. By default, certificates are not skipped.
    # kwargs["insecure_skip_verify"] = False

    # Specify whether to enable HTTP redirection. By default, this feature is disabled.
    # kwargs["enabled_redirect"] = False

    # Set the proxy server.
    # kwargs["proxy_host"] = config.proxy_host

    # Set the block size.
    # kwargs["block_size"] = 16 * 1024

    # Connection timeout. The default value is 10 seconds.
    kwargs["connect_timeout"] = 30

    # Timeout period for reading and writing data. The default value is 20 seconds.
    kwargs["readwrite_timeout"] = 30

    # Maximum connections. The default value is 20.
    kwargs["max_connections"] = 1024

    # Create an HTTP client and pass in the HTTP client parameters.
    cfg.http_client = oss.transport.RequestsHttpClient(**kwargs)

    # Set the credentials provider.
    cfg.credentials_provider = credentials_provider

    # Specify the region where the bucket is located. For example, set the region to cn-hangzhou for China (Hangzhou).
    cfg.region = 'cn-hangzhou'

    # Create an OSS client with the specified configurations.
    client = oss.Client(cfg)

    # Use the created client to perform subsequent operations...


# When this script is run directly, call the main function.
if __name__ == "__main__":
    main()  # Script entry point. Calls the main function when the file is run directly.

Access credential configurations

OSS provides several ways to initialize credentials. Choose one as needed.

Use the AccessKey pair of a RAM user

If your application runs in a secure and stable environment that is not prone to external attacks, requires long-term access to OSS, and cannot have its credentials rotated frequently, initialize the credential provider with the AccessKey pair (AccessKey ID and AccessKey secret) of an Alibaba Cloud account or a RAM user. Note that this method requires you to manually maintain an AccessKey pair, which increases security risks and maintenance complexity.

import alibabacloud_oss_v2 as oss

def main():
    # Create a static credentials provider and explicitly set the AccessKey ID and AccessKey secret. Replace them with your RAM user's AccessKey ID and AccessKey secret.
    credentials_provider = oss.credentials.StaticCredentialsProvider(
        access_key_id="RAM AccessKey ID",
        access_key_secret="RAM AccessKey Secret"
    )

    # Load the default SDK configurations and set the credentials provider.
    cfg = oss.config.load_default()
    cfg.credentials_provider = credentials_provider

    # Specify the region where the bucket is located. For example, set the region to cn-hangzhou for China (Hangzhou).
    cfg.region = 'cn-hangzhou'

    # Create an OSS client with the specified configurations.
    client = oss.Client(cfg)

    # Use the created client to perform subsequent operations...


# When this script is run directly, call the main function.
if __name__ == "__main__":
    main()  # Script entry point. Calls the main function when the file is run directly.

Use an STS token

If your application needs temporary access to OSS, initialize the credential provider with temporary identity credentials (AccessKey ID, AccessKey secret, and Security Token) obtained from Security Token Service (STS). Note that this method requires you to manually maintain an STS token, which increases security risks and maintenance complexity. Additionally, to access OSS temporarily multiple times, you must manually refresh the STS token.

import alibabacloud_oss_v2 as oss

def main():
    # Specify the temporary AccessKey ID and AccessKey secret obtained, not the AccessKey ID and AccessKey secret of your Alibaba Cloud account.
    # Note that the AccessKey ID obtained from STS starts with "STS", as shown below.
    sts_access_key_id = 'STS.****************'
    sts_access_key_secret = 'yourAccessKeySecret'
    # Specify the obtained STS security token.
    sts_security_token = 'yourSecurityToken'

    # Create a static credentials provider and explicitly set the temporary AccessKey ID, AccessKey secret, and STS security token.
    credentials_provider = oss.credentials.StaticCredentialsProvider(
        access_key_id=sts_access_key_id,
        access_key_secret=sts_access_key_secret,
        security_token=sts_security_token,
    )

    # Load the default SDK configurations and set the credentials provider.
    cfg = oss.config.load_default()
    cfg.credentials_provider = credentials_provider

    # Specify the region where the bucket is located. For example, set the region to cn-hangzhou for China (Hangzhou).
    cfg.region = 'cn-hangzhou'

    # Create an OSS client with the specified configurations.
    client = oss.Client(cfg)

    # Use the created client to perform subsequent operations...


# When this script is run directly, call the main function.
if __name__ == "__main__":
    main()  # Script entry point. Calls the main function when the file is run directly.

Use a RAM role ARN

If your application needs authorized access to OSS, such as cross-account access, initialize the credential provider with a RAM role ARN. The underlying implementation of this method is an STS token. By specifying the Alibaba Cloud Resource Name (ARN) of a RAM role, the credentials tool obtains an STS token from STS and calls the AssumeRole operation to apply for a new STS token before the current session expires. You can also assign a value to the policy parameter to restrict the RAM role to a smaller set of permissions.

1. Add the alibabacloud_credentials dependency.

   pip install alibabacloud_credentials

2. Configure the AccessKey pair and RAM role ARN as access credentials.

   # -*- coding: utf-8 -*-
   import os
   from alibabacloud_credentials.client import Client
   from alibabacloud_credentials.models import Config
   import alibabacloud_oss_v2 as oss
   
   def main():
       config = Config(
           # Get the AccessKey pair (AccessKey ID and AccessKey secret) of the RAM user from environment variables.
           access_key_id=os.getenv('ALIBABA_CLOUD_ACCESS_KEY_ID'),
           access_key_secret=os.getenv('ALIBABA_CLOUD_ACCESS_KEY_SECRET'),
           type='ram_role_arn',
           # The ARN of the RAM role to assume. Example: acs:ram::123456789012****:role/adminrole. Set RoleArn through the ALIBABA_CLOUD_ROLE_ARN environment variable.
           role_arn='<RoleArn>',
           # The role session name. Set RoleSessionName through the ALIBABA_CLOUD_ROLE_SESSION_NAME environment variable.
           role_session_name='<RoleSessionName>',
           # A smaller permission policy. This is optional. Example: {"Statement": [{"Action": ["*"],"Effect": "Allow","Resource": ["*"]}],"Version":"1"}
           policy='<Policy>',
           # The validity period of the role session in seconds. The default is 3600 seconds (1 hour). This is optional.
           role_session_expiration=3600
       )
   
       cred_client = Client(config)
   
       def get_credentials_wrapper():
           cred = cred_client.get_credential()
           return oss.credentials.Credentials(access_key_id=cred.access_key_id, access_key_secret=cred.access_key_secret, security_token=cred.security_token)
   
       # Create a credentials provider for dynamic loading of credentials.
       credentials_provider = oss.credentials.CredentialsProviderFunc(func=get_credentials_wrapper)
   
       # Load the default OSS SDK configurations.
       cfg = oss.config.load_default()
       cfg.credentials_provider = credentials_provider
   
       # Specify the region where the bucket is located. For example, set the region to cn-hangzhou for China (Hangzhou).
       cfg.region = 'cn-hangzhou'
   
       # Create an OSS client instance.
       client = oss.Client(cfg)
   
       # Use the client for subsequent operations...
   
   
   # When this script is run directly, call the main function.
   if __name__ == "__main__":
       main()  # Script entry point. Calls the main function when the file is run directly.

Use an ECS instance RAM role

If your application runs on an ECS instance, an ECI instance, or a worker node of Container Service for Kubernetes, initialize the credential provider with an ECS instance RAM role. The underlying implementation of this method is an STS token. An ECS instance RAM role lets you associate a role with an ECS instance, an ECI instance, or a worker node of Container Service for Kubernetes to automatically refresh the STS token within the instance. This method eliminates the risk of manually maintaining an AccessKey pair or an STS token because you do not need to provide one. For more information about how to obtain an ECS instance RAM role, see CreateRole - Create a RAM role.

1. Add the alibabacloud_credentials dependency.

   pip install alibabacloud_credentials

2. Configure the ECS instance RAM role as the access credential.

   from alibabacloud_credentials.client import Client
   from alibabacloud_credentials.models import Config
   import alibabacloud_oss_v2 as oss
   
   def main():
       config = Config(
           type='ecs_ram_role',      # Access credential type. Fixed as ecs_ram_role.
           role_name='EcsRoleExample'    # The name of the RAM role granted to the ECS instance. This is an optional parameter. If not set, it will be automatically retrieved. Set it to reduce requests.
       )
   
       cred_client = Client(config)
   
       def get_credentials_wrapper():
           cred = cred_client.get_credential()
           return oss.credentials.Credentials(access_key_id=cred.access_key_id, access_key_secret=cred.access_key_secret, security_token=cred.security_token)
   
       # Create a credentials provider for dynamic loading of credentials.
       credentials_provider = oss.credentials.CredentialsProviderFunc(func=get_credentials_wrapper)
   
       # Load the default OSS SDK configurations.
       cfg = oss.config.load_default()
       cfg.credentials_provider = credentials_provider
   
       # Specify the region where the bucket is located. For example, set the region to cn-hangzhou for China (Hangzhou).
       cfg.region = 'cn-hangzhou'
   
       # Create an OSS client instance.
       client = oss.Client(cfg)
   
       # Use the client for subsequent operations...
   
   
   # When this script is run directly, call the main function.
   if __name__ == "__main__":
       main()  # Script entry point. Calls the main function when the file is run directly.

Use an OIDC role ARN

After configuring a RAM role for worker nodes in Container Service for Kubernetes, applications in pods on those nodes can obtain the associated STS token via the Metadata Server, similar to ECS instances. However, for untrusted applications such as customer-submitted code, you may want to restrict access to the worker node's instance RAM role STS token to protect your resources. To allow these untrusted applications to securely obtain necessary STS tokens while minimizing permissions, use the RAM Roles for Service Accounts (RRSA) feature. This approach uses STS tokens, with the Alibaba Cloud container cluster creating and mounting a service account OIDC token file for each application pod. Relevant configuration information is injected into environment variables, and the credentials tool retrieves this data to invoke the AssumeRoleWithOIDC operation of STS, exchanging the OIDC token for an STS token for the bound role. This method removes the need to manage AccessKey pairs or STS tokens manually. For more information, see Isolate pod permissions based on RRSA.

Use a custom access credential

If the preceding credential configuration methods do not meet your requirements, customize the way you obtain credentials. The SDK supports multiple implementation methods.

1. Use the credentials.CredentialsProviderFunc interface

   import argparse
   import alibabacloud_oss_v2 as oss
   import os
   
   def main():
   
       def get_credentials_wrapper():
           # Return long-term credentials.
           return oss.credentials.Credentials(access_key_id='access_key_id', access_key_secret='access_key_security')
           # Return temporary STS credentials.
           # return oss.credentials.Credentials(access_key_id='access_key_id', access_key_secret='access_key_security', security_token='security_token')
   
       credentials_provider = oss.credentials.CredentialsProviderFunc(func=get_credentials_wrapper)
   
      # Load the default SDK configurations and set the credentials provider.
       cfg = oss.config.load_default()
       cfg.credentials_provider = credentials_provider
       
       # Specify the region where the bucket is located. For example, set the region to cn-hangzhou for China (Hangzhou).
       cfg.region = "cn-hangzhou"
   
       # Create an OSS client with the specified configurations.
       client = oss.Client(cfg)
   
       # Use the client for subsequent operations...
   
   if __name__ == "__main__":
       main()  # Script entry point. Calls the main function when the file is run directly.

2. Implement the credentials.CredentialsProvider interface

   # -*- coding: utf-8 -*-
   import alibabacloud_oss_v2 as oss
   
   class CredentialProviderWrapper(oss.credentials.CredentialsProvider):
       def get_credentials(self):
           # TODO
           # Customize the method for obtaining access credentials.
   
           # Return long-term credentials: access_key_id, access_key_secret.
           return oss.credentials.Credentials('<access_key_id>', '<access_key_secret>')
   
           # Return temporary STS credentials: access_key_id, access_key_secret, token.
           # For temporary credentials, you need to refresh them based on their expiration time.
           # return oss.credentials.Credentials('<access_key_id>', '<access_key_secret>', '<token>');
   
   
   def main():
       # Create a credentials provider for dynamic loading of credentials.
       credentials_provider = CredentialProviderWrapper()
   
       # Load the default OSS SDK configurations.
       cfg = oss.config.load_default()
       cfg.credentials_provider = credentials_provider
   
       # Specify the region where the bucket is located. For example, set the region to cn-hangzhou for China (Hangzhou).
       cfg.region = 'cn-hangzhou'
   
       client = oss.Client(cfg)
   
       # Use the client for subsequent operations...
   
   
   if __name__ == "__main__":
       main()  # Script entry point. Calls the main function when the file is run directly.

Anonymous access

If you only need to access public-read OSS resources, use anonymous access, which does not require any credentials.

import alibabacloud_oss_v2 as oss

# Create an anonymous credentials provider.
credentials_provider = oss.credentials.AnonymousCredentialsProvider()

# Configure the client.
cfg = oss.config.load_default()
cfg.credentials_provider = credentials_provider
# Specify the region where the bucket is located. For example, set the region to cn-hangzhou for China (Hangzhou).
cfg.region = 'cn-hangzhou'

# Create an OSS client.
client = oss.Client(cfg)

Troubleshoot errors

When you use OSS SDK for Python 2.0 to access OSS and an error occurs, OSS returns information such as an HTTP code, a message, a request ID, and an error code (EC). The EC indicates the specific cause of the error. Use the EC to troubleshoot the error.

Code examples

OSS SDK for Python 2.0 provides a rich set of code examples for your reference or direct use.