Object Storage Service:Configure an OSSClient instance

Configure environment variables

1. Create an AccessKey pair for a Resource Access Management (RAM) user that has full OSS access permissions.

   Create an AccessKey pair by using ROS

   You can quickly create an AccessKey pair for a RAM user that has full OSS access permissions by using a Resource Orchestration Service (ROS) script. To do so, go to the wizard for template-based stack creation, select I confirm that Alibaba Cloud ROS may create RAM resources in the Security Confirmation section, and click Create.

   

   After the AccessKey pair is created, copy the AccessKey pair on the Outputs tab.

   

2. Configure environment variables for the AccessKey pair.

   Linux

   1. Run the following commands on the CLI to add the configurations of the environment variables 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 check whether the environment variables have taken effect:

         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. Configure environment variables based on the default shell type.

      Zsh

      1. Run the following commands to add the configurations of the environment variables 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 check whether the environment variables take effect:

         echo $OSS_ACCESS_KEY_ID
         echo $OSS_ACCESS_KEY_SECRET

      Bash

      1. Run the following commands to add the configurations of the environment variables 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 check whether the environment variables take effect:

         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 check whether the environment variables take effect:

      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 check whether the environment variable takes effect:

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

3. After configuring the environment variables as described above, please restart or refresh your compilation and runtime environment, namely IDEs, command-line interfaces, other desktop applications, and background services, to ensure that the latest system environment variables are successfully loaded. 

Use an internal endpoint to configure a Client instance

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

The following sample code uses an internal endpoint to configure a Client instance:

import alibabacloud_oss_v2 as oss

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

    # Load the default configuration of the SDK and specify the credential 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 in which the bucket is located. For example, if your bucket is located in the China (Hangzhou) region, set the region to cn-hangzhou.
    cfg = oss.config.load_default()
    cfg.region = 'cn-hangzhou'
    cfg.use_internal_endpoint = True

    # # Method 2: Specify the internal endpoint and region.
    # # Specify the region in which the bucket is located. For example, if your bucket is located in the China (Hangzhou) region, set the region to cn-hangzhou.
    # cfg.region = 'cn-hangzhou'
    # # Specify the internal endpoint of the region in which the bucket is located. For example, if the bucket is located in the China (Hangzhou) region, set the endpoint to https://oss-cn-hangzhou-internal.aliyuncs.com.
    # cfg.endpoint = 'https://oss-cn-hangzhou-internal.aliyuncs.com'

    # Use the configuration to create a Client instance.
    client = oss.Client(cfg)

    # Use the Client instance to perform subsequent operations.

# Call the main function when the script is directly run.
if __name__ == "__main__":
    main()  # The entry point of the script. When the script is directly run, the main function is called.

Use a custom domain name to configure a Client instance

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

The following sample code uses a custom domain name to configure a Client instance:

import alibabacloud_oss_v2 as oss

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

    # Load the default configuration of the SDK and specify the credential provider.
    cfg = oss.config.load_default()
    cfg.credentials_provider = credentials_provider

    # Specify the region in which the bucket is located. For example, if your bucket is located in the China (Hangzhou) region, set the region to cn-hangzhou.
    cfg.region = 'cn-hangzhou'

    # Specify a custom domain name. Example: www.example-***.com.
    cfg.endpoint = 'https://www.example-***.com'

    # To enable CNAME, set this parameter to True. Otherwise, you cannot use a custom domain name.
    cfg.use_cname = True

    # Use the configuration to create a Client instance.
    client = oss.Client(cfg)

    # Use the Client instance to perform subsequent operations.

# Call the main function when the script is directly run.
if __name__ == "__main__":
    main()  # The entry point of the script. When the script is directly run, the main function is called.

Use an acceleration endpoint to configure a Client instance

The following sample code uses an acceleration endpoint to configure a Client instance:

import alibabacloud_oss_v2 as oss

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

    # Load the default configuration of the SDK and specify the credential 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 in which the bucket is located. For example, if your bucket is located in the China (Hangzhou) region, set the region to cn-hangzhou.
    cfg.region = 'cn-hangzhou'
    cfg.use_accelerate_endpoint = True

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

    # Use the configuration to create a Client instance.
    client = oss.Client(cfg)

    # Use the Client instance to perform subsequent operations.

# Call the main function when the script is directly run.
if __name__ == "__main__":
    main()  # The entry point of the script. When the script is directly run, the main function is called.

Use a private domain to configure a Client instance

The following sample code uses a private domain to configure a Client instance:

import alibabacloud_oss_v2 as oss

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

    # Load the default configuration of the SDK and specify the credential provider.
    cfg = oss.config.load_default()
    cfg.credentials_provider = credentials_provider

    # Specify the region in which the bucket is located. For example, if your bucket is located in the China (Hangzhou) region, set the region to cn-hangzhou.
    cfg.region = 'cn-hangzhou'

    # Specify the private domain. Example: https://service.corp.example.com.
    cfg.endpoint = 'https://service.corp.example.com'

    # Use the configuration to create a Client instance.
    client = oss.Client(cfg)

    # Use the Client instance to perform subsequent operations.

# Call the main function when the script is directly run.
if __name__ == "__main__":
    main()  # The entry point of the script. When the script is directly run, the main function is called.

Configuration example for Alibaba Finance Cloud

The following sample code uses an endpoint of Alibaba Finance Cloud to configure a Client instance:

import alibabacloud_oss_v2 as oss

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

    # Load the default configuration of the SDK and specify the credential provider.
    cfg = oss.config.load_default()
    cfg.credentials_provider = credentials_provider

    # Specify the region and endpoint.
    # Specify the region in which the bucket is located. For example, if the bucket is located in the China East 1 Finance region, set the region to cn-hangzhou-finance.
    cfg.region = 'cn-hangzhou-finance'
    # Specify the internal endpoint of the region in which the bucket is located. For example, if the bucket is located in the China East 1 Finance region, set the endpoint to https://oss-cn-hzjbp-a-internal.aliyuncs.com.
    # To use the HTTP protocol, set the endpoint to http://oss-cn-hzjbp-a-internal.aliyuncs.com.
    cfg.endpoint = 'https://oss-cn-hzjbp-a-internal.aliyuncs.com'

    # Use the configuration to create a Client instance.
    client = oss.Client(cfg)

    # Use the Client instance to perform subsequent operations.

# Call the main function when the script is directly run.
if __name__ == "__main__":
    main()  # The entry point of the script. When the script is directly run, the main function is called.

Configuration example for Alibaba Gov Cloud

The following sample code uses an endpoint of Alibaba Gov Cloud to configure a Client instance:

import alibabacloud_oss_v2 as oss

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

    # Load the default configuration of the SDK and specify the credential provider.
    cfg = oss.config.load_default()
    cfg.credentials_provider = credentials_provider

    # Specify the region and endpoint.
    # Specify the region in which the bucket is located. For example, if the bucket is located in the China North 2 Ali Gov 1 region, set the region to cn-north-2-gov-1.
    cfg.region = 'cn-north-2-gov-1'
    # Specify the internal endpoint of the region in which the bucket is located. For example, if the bucket is located in the China North 2 Ali Gov 1 region, set the endpoint to https://oss-cn-north-2-gov-1-internal.aliyuncs.com.
    # To use the HTTP protocol, set the endpoint to http://oss-cn-north-2-gov-1-internal.aliyuncs.com.
    cfg.endpoint = 'https://oss-cn-north-2-gov-1-internal.aliyuncs.com'

    # Use the configuration to create a Client instance.
    client = oss.Client(cfg)

    # Use the Client instance to perform subsequent operations.

