Object Storage Service:OSS Python SDK V1

Prepare the environment

yum install python-devel

yum install python-devel

yum install python-devel

apt-get install python-dev

apt-get install python-dev

Install the SDK

Install the SDK using one of the following methods. Use the latest version to ensure compatibility with the code examples.

Configure access credentials

Configure access credentials using the AccessKey pair of a RAM user.

1. In the RAM console, create a RAM user with a Permanent AccessKey Pair. Save the AccessKey pair and grant the AliyunOSSFullAccess permission to the user.

2. Use the AccessKey pair of the RAM user to configure environment variables.

   Linux

   1. Run the following commands in the command-line interface 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

   2. Run the following command to apply the changes.

      source ~/.bashrc

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

      echo $OSS_ACCESS_KEY_ID
      echo $OSS_ACCESS_KEY_SECRET

   macOS

   1. Run the following command in the terminal to view the default shell type.

      echo $SHELL

   2. 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. Run the following commands in CMD.

      setx OSS_ACCESS_KEY_ID "YOUR_ACCESS_KEY_ID"
      setx OSS_ACCESS_KEY_SECRET "YOUR_ACCESS_KEY_SECRET"

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

      echo %OSS_ACCESS_KEY_ID%
      echo %OSS_ACCESS_KEY_SECRET%

   PowerShell

   1. Run the following commands in PowerShell.

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

   2. 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)

Initialize the client

Most operations with the OSS Python SDK V1 use the oss2.Service and oss2.Bucket classes.

• The oss2.Service class lists buckets. It does not support access through custom domain names.

• The oss2.Bucket class uploads, downloads, and deletes files, and configures various bucket settings.

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

# Sample code for initializing a client with OSS Python SDK V1

import oss2
from oss2.credentials import EnvironmentVariableCredentialsProvider

def main():

    # Load access credentials from environment variables. You must set the OSS_ACCESS_KEY_ID and OSS_ACCESS_KEY_SECRET environment variables.
    auth = oss2.ProviderAuthV4(EnvironmentVariableCredentialsProvider())
    # Set the OSS service region.
    region = "<region-id>"
    # Set the endpoint.
    endpoint = "<endpoint>"
    # Set the bucket name.
    bucket_name = "example-bucket"

    # Initialize an OSS Bucket instance.
    bucket = oss2.Bucket(auth, endpoint, bucket_name, region=region)
    
    # List files in the bucket.
    print("=== List files in the bucket ===")
    try:
        # Use the list_objects method to list files.
        result = bucket.list_objects()
        
        # Iterate through the file list and print only the file names.
        for obj in result.object_list:
            print(obj.key)
        
        # Print statistics.
        print(f"\nTotal files listed: {len(result.object_list)}")
        if result.is_truncated:
            print("Note: The result is truncated. More files are available.")
            
    except oss2.exceptions.OssError as e:
        print(f"OSS error: {e}")
        raise
    except Exception as e:
        print(f"An error occurred: {e}")
        raise

if __name__ == "__main__":
    # Entry point of the program.
    try:
        main()
    except Exception as e:
        print(f"An error occurred during execution: {e}")
        raise

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

# Sample code for initializing a Service instance with OSS Python SDK V1

import oss2
from oss2.credentials import EnvironmentVariableCredentialsProvider

def main():

    # Load access credentials from environment variables. You must set the OSS_ACCESS_KEY_ID and OSS_ACCESS_KEY_SECRET environment variables.
    auth = oss2.ProviderAuthV4(EnvironmentVariableCredentialsProvider())
    # Set the OSS service region.
    region = "<region-id>"
    # Set the endpoint.
    endpoint = "<endpoint>"

    # Initialize an OSS Service instance.
    service = oss2.Service(auth, endpoint, region=region)
    
    # List all buckets.
    print("=== List all buckets ===")
    try:
        # Use BucketIterator to list buckets.
        buckets = [b.name for b in oss2.BucketIterator(service)]
        
        # Iterate through the bucket list and print only the bucket names.
        for bucket in buckets:
            print(bucket)
        
        # Print statistics.
        print(f"\nTotal buckets listed: {len(buckets)}")
            
    except oss2.exceptions.OssError as e:
        print(f"OSS error: {e}")
        raise
    except Exception as e:
        print(f"An error occurred: {e}")
        raise

