Merge "integration_2025-10-13_1068387367426" into "directconnect-Python-2020-04-01-online-1642-2025_09_25_16_20_03"

Conflicts:
pyproject.toml

Author: bytestarter

SDK_Integration_zh.md

@@ -5,6 +5,9 @@
 - [访问凭据](#访问凭据)
   - [AK、SK设置](#aksk设置)
   - [STS Token设置](#sts-token设置)
+  - [STS AssumeRole示例](#sts-assumerole示例)
+  - [STS AssumeRoleWithOidc示例](#sts-assumerolewithoidc示例)
+  - [STS AssumeRoleWithSaml示例](#sts-assumerolewithsaml示例)
 - [EndPoint配置](#endpoint配置)
   - [自定义Endpoint](#自定义endpoint)
   - [自定义RegionId](#自定义regionid)
@@ -28,6 +31,8 @@
     - [自定义退避策略](#自定义退避策略)
 - [异常处理](#异常处理)
 - [Debug机制](#debug机制)
+  - [开启Debug模式](#开启debug模式)
+  - [设置Debug级别](#设置debug级别)
 - [指定日志Logger](#指定日志logger)
 
 # 集成SDK
@@ -133,8 +138,190 @@ try:
 except ApiException as e:
     pass
 ```
+## STS AssumeRole示例
 
+STS AssumeRole（Security Token Service）是火山引擎提供的临时访问凭证机制。开发者通过服务端调用 STS 接口获取临时凭证（临时 AK、SK 和 Token），有效期可配置，适用于安全要求较高的场景。
+<br>
+此接口使用IAM子账号角色进行 AssumeRole 操作后，获取到IAM子用户的信息后，发起真正的API请求，参考如下
+<br>
+连接地址：https://www.volcengine.com/docs/6257/86374
+> ⚠️ 注意事项
+>
+> 1. 最小权限： 仅授予调用方访问所需资源的最小权限，避免使用 * 通配符授予全资源、全操作权限。
+> 2. 设置合理的有效期: 请根据实际情况设置合理有效期，越短越安全，建议不要超过1小时。
+
+支持`configuration`级别全局配置和接口级别的运行时参数设置`RuntimeOption`;`RuntimeOption`设置会覆盖`configuration`全局配置。  
+
+**代码示例：**
 
+```python
+from __future__ import print_function
+import volcenginesdkcore
+import volcenginesdkvpc
+from volcenginesdkcore.rest import ApiException
+from volcenginesdkcore.auth.providers.sts_provider import StsCredentialProvider
+
+if __name__ == '__main__':
+    # 注意示例代码安全，代码泄漏会导致AK/SK泄漏，有极大的安全风险。
+    configuration = volcenginesdkcore.Configuration()
+    configuration.region = "cn-beijing"
+
+    # 这里是使用STS ASSUMEROLE角色的方式
+    configuration.credential_provider = StsCredentialProvider(
+        ak="Your ak",  # 必填，子账号的ak
+        sk="Your sk",  # 必填，子账号的sk
+        role_name="Your role name",  # 必填，子账号的角色TRN，如trn:iam::2110400000:role/role123  ,此处填写role123
+        account_id="Your account id",  # 必填，子账号的角色TRN，如trn:iam::2110400000:role/role123  ,此处填写2110400000
+        duration_seconds=3600,  # 非必填，有效期默认3600秒
+        scheme="https",  # 非必填，域名前缀，默认https
+        host="sts.volcengineapi.com",  # 非必填，请求域名，默认sts.volcengineapi.com
+        region="cn-beijing",  # 非必填，请求服务器区域地址，默认cn-north-1
+        timeout=30,  # 非必填，请求超时时间，默认30秒
+        expired_buffer_seconds=60, #非必填，session有效期前多久过期，剩余时间小于这个设置就要请求新的token了，默认60秒
+        policy='{"Statement":[{"Effect":"Allow","Action":["vpc:CreateVpc"],"Resource":["*"],"Condition":{"StringEquals":{"volc:RequestedRegion":["cn-beijing"]}}}]}' # 非必填，授权策略，默认为空
+    )
+
+    # set default configuration
+    volcenginesdkcore.Configuration.set_default(configuration)
+    # use global default configuration
+    api_instance = volcenginesdkvpc.VPCApi()
+    create_vpc_request = volcenginesdkvpc.CreateVpcRequest(
+        cidr_block="192.168.0.0/16",
+        dns_servers=["10.0.0.1", "10.1.1.2"],
+    )
+
+    try:
+        # 复制代码运行示例，请自行打印API返回值。
+        api_instance.create_vpc(create_vpc_request)
+    except ApiException as e:
+        # 复制代码运行示例，请自行打印API错误信息。
+        # print("Exception when calling api: %s\n" % e)
+        pass
+```
+
+## STS AssumeRoleWithOidc示例
+
+STS AssumeRoleOIDC（Security Token Service）是火山引擎提供的临时访问凭证机制。开发者通过oidc_token在服务端调用 STS 接口获取临时凭证（临时 AK、SK 和 Token），有效期可配置，适用于安全要求较高的场景。
+<br>
+此接口使用oidc身份提供商角色使用oidc_token进行 AssumeRoleWithOidc 操作后，获取到用户的信息后，发起真正的API请求，参考如下
+<br>
+连接地址：https://www.volcengine.com/docs/6257/1494877
+> ⚠️ 注意事项
+>
+> 1. 最小权限： 仅授予调用方访问所需资源的最小权限，避免使用 * 通配符授予全资源、全操作权限。
+> 2. 设置合理的有效期: 请根据实际情况设置合理有效期，越短越安全，建议不要超过1小时。
+
+支持`configuration`级别全局配置和接口级别的运行时参数设置`RuntimeOption`;`RuntimeOption`设置会覆盖`configuration`全局配置。  
+
+**代码示例：**
+
+```python
+# Example Code generated by Beijing Volcanoengine Technology.
+from __future__ import print_function
+import volcenginesdkcore
+import volcenginesdkvpc
+from volcenginesdkcore.rest import ApiException
+from volcenginesdkcore.auth.providers.sts_oidc_provider import StsOidcCredentialProvider
+
+if __name__ == '__main__':
+    # 注意示例代码安全，代码泄漏会导致AK/SK泄漏，有极大的安全风险。
+    configuration = volcenginesdkcore.Configuration()
+    configuration.region = "cn-beijing"
+
+    # 这里是使用STS ASSUMEROLE_OIDC角色的方式
+    configuration.credential_provider = StsOidcCredentialProvider(
+        role_name="Your role name",  # 必填，账号的角色TRN，如trn:iam::2110400000:role/role123  ,此处填写role123
+        account_id="Your account id",  # 必填，账号的角色TRN，如trn:iam::2110400000:role/role123  ,此处填写2110400000
+        oidc_token="your oidc token",  # 必填，生成的oidcToken，如ey********
+        duration_seconds=3600,  # 非必填，有效期默认3600秒
+        scheme="https",  # 非必填，域名前缀，默认https
+        host="sts.volcengineapi.com",  # 非必填，请求域名，默认sts.volcengineapi.com
+        region="cn-beijing",  # 非必填，请求服务器区域地址，默认cn-beijing
+        timeout=30,  # 非必填，请求超时时间，默认30秒
+        expired_buffer_seconds=60,  # 非必填，session有效期前多久过期，剩余时间小于这个设置就要请求新的token了，默认60秒
+        policy='{"Statement":[{"Effect":"Allow","Action":["vpc:CreateVpc"],"Resource":["*"],"Condition":{"StringEquals":{"volc:RequestedRegion":["cn-beijing"]}}}]}' # 非必填，授权策略，默认为空
+    )
+
+    # set default configuration
+    volcenginesdkcore.Configuration.set_default(configuration)
+    # use global default configuration
+    api_instance = volcenginesdkvpc.VPCApi()
+    create_vpc_request = volcenginesdkvpc.CreateVpcRequest(
+        cidr_block="192.168.0.0/16",
+        dns_servers=["10.0.0.1", "10.1.1.2"],
+    )
+
+    try:
+        # 复制代码运行示例，请自行打印API返回值。
+        api_instance.create_vpc(create_vpc_request)
+    except ApiException as e:
+        # 复制代码运行示例，请自行打印API错误信息。
+        # print("Exception when calling api: %s\n" % e)
+        pass
+
+```
+
+## STS AssumeRoleWithSaml示例
+
+STS AssumeRoleWithSaml（Security Token Service）是火山引擎提供的临时访问凭证机制。开发者通过saml_token在服务端调用 STS 接口获取临时凭证（临时 AK、SK 和 Token），有效期可配置，适用于安全要求较高的场景。
+<br>
+此接口使用saml身份提供商角色使用saml_resp进行 AssumeRoleWithSaml 操作后，获取到用户的信息后，发起真正的API请求，参考如下
+<br>
+连接地址：https://www.volcengine.com/docs/6257/1631607
+> ⚠️ 注意事项
+>
+> 1. 最小权限： 仅授予调用方访问所需资源的最小权限，避免使用 * 通配符授予全资源、全操作权限。
+> 2. 设置合理的有效期: 请根据实际情况设置合理有效期，越短越安全，建议不要超过1小时。
+
+支持`configuration`级别全局配置和接口级别的运行时参数设置`RuntimeOption`;`RuntimeOption`设置会覆盖`configuration`全局配置。  
+
+**代码示例：**
+```python
+# Example Code generated by Beijing Volcanoengine Technology.
+from __future__ import print_function
+import volcenginesdkcore
+import volcenginesdkvpc
+from volcenginesdkcore.rest import ApiException
+from volcenginesdkcore.auth.providers.sts_saml_provider import StsSamlCredentialProvider
+
+if __name__ == '__main__':
+    # 注意示例代码安全，代码泄漏会导致AK/SK泄漏，有极大的安全风险。
+    configuration = volcenginesdkcore.Configuration()
+    configuration.region = "cn-beijing"
+
+    # 这里是使用STS ASSUMEROLE_SAML角色的方式
+    configuration.credential_provider = StsSamlCredentialProvider(
+        role_name="Your role name",  # 必填，账号的角色TRN，如trn:iam::2110400000:role/role123,此处填写role123
+        account_id="Your account id",  # 必填，账号的角色TRN，如trn:iam::2110400000:saml-provider/role123,此处填写2110400000
+        provider_name="your provider name",# 必填，认证provider的TRN，如trn:iam::2110400000:saml-provider/provider123,此处填写provider123
+        saml_resp="your saml resp",  # 必填，认证获取到的SAML的断言
+        duration_seconds=3600,  # 非必填，有效期默认3600秒
+        scheme="https",  # 非必填，域名前缀，默认https
+        host="sts.volcengineapi.com",  # 非必填，请求域名，默认sts.volcengineapi.com
+        region="cn-beijing",  # 非必填，请求服务器区域地址，默认cn-beijing
+        timeout=30,  # 非必填，请求超时时间，默认30秒
+        expired_buffer_seconds=60,  # 非必填，session有效期前多久过期，剩余时间小于这个设置就要请求新的token了，默认60秒
+        policy='{"Statement":[{"Effect":"Allow","Action":["vpc:CreateVpc"],"Resource":["*"],"Condition":{"StringEquals":{"volc:RequestedRegion":["cn-beijing"]}}}]}' # 非必填，授权策略，默认为空
+    )
+
+    # set default configuration
+    volcenginesdkcore.Configuration.set_default(configuration)
+    # use global default configuration
+    api_instance = volcenginesdkvpc.VPCApi()
+    create_vpc_request = volcenginesdkvpc.CreateVpcRequest(
+        cidr_block="192.168.0.0/16",
+        dns_servers=["10.0.0.1", "10.1.1.2"],
+    )
+
+    try:
+        # 复制代码运行示例，请自行打印API返回值。
+        api_instance.create_vpc(create_vpc_request)
+    except ApiException as e:
+        # 复制代码运行示例，请自行打印API错误信息。
+        # print("Exception when calling api: %s\n" % e)
+        pass
+
+```
 
 # EndPoint配置
 
@@ -293,6 +480,7 @@ except ApiException as e:
 ## 配置Http(s)代理
 
 ```python
+import volcenginesdkcore,volcenginesdkecs
 configuration = volcenginesdkcore.Configuration()
 configuration.ak = "Your AK"
 configuration.sk = "Your SK"
@@ -563,6 +751,8 @@ except Exception as e:
 
 为便于客户在处理请求时进行问题排查和调试，SDK 支持日志功能，并提供多种日志级别设置。客户可根据实际需求配置日志级别，获取详细的请求与响应信息，以提升排障效率和系统可 observability（可观测性）。
 
+## 开启Debug模式
+
 > **默认**  
 > * `debug` - `False`  
 
@@ -576,6 +766,39 @@ configuration.debug = True  # 开启debug模式
 volcenginesdkcore.Configuration.set_default(configuration)
 ```
 
+## 设置debug级别
+默认情况下开启debug日志后，会输出所有的debug日志；为了按需输出日志，可以调用`configuration.log_level`进行以下设置：
+
+```python
+import volcenginesdkcore
+from volcenginesdkcore.observability.debugger import LogLevel
+configuration = volcenginesdkcore.Configuration()
+configuration.ak = "Your AK"
+configuration.sk = "Your SK"
+configuration.debug = True  # 开启debug模式
+configuration.log_level = LogLevel.LOG_DEBUG_WITH_CONFIG.mask | LogLevel.LOG_DEBUG_WITH_REQUEST.mask | LogLevel.LOG_DEBUG_WITH_RESPONSE.mask
+volcenginesdkcore.Configuration.set_default(configuration)
+
+```
+
+**支持的日志级别**
+
+
+| 枚举项                              | 父级日志(同时打印父级日志) | 打印的内容                                |
+| -------------------------------- |-----|--------------------------------------|
+| `LOG_DEBUG_WITH_REQUEST`         | —   | 请求行与基础请求信息：`HTTP方法`、`URL（含查询参数）`、`请求头` |
+| `LOG_DEBUG_WITH_REQUEST_BODY`    | `LOG_DEBUG_WITH_REQUEST` | `请求体`                                |
+| `LOG_DEBUG_WITH_REQUEST_ID`      | `LOG_DEBUG_WITH_REQUEST` | `RequestId`                          |
+| `LOG_DEBUG_WITH_RESPONSE`        | `LOG_DEBUG_WITH_REQUEST` | `响应状态码` `响应头`                        |
+| `LOG_DEBUG_WITH_RESPONSE_BODY`   | `LOG_DEBUG_WITH_RESPONSE` | `响应体`                                |
+| `LOG_DEBUG_WITH_SIGNING`         | `LOG_DEBUG_WITH_REQUEST` | `签名过程`                               |
+| `LOG_DEBUG_WITH_ENDPOINT`        | `LOG_DEBUG_WITH_REQUEST` | ` Endpoint 选择过程`                     |
+| `LOG_DEBUG_WITH_REQUEST_RETRIES` | `LOG_DEBUG_WITH_REQUEST` | `重试信息`                               |
+| `LOG_DEBUG_WITH_CONFIG`          | `LOG_DEBUG_WITH_REQUEST` | `关键配置信息`                             |
+| `LOG_DEBUG_ALL`                  |   —     | `包含上面所有信息`                           |
+
+
+
 # 指定日志Logger
 
 > **默认**  

pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "volcengine-python-sdk"
-version = "4.0.22"
+version = "4.0.24"
 authors = [
     {name = "volc-engine", email = "[email protected]"},
 ]

volcenginesdkarkruntime/_utils/_key_agreement.py

@@ -12,6 +12,7 @@
 
 from __future__ import annotations
 
+import re
 import base64
 from typing import Tuple
 
@@ -72,6 +73,28 @@ def aes_gcm_decrypt_base64_string(key: bytes, nonce: bytes, ciphertext: str) ->
     return aes_gcm_decrypt_bytes(key, nonce, cipher_bytes).decode()
 
 
+base64_pattern = r'(?:[A-Za-z0-9+/]{4})*(?:[A-Za-z0-9+/]{2}==|[A-Za-z0-9+/]{3}=|[A-Za-z0-9+/]{4})'
+
+
+def aes_gcm_decrypt_base64_list(key: bytes, nonce: bytes, ciphertext: str) -> str:
+    # Decrypt
+    base64_array = re.findall(base64_pattern, ciphertext)
+    result = []
+    for b64 in base64_array:
+        try:
+            result.append(aes_gcm_decrypt_base64_string(key, nonce, b64))
+        except Exception:
+            for i in range(20, len(b64), 4):
+                try:
+                    decrypted = aes_gcm_decrypt_base64_string(key, nonce, b64[:i+4])
+                    result.append(decrypted)
+                    decrypted = aes_gcm_decrypt_base64_string(key, nonce, b64[i+4:])
+                    result.append(decrypted)
+                except Exception:
+                    result.append('')
+    return ''.join(result)
+
+
 def marshal_cryptography_pub_key(key) -> bytes:
     # python version of crypto/elliptic/elliptic.go Marshal
     # without point on curve check

volcenginesdkarkruntime/resources/chat/completions.py

@@ -29,7 +29,7 @@
 
 from ..._types import Body, Query, Headers
 from ..._utils._utils import deepcopy_minimal, with_sts_token, async_with_sts_token
-from ..._utils._key_agreement import aes_gcm_decrypt_base64_string
+from ..._utils._key_agreement import aes_gcm_decrypt_base64_string, aes_gcm_decrypt_base64_list
 from ..._base_client import make_request_options
 from ..._resource import SyncAPIResource, AsyncAPIResource
 from ..._compat import cached_property
@@ -142,9 +142,14 @@ def _decrypt(
                         choice.message is not None and choice.finish_reason != 'content_filter'
                         and choice.message.content is not None
                     ):
-                        choice.message.content = aes_gcm_decrypt_base64_string(
+                        content = aes_gcm_decrypt_base64_string(
                             key, nonce, choice.message.content
                         )
+                        if content == '':
+                            content = aes_gcm_decrypt_base64_list(
+                                key, nonce, choice.message.content
+                            )
+                        choice.message.content = content
                     resp.choices[index] = choice
             return resp
         else:
@@ -291,9 +296,14 @@ async def _decrypt(
                         choice.message is not None and choice.finish_reason != 'content_filter'
                         and choice.message.content is not None
                     ):
-                        choice.message.content = aes_gcm_decrypt_base64_string(
+                        content = aes_gcm_decrypt_base64_string(
                             key, nonce, choice.message.content
                         )
+                        if content == '':
+                            content = aes_gcm_decrypt_base64_list(
+                                key, nonce, choice.message.content
+                            )
+                        choice.message.content = content
                     resp.choices[index] = choice
             return resp
         else:

volcenginesdkarkruntime/resources/responses/responses.py

@@ -90,6 +90,7 @@ def create(
         tools: Iterable[ToolParam] | None = None,
         top_p: Optional[float] | None = None,
         max_tool_calls: Optional[int] | None = None,
+        expire_at: Optional[int] | None = None,
         extra_headers: Headers | None = None,
         extra_query: Query | None = None,
         extra_body: Body | None = None,
@@ -114,7 +115,8 @@ def create(
                 "tool_choice": tool_choice,
                 "tools": tools,
                 "top_p": top_p,
-                "max_tool_calls": max_tool_calls
+                "max_tool_calls": max_tool_calls,
+                "expire_at": expire_at,
             },
             options=make_request_options(
                 extra_headers=extra_headers,
@@ -203,6 +205,7 @@ async def create(
         tools: Iterable[ToolParam] | None = None,
         top_p: Optional[float] | None = None,
         max_tool_calls: Optional[int] | None = None,
+        expire_at: Optional[int] | None = None,
         extra_headers: Headers | None = None,
         extra_query: Query | None = None,
         extra_body: Body | None = None,
@@ -228,6 +231,7 @@ async def create(
                 "tools": tools,
                 "top_p": top_p,
                 "max_tool_calls": max_tool_calls,
+                "expire_at": expire_at,
             },
             options=make_request_options(
                 extra_headers=extra_headers,