Merge branch 'dev/lsx/http-proxy' into 'integration_2025-07-24_1018981540354'

feat: [development task] core (1482850)

See merge request iaasng/volcengine-python-sdk!721

Author: BitsAdmin

SDK_Integration_zh.md

@@ -1,29 +1,34 @@
 # 目录
+- [目录](#目录)
 - [集成SDK](#集成sdk)
-  - [环境要求](#环境要求)
-  - [访问凭据](#访问凭据)
-    - [AK、SK设置](#aksk设置)
-  - [EndPoint配置](#endpoint配置)
-    - [自定义Endpoint](#自定义endpoint)
-    - [自定义RegionId](#自定义regionid)
-    - [自动化Endpoint寻址](#自动化endpoint寻址)
-      - [Endpoint默认寻址](#endpoint默认寻址)
-  - [Http连接池配置](#http连接池配置)
-  - [Https请求配置](#https请求配置)
-    - [指定scheme](#指定scheme)
-    - [忽略SSL验证](#忽略ssl验证)
-  - [超时配置](#超时配置)
-  - [重试机制](#重试机制)
-    - [重试代码配置](#重试代码配置)
-    - [重试条件](#重试条件)
-      - [默认重试条件](#默认重试条件)
-      - [自定义重试条件](#自定义重试条件)
-    - [退避策略](#退避策略)
-      - [内置退避策略](#内置退避策略)
-      - [自定义退避策略](#自定义退避策略)
-  - [异常处理](#异常处理)
-  - [Debug机制](#debug机制)
-  - [指定日志Logger](#指定日志logger)
+- [环境要求](#环境要求)
+- [访问凭据](#访问凭据)
+  - [AK、SK设置](#aksk设置)
+  - [STS Token设置](#sts-token设置)
+- [EndPoint配置](#endpoint配置)
+  - [自定义Endpoint](#自定义endpoint)
+  - [自定义RegionId](#自定义regionid)
+  - [自动化Endpoint寻址](#自动化endpoint寻址)
+    - [Endpoint默认寻址](#endpoint默认寻址)
+- [Http连接池配置](#http连接池配置)
+- [Https请求配置](#https请求配置)
+  - [指定scheme](#指定scheme)
+- [Http(s)代理配置](#https代理配置)
+  - [配置Http(s)代理](#配置https代理)
+  - [注意事项](#注意事项)
+  - [忽略SSL验证](#忽略ssl验证)
+- [超时配置](#超时配置)
+- [重试机制](#重试机制)
+  - [重试代码配置](#重试代码配置)
+  - [重试条件](#重试条件)
+    - [默认重试条件](#默认重试条件)
+    - [自定义重试条件](#自定义重试条件)
+  - [退避策略](#退避策略)
+    - [内置退避策略](#内置退避策略)
+    - [自定义退避策略](#自定义退避策略)
+- [异常处理](#异常处理)
+- [Debug机制](#debug机制)
+- [指定日志Logger](#指定日志logger)
 
 # 集成SDK
 
@@ -36,7 +41,7 @@
 
 # 访问凭据
 
-为保障资源访问安全，火山引擎 Python SDK 目前暂时只支持 **AK/SK**认证设置。
+为保障资源访问安全，火山引擎 Python SDK 目前支持 `AK/SK`和 `STS Token` 认证设置。
 
 ## AK、SK设置
 
@@ -83,6 +88,53 @@ except ApiException as e:
     pass
 ```
 
+## STS Token设置
+
+STS（Security Token Service）是火山引擎提供的临时访问凭证机制。开发者通过服务端调用 STS 接口获取临时凭证（临时 AK、SK 和 Token），有效期可配置，适用于安全要求较高的场景。
+
+> ⚠️ 注意事项
+>
+> 1. 最小权限： 仅授予调用方访问所需资源的最小权限，避免使用 * 通配符授予全资源、全操作权限。
+> 2. 设置合理的有效期: 请根据实际情况设置合理有效期，越短越安全，建议不要超过1小时。
+
+支持`configuration`级别全局配置和接口级别的运行时参数设置`RuntimeOption`;`RuntimeOption`设置会覆盖`configuration`全局配置。  
+
+**代码示例：**
+```python
+import volcenginesdkcore,volcenginesdkecs
+from volcenginesdkcore.rest import ApiException
+from volcenginesdkcore.interceptor import RuntimeOption
+
+# 全局设置
+configuration = volcenginesdkcore.Configuration()
+configuration.ak = "Your ak"
+configuration.sk = "Your sk"
+configuration.session_token = "Your session token"
+configuration.debug = True
+volcenginesdkcore.Configuration.set_default(configuration)
+
+# 接口级别运行时参数设置,会覆盖全局配置
+runtime_options = RuntimeOption(
+  ak =  "Your ak", 
+  sk = "Your sk",
+  session_token="Your session token",
+  client_side_validation = 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,  # 配置运行时参数
+)
+try:
+    api_instance.create_command(create_command_request)
+except ApiException as e:
+    pass
+```
+
+
 
 # EndPoint配置
 
@@ -233,6 +285,35 @@ except ApiException as e:
     pass
 ```
 
+# Http(s)代理配置
+
+> - **默认** 
+>   无代理
+
+## 配置Http(s)代理
+
+```python
+configuration = volcenginesdkcore.Configuration()
+configuration.ak = "Your AK"
+configuration.sk = "Your SK"
+
+configuration.http_proxy = "http://your_proxy:8080"
+configuration.https_proxy = "http://your_proxy:8080"
+
+volcenginesdkcore.Configuration.set_default(configuration)
+
+api_instance = volcenginesdkecs.ECSApi()
+```
+
+## 注意事项
+
+支持通过以下环境变量配置代理:
+
+http_proxy/HTTP_PROXY, https_proxy/HTTPS_PROXY, no_proxy/NO_PROXY
+
+优先级：代码 > 环境变量
+
+
 ## 忽略SSL验证
 
 > **默认**  

volcenginesdkcore/configuration.py

@@ -127,6 +127,9 @@ def __init__(self):
 
         # Proxy URL
         self.proxy = None
+        self.http_proxy = None
+        self.https_proxy = None
+
         # Safe chars for path_param
         self.safe_chars_for_path_param = ''
 

volcenginesdkcore/rest.py

@@ -5,6 +5,7 @@
 import io
 import json
 import logging
+import os
 import re
 import ssl
 
@@ -38,7 +39,6 @@ def getheader(self, name, default=None):
         """Returns a given response header."""
         return self.urllib3_response.getheader(name, default)
 
-
 class RESTClientObject(object):
 
     def __init__(self, configuration, pools_size=4, maxsize=None):
@@ -48,6 +48,8 @@ def __init__(self, configuration, pools_size=4, maxsize=None):
         # maxsize is the number of requests to host that are allowed in parallel  # noqa: E501
         # Custom SSL certificates and client certificates: http://urllib3.readthedocs.io/en/latest/advanced-usage.html  # noqa: E501
 
+        proxy_url = self.__get_proxy(configuration)
+
         # cert_reqs
         if configuration.verify_ssl:
             cert_reqs = ssl.CERT_REQUIRED
@@ -78,16 +80,16 @@ def __init__(self, configuration, pools_size=4, maxsize=None):
             connect=configuration.connect_timeout,
             read=configuration.read_timeout,
         )
-        # https pool manager
-        if configuration.proxy:
+
+        if proxy_url:
             self.pool_manager = urllib3.ProxyManager(
                 num_pools=pools_size,
                 maxsize=maxsize,
                 cert_reqs=cert_reqs,
                 ca_certs=ca_certs,
                 cert_file=configuration.cert_file,
                 key_file=configuration.key_file,
-                proxy_url=configuration.proxy,
+                proxy_url=proxy_url,
                 timeout=timeout,
                 retries=Retry(total=False),
                 **addition_pool_args
@@ -105,6 +107,25 @@ def __init__(self, configuration, pools_size=4, maxsize=None):
                 **addition_pool_args
             )
 
+    def __get_proxy(self, configuration):
+        proxy_url = configuration.proxy
+        if not proxy_url:
+            if configuration.scheme == 'http':
+                if configuration.http_proxy:
+                    proxy_url = configuration.http_proxy
+                elif os.getenv('HTTP_PROXY'):
+                    proxy_url = os.getenv('HTTP_PROXY')
+                elif os.getenv('http_proxy'):
+                    proxy_url = os.getenv('http_proxy')
+            elif configuration.scheme == 'https':
+                if configuration.https_proxy:
+                    proxy_url = configuration.https_proxy
+                elif os.getenv('HTTPS_PROXY'):
+                    proxy_url = os.getenv('HTTPS_PROXY')
+                elif os.getenv('https_proxy'):
+                    proxy_url = os.getenv('https_proxy')
+        return proxy_url
+
     def request(self, method, url, query_params=None, headers=None,
                 body=None, post_params=None, _preload_content=True,
                 _request_timeout=None):