if __name__ == "__main__":
    # Entry point of the program.
    try:
        main()
    except Exception as e:
        print(f"An error occurred during execution: {e}")
        raise

Use an internal domain name

To access OSS over an internal network, use the internal domain name as the endpoint.

Replace the <region-id> placeholder in the code with an actual region, such as ap-southeast-1.

endpoint = "oss-<region-id>-internal.aliyuncs.com"

# Initialize an OSS bucket instance.
bucket = oss2.Bucket(auth, endpoint, bucket_name, region=region)

Use a custom domain name

To use a custom domain name, set the endpoint to your domain and enable is_cname=True.

Map your custom domain name to your bucket before using it. Access OSS by Using Custom Domain Names.

# Set the custom domain name.
endpoint = "http://example.com"

# Initialize an OSS bucket instance.
bucket = oss2.Bucket(auth, endpoint, bucket_name, is_cname=True, region=region)

Timeout control

Set the connect_timeout parameter (in seconds) when initializing the client. Default: 60 seconds.

# Initialize an OSS bucket instance.
bucket = oss2.Bucket(auth, endpoint, bucket_name, connect_timeout=30, region=region)

Connection pool size

Adjust the connection pool size with the pool_size parameter of the session object.

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

# Initialize an OSS bucket instance.
bucket = oss2.Bucket(auth, endpoint, bucket_name, session=session, region=region)

TLS version

To specify a TLS version, create a session by using a custom SSLAdapter.

Python SDK 2.18.1 and later versions allow you to specify the TLS version.

import ssl
from requests.adapters import HTTPAdapter

# Define a custom adapter to specify the TLS version.
class SSLAdapter(HTTPAdapter):
    def init_poolmanager(self, *args, **http_client_config):
        # Specify TLS 1.2.
        http_client_config["ssl_version"] = ssl.PROTOCOL_TLSv1_2
        return super(SSLAdapter, self).init_poolmanager(*args, **http_client_config)
        
# Create a session by using SSLAdapter.
session = oss2.Session(adapter=SSLAdapter())

# Initialize an OSS bucket instance.
bucket = oss2.Bucket(auth, endpoint, bucket_name, session=session, region=region)

Disable CRC check

To disable the CRC data integrity check, set the enable_crc=False parameter.

# Initialize an OSS bucket instance.
bucket = oss2.Bucket(auth, endpoint, bucket_name, enable_crc=False, region=region)

Signature version

The following example initializes a client with the V1 signature. For V4 signature initialization, see Initialize a Client.

Before you run the sample code, replace placeholders such as <endpoint> with your actual region and endpoint, such as https://oss-ap-southeast-1.aliyuncs.com.

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

# OSS Python SDK V1 client initialization sample code
import oss2
from oss2.credentials import EnvironmentVariableCredentialsProvider

def main():

    # Load access credentials from environment variables. You must set the OSS_ACCESS_KEY_ID and OSS_ACCESS_KEY_SECRET environment variables.
    auth = oss2.ProviderAuth(EnvironmentVariableCredentialsProvider())

    # Set the endpoint.
    endpoint = "<endpoint>"
    # Set the bucket name.
    bucket_name = "example-bucket"

    # Initialize an OSS bucket instance.
    bucket = oss2.Bucket(auth, endpoint, bucket_name)
    
    # List files in the bucket.
    print("=== List files in the bucket ===")
    try:
        # List files by using the list_objects() method.
        result = bucket.list_objects()
        
        # Iterate through the object list and print each object's key.
        for obj in result.object_list:
            print(obj.key)
        
        # Print statistics.
        print(f"\nTotal files listed: {len(result.object_list)}")
        if result.is_truncated:
            print("Note: The result is truncated. More files are available.")
            
    except oss2.exceptions.OssError as e:
        print(f"OSS error: {e}")
        raise
    except Exception as e:
        print(f"An error occurred: {e}")
        raise

