Volcengine Python SDK

The Volcengine Python SDK uses CredentialProvider objects to resolve authentication credentials. Providers can be static or support automatic background refreshing of temporary credentials.

The Volcengine Python SDK supports two ways to handle credentials: explicit credentials and automatic parsing via CredentialProvider. Different providers suit different scenarios:

The SDK supports two levels of configuration: global configuration via volcenginesdkcore.Configuration and request-level configuration via volcenginesdkcore.interceptor.RuntimeOption.

Settings provided in RuntimeOption will override the global configuration for that specific API call. This is useful for changing the scheme or enabling/disabling client_side_validation on a per-request basis.

import volcenginesdkcore,volcenginesdkecs
from volcenginesdkcore.rest import ApiException
from volcenginesdkcore.interceptor import RuntimeOption

# Global configuration
configuration = volcenginesdkcore.Configuration()
configuration.ak = "Your ak"
configuration.sk = "Your sk"
configuration.scheme="http" # Set global scheme
volcenginesdkcore.Configuration.set_default(configuration)

# Request-level runtime parameters (overrides global configuration)
runtime_options = RuntimeOption(
    scheme="http",
    client_side_validation=True, # Enable client-side validation (default is True)
)

api_instance = volcenginesdkecs.ECSApi()
create_command_request = volcenginesdkecs.CreateCommandRequest(
    command_content="ls -l",
    description="Your command description",
    name="Your command name",
    type="command",
    _configuration=runtime_options,  # Apply runtime parameters here
)

try:
    api_instance.create_command(create_command_request)
except ApiException as e:
    pass

By default, the SDK uses an automated addressing mechanism. If you do not specify an Endpoint, the SDK automatically constructs the service address based on the service name and the Region.

Addressing Logic

1. Region Addressing: The SDK uses a built-in list of regions for automatic addressing. For regions not in the preset list, it defaults to open.volcengineapi.com. You can extend this list via the custom_bootstrap_region attribute in Configuration or the VOLC_BOOTSTRAP_REGION_LIST_CONF environment variable.
2. DualStack (IPv6) Support: When enabled, the domain suffix changes from volcengineapi.com to volcengine-api.com.
   • Priority: use_dual_stack parameter > VOLC_ENABLE_DUALSTACK environment variable.
3. Service Types:
   • Global Services (e.g., CDN, IAM): Uses {Service}.volcengineapi.com.
   • Regional Services (e.g., ECS, RDS): Uses {Service}.{region}.volcengineapi.com.

Standard Addressing Rules

import volcenginesdkcore

configuration = volcenginesdkcore.Configuration()
configuration.ak = "Your ak"
configuration.sk = "Your sk"
configuration.use_dual_stack = True # Enables IPv4 + IPv6 access
configuration.custom_bootstrap_region = {
    "custom_example_region1": {},
    "custom_example_region2": {},
}
volcenginesdkcore.Configuration.set_default(configuration)

The SDK defaults to https. You can change the communication scheme globally via the Configuration object or per-request using RuntimeOption.

Note: Settings provided via RuntimeOption at the API/Request level will override the global Configuration settings.

import volcenginesdkcore, volcenginesdkecs
from volcenginesdkcore.rest import ApiException
from volcenginesdkcore.interceptor import RuntimeOption

# Global configuration
configuration = volcenginesdkcore.Configuration()
configuration.ak = "Your ak"
configuration.sk = "Your sk"
configuration.scheme = "http" # Specify scheme
volcenginesdkcore.Configuration.set_default(configuration)

# API-level runtime parameter settings, overrides global configuration
runtime_options = RuntimeOption(
    scheme="http",
    client_side_validation=True, # Enable client-side validation, enabled by default,
)
api_instance = volcenginesdkecs.ECSApi()
create_command_request = volcenginesdkecs.CreateCommandRequest(
    command_content="ls -l",
    description="Your command description",
    name="Your command name",
    type="command",
    _configuration=runtime_options,  # Set runtime parameters
)
try:
    api_instance.create_command(create_command_request)
except ApiException as e:
    pass

A retry condition determines if a specific error or response warrants a retry attempt.

DefaultRetryCondition

The DefaultRetryCondition triggers a retry if:

1. A network error occurs.
2. A server-side rate-limiting error occurs.
3. The error code is present in the user-defined retry_error_codes set.

Customizing Retry Conditions

You can implement custom logic by inheriting from RetryCondition or extending DefaultRetryCondition to reuse its existing logic.

Implementing a base RetryCondition:

from volcenginesdkcore.retryer.retry_condition import RetryCondition

class CustomRetryCondition(RetryCondition):
    def should_retry(self, response, err):
        # type: (RESTResponse, Exception) -> bool
        # Access user-defined error codes via self.retry_error_codes
        return False

Extending DefaultRetryCondition:

from volcenginesdkcore.retryer.retry_condition import DefaultRetryCondition

class CustomRetryCondition(DefaultRetryCondition):
    def should_retry(self, response, err):
        # type: (RESTResponse, Exception) -> bool
        # Use super() to keep default logic (network/rate-limit/custom codes)
        should_retry = super(CustomRetryCondition, self).should_retry(response, err)
        # Add additional custom logic here
        return should_retry or False

from volcenginesdkcore.retryer.retry_condition import RetryCondition
class CustomRetryCondition(RetryCondition):
    def should_retry(
        self,
        response,
        err
    ):
        # type: (RESTResponse, Exception) -> bool
        retry_error_codes = self.retry_error_codes # 可以获取到用户自定义的错误码
        #................实现自己逻辑

        return False

By default, the SDK automatically constructs the service address based on the service name and region.

Resolution Logic

1. Region Resolution: The SDK uses a built-in list of preset regions. If a region is not in the preset list and not user-configured, it defaults to open.volcengineapi.com. You can extend the list using the VOLC_BOOTSTRAP_REGION_LIST_CONF environment variable or the custom_bootstrap_region configuration key.
2. DualStack (IPv6) Support: When use_dual_stack is set to True in configuration or the VOLC_ENABLE_DUALSTACK environment variable is set, the domain suffix changes from volcengineapi.com to volcengine-api.com.
3. Endpoint Construction:
   • Global services (e.g., CDN, IAM): <ServiceName>.volcengineapi.com (or volcengine-api.com for dual-stack).
   • Regional services (e.g., ECS, RDS): <ServiceName>.<Region>.volcengineapi.com (or volcengine-api.com for dual-stack).

Configuration Example

import volcenginesdkcore
configuration = volcenginesdkcore.Configuration()
configuration.ak = "Your ak"
configuration.sk = "Your sk"
configuration.use_dual_stack = True # Enable dual-stack network (IPv4 + IPv6) access, default is False
configuration.custom_bootstrap_region = {
    "custom_example_region1": {},
    "custom_example_region2": {},
} # Custom auto-resolution region list
volcenginesdkcore.Configuration.set_default(configuration)