# Call the main function when the script is directly run.
if __name__ == "__main__":
    main()  # The entry point of the script. When the script is directly run, the main function is called.

Configure the timeout period

The following sample code configures a connection timeout period for a Client instance:

import alibabacloud_oss_v2 as oss
from typing import Dict, Any

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

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

    # Specify the timeout period for establishing a connection. Default value: 10. Unit: seconds.
    cfg.connect_timeout = 30

    # Specify the timeout period for the application to read and write data. Default value: 20. Unit: seconds.
    cfg.readwrite_timeout = 30

    # Specify the credential provider.
    cfg.credentials_provider = credentials_provider

    # Specify the region in which the bucket is located. For example, if your bucket is located in the China (Hangzhou) region, set the region to cn-hangzhou.
    cfg.region = 'cn-hangzhou'

    # Use the configuration to create a Client instance.
    client = oss.Client(cfg)

    # Use the Client instance to perform subsequent operations.

# Call the main function when the script is directly run.
if __name__ == "__main__":
    main()  # The entry point of the script. When the script is directly run, the main function is called.

Configure retry policies

OSS SDK for Python provides retry policies to handle request failures caused by network fluctuations or temporary service exceptions. Refer to the following sample code to add optional parameters to configure the number of retries when initializing a Client instance.

import alibabacloud_oss_v2 as oss

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

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

    # Set the maximum number of retries. Default value: 3.
    cfg.retryer = oss.retry.StandardRetryer(max_attempts=5)

    # Set the backoff delay time, adjust the base delay time base_delay to 500 milliseconds, and the maximum backoff time max_backoff to 25 seconds.
    # cfg.retryer = oss.retry.StandardRetryer(max_backoff=25, base_delay=0.5)

    # Set the backoff algorithm, use a fixed time backoff algorithm with a 2-second delay each time.
    # cfg.retryer = oss.retry.StandardRetryer(backoff_delayer=oss.retry.FixedDelayBackoff(2))

    # To disable all retry attempts, you can use the retry.NopRetryer implementation.
    # cfg.retryer = oss.retry.NopRetryer()


    # Specify the credential provider.
    cfg.credentials_provider = credentials_provider

    # Specify the region in which the bucket is located. For example, if your bucket is located in the China (Hangzhou) region, set the region to cn-hangzhou.
    cfg.region = 'cn-hangzhou'

    # Use the configuration to create a Client instance.
    client = oss.Client(cfg)

    # Use the Client instance to perform subsequent operations.

# Call the main function when the script is directly run.
if __name__ == "__main__":
    main()  # The entry point of the script. When the script is directly run, the main function is called.

Use an HTTP client to configure a Client instance

If common parameters cannot meet the requirements of your business scenario, you can use cfg.http_client to replace the default HTTP client.

import alibabacloud_oss_v2 as oss
from typing import Dict, Any

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

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

    # Specify the parameters of 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, certificate verification is not skipped.
    # kwargs["insecure_skip_verify"] = False

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

    # Specify a proxy server.
    # kwargs["proxy_host"] = config.proxy_host

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

    # The timeout period to establish a connection. Default value: 10 seconds.
    kwargs["connect_timeout"] = 30

    # The timeout period for the application to read and write data. Default value: 20. Unit: seconds.
    kwargs["readwrite_timeout"] = 30

    # The maximum number of connections. Default value: 20.
    kwargs["max_connections"] = 1024

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

    # Specify the credential provider.
    cfg.credentials_provider = credentials_provider

    # Specify the region in which the bucket is located. For example, if your bucket is located in the China (Hangzhou) region, set the region to cn-hangzhou.
    cfg.region = 'cn-hangzhou'

    # Use the configuration to create a Client instance.
    client = oss.Client(cfg)

    # Use the Client instance to perform subsequent operations.


# Call the main function when the script is directly run.
if __name__ == "__main__":
    main()  # The entry point of the script. When the script is directly run, the main function is called.