if __name__ == "__main__":
    # Program entry point.
    try:
        main()
    except Exception as e:
        print(f"An error occurred while running the program: {e}")
        raise

Custom application name

Set the app_name parameter to add a custom identifier to the User-Agent header. Default: empty string.

The application name is transmitted as an HTTP header value and must comply with HTTP standards.

# Initialize an OSS bucket instance.
bucket = oss2.Bucket(auth, endpoint, bucket_name, app_name="client_test", region=region)

RAM user AK

Suitable for secure, stable environments that need long-term OSS access without frequent credential rotation. Initialize the credential provider with the AccessKey (AK) of a RAM user. This requires manual AK maintenance, which introduces security risks.

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

# OSS Python SDK V1: Sample code for client initialization

import oss2
from oss2.credentials import EnvironmentVariableCredentialsProvider

def main():

    # Specify the AccessKey ID and AccessKey Secret of a RAM user.
    access_key_id = 'yourAccessKeyID'
    access_key_secret = 'yourAccessKeySecret'
    # Configure access credentials using the Access Key (AK) of the RAM user.
    auth = oss2.AuthV4(access_key_id, access_key_secret)
    # Set the OSS service region.
    region = "<region-id>"
    # Set the endpoint.
    endpoint = "<endpoint>"
    # Set the bucket name.
    bucket_name = "example-bucket-hz"

    # Initialize an OSS Bucket instance.
    bucket = oss2.Bucket(auth, endpoint, bucket_name, region=region)
    
    # List objects in the bucket.
    print("=== List objects in the bucket ===")
    try:
        # Use the list_objects method to list objects.
        result = bucket.list_objects()
        
        # Iterate through the object list and print only the object keys.
        for obj in result.object_list:
            print(obj.key)
        
        # Print statistics.
        print(f"\nTotal objects listed: {len(result.object_list)}")
        if result.is_truncated:
            print("Note: The result is truncated. More objects are not listed.")
            
    except oss2.exceptions.OssError as e:
        print(f"OSS error: {e}")
        raise
    except Exception as e:
        print(f"An error occurred: {e}")
        raise

if __name__ == "__main__":
    # Entry point of the program.
    try:
        main()
    except Exception as e:
        print(f"An error occurred during execution: {e}")
        raise

STS temporary credentials

Suitable for applications that need temporary OSS access. Initialize the credential provider with temporary credentials (AccessKey ID, AccessKey Secret, and security token) from STS. You must refresh the STS token manually before it expires.

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

# Specify the temporary AccessKey ID and AccessKey Secret obtained from STS, not the AccessKey ID and AccessKey Secret of your Alibaba Cloud account.
# Note that the Access Key ID obtained from STS starts with "STS."
sts_access_key_id = 'STS.****************'
sts_access_key_secret = 'yourAccessKeySecret'
# Specify the security token obtained from STS.
security_token = 'yourSecurityToken'

# yourEndpoint specifies the endpoint for the region where the bucket is located.
endpoint = '<endpoint>'

# yourBucketName specifies the bucket name.
bucket_name = 'yourBucketName'

# Specify the region where the bucket is located.
region = '<region-id>'

# Initialize the StsAuth instance. Note that setting auth_version to "v4" enables OSS V4 signatures.
auth = oss2.StsAuth(sts_access_key_id,
                    sts_access_key_secret,
                    security_token,
                    auth_version="v4")

# Initialize the bucket using the StsAuth instance. Note that the region parameter is required when using V4 signatures;
# otherwise, an error occurs.
bucket = oss2.Bucket(auth, endpoint, bucket_name, region=region)

# Use the bucket object for subsequent operations...

RAM role ARN

Suitable for cross-account access. Initialize the credential provider with a RAM role ARN. The credentials tool automatically refreshes the STS token by calling AssumeRole before it expires. You can set the policy parameter to further restrict permissions.

1. Add the credentials dependency.

   pip install alibabacloud_credentials

2. Configure the Access Key (AK) and RAM role ARN as access credentials.

   Before you run the sample code, replace placeholders such as <region-id> with the actual region and endpoint. For example, replace <region-id> with ap-southeast-1.

   # -*- coding: utf-8 -*-
   import oss2
   from alibabacloud_credentials.client import Client
   from alibabacloud_credentials.models import Config
   from oss2 import CredentialsProvider
   from oss2.credentials import Credentials
   import os
   
   class CredentialProviderWrapper(CredentialsProvider):
       def __init__(self, client):
           self.client = client
   
       def get_credentials(self):
           credential = self.client.get_credential()
           access_key_id = credential.access_key_id
           access_key_secret = credential.access_key_secret
           security_token = credential.security_token
           return Credentials(access_key_id, access_key_secret, security_token)
   
   config = Config(
       # Obtain the Access Key (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. You can set the RoleArn using the ALIBABA_CLOUD_ROLE_ARN environment variable.
       role_arn='<RoleArn>',
       # The role session name. You can set the RoleSessionName using the ALIBABA_CLOUD_ROLE_SESSION_NAME environment variable.
       role_session_name='<RoleSessionName>',
       # Optional. A more restrictive permission policy. Example: {"Statement": [{"Action": ["*"],"Effect": "Allow","Resource": ["*"]}],"Version":"1"}
       policy='<Policy>',
       # Optional. The validity period of the role session.
       role_session_expiration=3600
   )
   
   cred = Client(config)
   
   credentials_provider = CredentialProviderWrapper(cred)
   
   # Note that ProviderAuthV4 indicates the use of V4 signatures.
   auth = oss2.ProviderAuthV4(credentials_provider)
   
   # yourEndpoint specifies the endpoint for the region where the bucket is located.
   endpoint = '<endpoint>'
   
   # yourBucketName specifies the bucket name.
   bucket_name = 'yourBucketName'
   
   # Specify the region where the bucket is located.
   region = '<region-id>'
   
   # Initialize the bucket by using the Auth instance. Note that the region parameter is required when using V4 signatures;
   # otherwise, an error occurs.
   bucket = oss2.Bucket(auth, endpoint, bucket_name, region=region)
   
   # Use the bucket object for subsequent operations...

ECS instance RAM role

Suitable for applications on ECS instances, ECI instances, or Container Service for Kubernetes (ACK) worker nodes. An ECS instance RAM role enables automatic STS token refresh on ECS instances, ECI instances, or Container Service for Kubernetes (ACK) worker nodes without providing an AK or STS token. To obtain a role, see Create a RAM role. To attach it to an instance, see Instance RAM role.

1. Add the credentials dependency.

   pip install alibabacloud_credentials

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

   Before you run the sample code, replace placeholders such as <region-id> with the actual region and endpoint. For example, replace <region-id> with ap-southeast-1.

   # -*- coding: utf-8 -*-
   import oss2
   from alibabacloud_credentials.client import Client
   from alibabacloud_credentials.models import Config
   from oss2 import CredentialsProvider
   from oss2.credentials import Credentials
   
   class CredentialProviderWrapper(CredentialsProvider):
       def __init__(self, client):
           self.client = client
   
       def get_credentials(self):
           credential = self.client.get_credential()
           access_key_id = credential.access_key_id
           access_key_secret = credential.access_key_secret
           security_token = credential.security_token
           return Credentials(access_key_id, access_key_secret, security_token)
   
   config = Config(
       type='ecs_ram_role',      # Credential type. Fixed value: ecs_ram_role.
       role_name='<RoleName>'    # The name of the RAM role attached to the ECS instance. Optional. If not set, it is retrieved automatically. We strongly recommend setting this parameter to reduce requests.
   )
   
   cred = Client(config)
   
   credentials_provider = CredentialProviderWrapper(cred)
   
   # Note that ProviderAuthV4 indicates the use of V4 signatures.
   auth = oss2.ProviderAuthV4(credentials_provider)
   
   # yourEndpoint specifies the endpoint for the region where the bucket is located.
   endpoint = '<endpoint>'
   
   # yourBucketName specifies the bucket name.
   bucket_name = 'yourBucketName'
   
   # Specify the region where the bucket is located.
   region = '<region-id>'
   
   # Initialize the bucket by using the Auth instance. Note that the region parameter is required when using V4 signatures;
   # otherwise, an error occurs.
   bucket = oss2.Bucket(auth, endpoint, bucket_name, region=region)
   
   # Use the bucket object for subsequent operations...

OIDC role ARN

When untrusted applications run on ACK worker nodes, use RRSA to prevent them from obtaining the node's instance RAM role STS token. The cluster mounts a service account OIDC token file per pod and injects the configuration into environment variables. The credentials tool exchanges the OIDC token for an STS token via AssumeRoleWithOIDC, without requiring an AK or STS token. Configure RAM permissions for a ServiceAccount to implement pod permission isolation by using RRSA.

1. Add the credentials dependency.

   pip install alibabacloud_credentials

2. Configure the OIDC role as the access credential.

   Before you run the sample code, replace placeholders such as <region-id> with the actual region and endpoint. For example, replace <region-id> with ap-southeast-1.

   # -*- coding: utf-8 -*-
   import oss2
   from alibabacloud_credentials.client import Client
   from alibabacloud_credentials.models import Config
   from oss2 import CredentialsProvider
   from oss2.credentials import Credentials
   import os
   
   class CredentialProviderWrapper(CredentialsProvider):
       def __init__(self, client):
           self.client = client
   
       def get_credentials(self):
           credential = self.client.get_credential()
           access_key_id = credential.access_key_id
           access_key_secret = credential.access_key_secret
           security_token = credential.security_token
           return Credentials(access_key_id, access_key_secret, security_token)
   
   config = Config(
       # Credential type. Fixed value: oidc_role_arn.
       type='oidc_role_arn',
       # The ARN of the RAM role. You can set the RoleArn using the ALIBABA_CLOUD_ROLE_ARN environment variable.
       role_arn=os.environ.get('<RoleArn>'),
       # The ARN of the OIDC provider. You can set the OidcProviderArn using the ALIBABA_CLOUD_OIDC_PROVIDER_ARN environment variable.
       oidc_provider_arn=os.environ.get('<OidcProviderArn>'),
       # The OIDC token file path. You can set the OidcTokenFilePath using the ALIBABA_CLOUD_OIDC_TOKEN_FILE environment variable.
       oidc_token_file_path=os.environ.get('<OidcTokenFilePath>'),
       # The role session name. You can set the RoleSessionName using the ALIBABA_CLOUD_ROLE_SESSION_NAME environment variable.
       role_session_name='<RoleSessionName>',
       # Optional. A more restrictive permission policy. Example: {"Statement": [{"Action": ["*"],"Effect": "Allow","Resource": ["*"]}],"Version":"1"}
       policy='<Policy>',
       # The validity period of the session.
       role_session_expiration=3600
   )
   
   cred = Client(config)
   
   credentials_provider = CredentialProviderWrapper(cred)
   
   # Note that ProviderAuthV4 indicates the use of V4 signatures.
   auth = oss2.ProviderAuthV4(credentials_provider)
   
   # yourEndpoint specifies the endpoint for the region where the bucket is located.
   endpoint = '<endpoint>'
   
   # yourBucketName specifies the bucket name.
   bucket_name = 'yourBucketName'
   
   # Specify the region where the bucket is located.
   region = '<region-id>'
   
   # Initialize the bucket by using the Auth instance. Note that the region parameter is required when using V4 signatures;
   # otherwise, an error occurs.
   bucket = oss2.Bucket(auth, endpoint, bucket_name, region=region)
   
   # Use the bucket object for subsequent operations...

Function Compute context

Suitable for functions running in FC. FC assumes a service role to obtain an STS token (valid for 36 hours) and passes it through the context Credentials parameter. Since the maximum function execution time is 24 hours, the token does not expire during execution, so no refresh is needed. To grant FC permissions to access OSS, see Use a function role to grant Function Compute permissions to access other cloud services.

Initialize the credential provider with credentials from the FC context.

Before you run the sample code, replace placeholders such as <region-id> with the actual region and endpoint. For example, replace <region-id> with ap-southeast-1.

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

def handler(event, context):

    class CredentialProviderWrapper(CredentialsProvider):
        def get_credentials(self):
            creds = context.credentials
            return Credentials(creds.access_key_id, creds.access_key_secret, creds.security_token)

    credentials_provider = CredentialProviderWrapper()
    # Note that ProviderAuthV4 indicates the use of V4 signatures.
    auth = oss2.ProviderAuthV4(credentials_provider)

    # yourEndpoint specifies the endpoint for the region where the bucket is located.
    endpoint = '<endpoint>'

    # yourBucketName specifies the bucket name.
    bucket_name = 'yourBucketName'

    # Specify the region where the bucket is located.
    region = '<region-id>'

    # Initialize the bucket by using the Auth instance. Note that the region parameter is required when using V4 signatures;
    # otherwise, an error occurs.
    bucket = oss2.Bucket(auth, endpoint, bucket_name, region=region)

    # Use the bucket object for subsequent operations...

    return 'success'

Credentials URI

Suitable for applications that obtain credentials from an external system. The credentials tool retrieves an STS token from the provided URI and handles automatic refresh.

1. To ensure the credentials tool can correctly parse and use the STS token, the URI response must adhere to the following protocol:

   • Response status code: 200

   • Response body structure:

     {
         "Code": "Success",
         "AccessKeySecret": "AccessKeySecret",
         "AccessKeyId": "AccessKeyId",
         "Expiration": "2021-09-26T03:46:38Z",
         "SecurityToken": "SecurityToken"
     }

2. Add the credentials dependency.

   pip install alibabacloud_credentials

3. Configure the credentials URI as the access credential.

   Before you run the sample code, replace placeholders such as <region-id> with the actual region and endpoint. For example, replace <region-id> with ap-southeast-1.

   # -*- coding: utf-8 -*-
   import oss2
   from alibabacloud_credentials.client import Client
   from alibabacloud_credentials.models import Config
   from oss2 import CredentialsProvider
   from oss2.credentials import Credentials
   
   class CredentialProviderWrapper(CredentialsProvider):
       def __init__(self, client):
           self.client = client
   
       def get_credentials(self):
           credential = self.client.get_credential()
           access_key_id = credential.access_key_id
           access_key_secret = credential.access_key_secret
           security_token = credential.security_token
           return Credentials(access_key_id, access_key_secret, security_token)
   
   config = Config(
       type='credentials_uri',
       # The URI for the credentials, in the format http://local_or_remote_uri/. You can set the CredentialsUri using the ALIBABA_CLOUD_CREDENTIALS_URI environment variable.
       credentials_uri='<CredentialsUri>',
   )
   
   cred = Client(config)
   
   credentials_provider = CredentialProviderWrapper(cred)
   
   # Note that ProviderAuthV4 indicates the use of V4 signatures.
   auth = oss2.ProviderAuthV4(credentials_provider)
   
   # yourEndpoint specifies the endpoint for the region where the bucket is located.
   endpoint = '<endpoint>'
   
   # yourBucketName specifies the bucket name.
   bucket_name = 'yourBucketName'
   
   # Specify the region where the bucket is located.
   region = '<region-id>'
   
   # Initialize the bucket by using the Auth instance. Note that the region parameter is required when using V4 signatures;
   # otherwise, an error occurs.
   bucket = oss2.Bucket(auth, endpoint, bucket_name, region=region)
   
   # Use the bucket object for subsequent operations...

Auto-rotated AK

Suitable for environments where the AK is at risk of compromise. Initialize the credential provider with a ClientKey from KMS, which automatically rotates the managed RAM user AK. KMS also supports immediate rotation if an AK is compromised. To obtain a ClientKey, see Create an Application Access Point.

1. Add the Secrets Manager client dependency.

   pip install aliyun-secret-manager-client

2. Create a configuration file named secretsmanager.properties.

   # The type of access credential. Fixed value: client_key
   credentials_type=client_key
   
   # The decryption password for the ClientKey. You can read it from an environment variable or a file. Set only one.
   client_key_password_from_env_variable=<your client key private key password environment variable name>
   client_key_password_from_file_path=<your client key private key password file path>
   
   # The path to the private key file of the ClientKey.
   client_key_private_key_path=<your client key private key file path>
   
   # The region of the associated KMS.
   cache_client_region_id=[{"regionId":"<regionId>"}]

3. Use the configuration file to provide credential information.

   Before you run the sample code, replace placeholders such as <region-id> with the actual region and endpoint. For example, replace <region-id> with ap-southeast-1.

   # -*- coding: utf-8 -*-
   import json
   import oss2
   from oss2 import CredentialsProvider
   from oss2.credentials import Credentials
   from alibaba_cloud_secretsmanager_client.secret_manager_cache_client_builder import SecretManagerCacheClientBuilder
   
   class CredentialProviderWrapper(CredentialsProvider):
       def get_credentials(self):
           secret_cache_client = SecretManagerCacheClientBuilder.new_client()
           secret_info = secret_cache_client.get_secret_info("<secretName>")
           secret_value_json = json.loads(secret_info.secret_value)
           return Credentials(secret_value_json["AccessKeyId"], secret_value_json["AccessKeySecret"])
   
   credentials_provider = CredentialProviderWrapper()
   
   # Note that ProviderAuthV4 indicates the use of V4 signatures.
   auth = oss2.ProviderAuthV4(credentials_provider)
   
   # yourEndpoint specifies the endpoint for the region where the bucket is located.
   endpoint = '<endpoint>'
   
   # yourBucketName specifies the bucket name.
   bucket_name = 'yourBucketName'
   
   # Specify the region where the bucket is located.
   region = '<region-id>'
   
   # Initialize the bucket by using the Auth instance. Note that the region parameter is required when using V4 signatures;
   # otherwise, an error occurs.
   bucket = oss2.Bucket(auth, endpoint, bucket_name, region=region)
   
   # Use the bucket object for subsequent operations...

Custom credential provider

If none of the above credential configuration methods meet your requirements, you can define a custom credential provider by implementing the CredentialProvider interface. If your implementation uses an STS token, you must also handle credential refresh.

Before you run the sample code, replace placeholders such as <region-id> with the actual region and endpoint. For example, replace <region-id> with ap-southeast-1.

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

class CredentialProviderWrapper(CredentialsProvider):
    def get_credentials(self):
        # TODO
        # Implement your custom method for obtaining access credentials.

        # Return long-term credentials: access_key_id, access_key_secret
        return Credentials('<access_key_id>', '<access_key_secrect>')

        # Return temporary credentials: access_key_id, access_key_secret, token
        # For temporary credentials, you need to refresh them based on their expiration time.
        # return Credentials('<access_key_id>', '<access_key_secrect>', '<token>');

credentials_provider = CredentialProviderWrapper()

# Note that ProviderAuthV4 indicates the use of V4 signatures.
auth = oss2.ProviderAuthV4(credentials_provider)

# yourEndpoint specifies the endpoint for the region where the bucket is located.
endpoint = '<endpoint>'

# yourBucketName specifies the bucket name.
bucket_name = 'yourBucketName'

# Specify the region where the bucket is located.
region = '<region-id>'

# Initialize the bucket by using the Auth instance. Note that the region parameter is required when using V4 signatures;
# otherwise, an error occurs.
bucket = oss2.Bucket(auth, endpoint, bucket_name, region=region)

# Use the bucket object for subsequent operations...

Error: No module named _crcfunext?

Uploads and downloads using the OSS Python SDK V1 are slower than with other tools, such as ossutil or other SDKs.

• Cause:

  The _crcfunext.so library fails to generate during crcmod compilation because the system is missing the required Python.h file. Learn more about crcmod in the crcmod introduction.

• Solution:

  Verify that the C extension mode for crcmod is installed correctly.

  1. Run the following command to enter the Python environment.

     python

  2. Run the following command to import the _crcfunext C extension module from the crcmod module.

     import crcmod._crcfunext

     The following error indicates that the C extension mode for the crcmod library failed to install.

     Traceback (most recent call last):
     File "<stdin>", line 1, in <module>
     ImportError: No module named _crcfunext                                 

  3. Choose a solution based on your operating system.

     Windows

     1. Download crcmod-1.7.win32-py2.7.msi or another version of the .msi file.

        Note

        The 32-bit version of crcmod is compatible with both 32-bit and 64-bit Windows systems.

     2. Install the .msi file and during the installation process, specify the installation path for crcmod to the Lib\site-packages folder in your local Python installation directory. For example, D:\python\Lib\site-packages\.

     3. After the installation is complete, run the crcmod verification steps again.

     Linux

     If this issue occurs on a Linux system, perform the following steps:

     1. Run the following command to uninstall crcmod.

        pip uninstall crcmod

     2. Install python-devel. See Prepare the environment.

     3. Run the following command to reinstall crcmod.

        pip install crcmod

        If the installation fails again, uninstall crcmod and run the following command to view detailed error information.

        pip install crcmod -v

Error: No module named 'Crypto'?

• Cause:

  The Crypto module does not exist in the system, or the crypto module (with a lowercase initial letter) exists.

• Solution:

  Check for the Crypto module in your local Python installation path, for example, D:\python3.9\Lib\site-packages.

  • If the Crypto module does not exist, run the following command.

    python -m pip install --upgrade setuptools

  • If a module named crypto (with a lowercase c) exists, rename it to Crypto and then restart your program.

Error: "not an internal or external command"?

On Windows, if you receive 'is not recognized as an internal or external command', add the Python and pip installation paths (typically the Scripts folder in the Python directory) to the Path environment variable. Restart your computer for the changes to take effect.

OSS Python SDK V1 installation failure

If installation fails, uninstall and retry.

pip uninstall oss2            

Upgrade the OSS Python SDK V1

Run the following command to upgrade the SDK.

 pip install --upgrade oss2

Troubleshoot AccessDenied errors

An AccessDenied error indicates insufficient permissions. Troubleshoot as follows:

1. Ensure that you are using the correct AccessKey ID and AccessKey Secret.

2. Verify that the RAM user has the required permissions for the bucket or object operations.

3. Check the bucket policy: An error message containing "Access denied by bucket policy" indicates the request was blocked by a bucket policy.

Improve transfer speed for intra-region access

For faster transfers, access OSS from an Alibaba Cloud product (such as ECS) in the same region as your bucket, using an internal endpoint.

View AccessKeys and manage AccessKey Secrets

1. To view a RAM user's AccessKey: Log on to the RAM console and select the specific user to view their AccessKey information.

2. A RAM user's AccessKey Secret is shown only at creation time. If you lose it, create a new AccessKey in the RAM console. Create an AccessKey.