TosClient 提供了一系列接口用与 TOS 服务进行交互,以管理存储桶和对象等 TOS 服务上的资源。可通过AccessKey/SecretKey、STS (Security Token Service)等方式初始化 TosClient 。在初始化时,可设置建立连接超时时间、超时重试次数和最大空闲连接数量等可选参数。本文介绍如何初始化 TOS Python SDK。
初始化 SDK 前,您需要先配置长期访问凭证。本章节介绍不同操作系统下配置长期访问凭证的操作步骤。
nano ~/.bash_profile
export TOS_ACCESS_KEY=AKTPYmI1Z**** export TOS_SECRET_KEY=T1dJM01UU****
source ~/.bash_profile
echo $TOS_ACCESS_KEY echo $TOS_SECRET_KEY
如果配置成功,则返回如下示例:
AKTPYmI1Z**** T1dJM01UU****
以下代码用于使用 TOS 域名初始化。
说明
import os import tos # 从环境变量获取 AKSK 信息 ak = os.getenv('TOS_ACCESS_KEY') sk = os.getenv('TOS_SECRET_KEY') # your endpoint 和 your region 填写Bucket 所在区域对应的Endpoint。# 以华北2(北京)为例,your endpoint 填写 tos-cn-beijing.volces.com,your region 填写 cn-beijing。 endpoint = "your endpoint" region = "your region" client = tos.TosClientV2(ak, sk, endpoint, region)
以下代码用于使用可选参数初始化。
import tos import os # ak和sk为临时访问凭证中的安全密钥(AccessKeyId、SecretAccessKey) ak = os.getenv('TOS_ACCESS_KEY') sk = os.getenv('TOS_SECRET_KEY') sts_token = "your security token" # your endpoint 和 your region 填写Bucket 所在区域对应的Endpoint。# 以华北2(北京)为例,your endpoint 填写 tos-cn-beijing.volces.com,your region 填写 cn-beijing。 endpoint = "your endpoint" region = "your region" # 使用临时访问凭证中的认证信息初始化TosClient client = tos.TosClientV2(ak, sk, endpoint, region, # 通过security_token可选参数设置STS security_token=sts_token, # 通过connection_time可选参数设置连接超时,单位:秒 connection_time=10, # 通过socket_timeout可选参数设置Socket读写超时,单位:秒 socket_timeout=30)
您可以通过 STS 服务向其他用户颁发临时访问凭证,在凭证有效期内,用户可访问您的 TOS 资源,而无需透露您的长期密钥,保障您 TOS 资源的安全性。
说明
您可以通过 STS 服务的 AssumeRole 接口获取临时访问凭证,临时访问凭证中包含安全密钥(AccessKeyId、SecretAccessKey)和安全令牌(SessionToken),后续您可以使用该信息访问 TOS 服务。关于搭建 STS 服务的基本操作,请参见 使用 STS 临时 AK/SK+Token 访问火山引擎 TOS。
以下代码用于使用 STS 初始化。
import os import tos # ak和sk为临时访问凭证中的安全密钥(AccessKeyId、SecretAccessKey) ak = "your access key" sk = "your secret key" # sts_token为临时访问凭证中的安全令牌(SessionToken) sts_token = "your security token" # your endpoint 和 your region 填写Bucket 所在区域对应的Endpoint。# 以华北2(北京)为例,your endpoint 填写 tos-cn-beijing.volces.com,your region 填写 cn-beijing。 endpoint = "your endpoint" region = "your region" # 使用临时访问凭证中的认证信息初始化TosClient client = tos.TosClientV2(ak, sk, endpoint, region, security_token=sts_token)
您可以在初始化 TosClient 时,通过添加可选参数配置网络请求的超时时间,目前 TOS Python SDK支持配置连接超时 connection_time
和请求超时 socket_timeout
。
以下代码用于初始化 TosClient 时配置超时时间。
import tos import os # 从环境变量获取 AKSK 信息。 ak = os.getenv('TOS_ACCESS_KEY') sk = os.getenv('TOS_SECRET_KEY') # your endpoint 和 your region 填写Bucket 所在区域对应的Endpoint。# 以华北2(北京)为例,your endpoint 填写 tos-cn-beijing.volces.com,your region 填写 cn-beijing。 endpoint = "your endpoint" region = "your region" # 创建 TosClientV2 对象,并设置连接超时为30秒, Socket 读写超时时间为60秒 # connection_time为连接超时,socket_timeout为请求超时时间。 client = tos.TosClientV2(ak, sk, endpoint, region, connection_time=30, socket_timeout=60)
网络波动或短期 TOS 服务异常(返回 500 状态码)等场景会导致调用 TOS 服务失败,针对此问题 Python SDK 内部提供了重试机制,幂等操作的接口在失败后会使用指数避让策略进行重试,非幂接口则直接抛出对应异常。您可以在初始化 TosClient 时,添加可选参数配置重试次数。
import os import tos # 从环境变量获取 AKSK 信息 ak = os.getenv('TOS_ACCESS_KEY') sk = os.getenv('TOS_SECRET_KEY') # your endpoint 和 your region 填写Bucket 所在区域对应的Endpoint。# 以华北2(北京)为例,your endpoint 填写 tos-cn-beijing.volces.com,your region 填写 cn-beijing。 endpoint = "your endpoint" region = "your region" # 创建 TosClientV2 对象,并设置超时重试次数为3次。重试策略为指数避让策略,基准时间为100ms,及第一次重试间隔100ms,第二次重试间隔200ms,第三次重试400ms client = tos.TosClientV2(ak, sk, endpoint, region, max_retry_count=3)
对象上传和下载时 TOS 返回对象的 CRC 值,SDK 验证本地计算的 CRC 和 TOS 返回的 CRC 是否相等,校验上传和下载数据的完整性。为确保上传和下载过程中数据的完整性,SDK 默认开启 CRC 数据校验,您可以在初始化 TosClient 时,添加可选参数关闭 CRC 校验功能。
警告
强烈建议不要关闭 CRC 数据校验功能。若关闭此功能,TOS 不保障上传和下载过程中数据完整性。
import os import tos # 从环境变量获取 AKSK 信息 ak = os.getenv('TOS_ACCESS_KEY') sk = os.getenv('TOS_SECRET_KEY') # your endpoint 和 your region 填写 Bucket 所在区域对应的Endpoint。# 以华北2(北京)为例,your endpoint 填写 tos-cn-beijing.volces.com,your region 填写 cn-beijing。 endpoint = "your endpoint" region = "your region" # 创建 TosClientV2 对象,并设置 enable_crc=False 来关闭 CRC 数据校验 client = tos.TosClientV2(ak, sk, endpoint, region, enable_crc=True)
TOS Python SDK 支持配置代理服务器的方式访问 TOS 服务,您可以在初始化 TosClient 时,添加可选参数配置代理服务器。
说明
目前只支持 HTTP 协议代理。
import os import tos # 从环境变量获取 AKSK 信息 ak = os.getenv('TOS_ACCESS_KEY') sk = os.getenv('TOS_SECRET_KEY') # your endpoint 和 your region 填写Bucket 所在区域对应的Endpoint。# 以华北2(北京)为例,your endpoint 填写 tos-cn-beijing.volces.com,your region 填写 cn-beijing。 endpoint = "your endpoint" region = "your region" # 创建 TosClientV2 对象,通过可选参数proxy_host、proxy_port、proxy_username、proxy_password来配置代理 client = tos.TosClientV2(ak, sk, endpoint, region, proxy_host='<your proxy host>', proxy_port=80, proxy_username='<your proxy user name>', proxy_password='<your proxy password>')
TOS Python SDK 支持连接池配置,您可以在初始化 TosClient 时,添加可选参数配置连接池大小。
说明
连接池大小默认配置为 1024,建议您使用一个 TosClient 实例。
import os import tos # 从环境变量获取 AKSK 信息 ak = os.getenv('TOS_ACCESS_KEY') sk = os.getenv('TOS_SECRET_KEY') # your endpoint 和 your region 填写Bucket 所在区域对应的Endpoint。# 以华北2(北京)为例,your endpoint 填写 tos-cn-beijing.volces.com,your region 填写 cn-beijing。 endpoint = "your endpoint" region = "your region" # 创建 TosClientV2 对象,并设置max_connections=1024将连接池大小设置为1024 client = tos.TosClientV2(ak, sk, endpoint, region, max_connections=1024)
TOS Python SDK 支持设置自定义域名,您可以在初始化 TosClient 时,传入自定义域名作为 Host。指定自定义域名后,使用 SDK 接口中无需传入 Bucket 。
说明
使用自定义域名前需要在服务端配置自定义域名,详情请参见设置自定义域名。
import os import tos # 从环境变量获取 AKSK 信息 ak = os.getenv('TOS_ACCESS_KEY') sk = os.getenv('TOS_SECRET_KEY') # custom_domain 和 your region 填写您的自定义域名和 Bucket 所在区域对应的 region。# 以华北2(北京)为例,your region 填写 cn-beijing。 custom_domain = "your custom endpoint" region = "your region" # 创建 TosClientV2 对象,并设置is_custom_domain=True,标识当前域名为自定义域名 # 使用自定义域名前,需要在TOS上完成配置 # 详情:https://www.volcengine.com/docs/6349/128983 client = tos.TosClientV2(ak, sk, custom_domain, region, is_custom_domain=True)
TOS Python SDK 支持设置 ECS 免密登录,您可以在初始化 TosClient 时,添加 credentials_provider
参数。
说明
在使用 ECS 免密登录之前,需要先绑定 IAM 角色到 ECS,详细信息请参见 ECS绑定 IAM 角色,并使用角色名作为参数初始化TosClient。
# your endpoint 和 your region 填写Bucket 所在区域对应的Endpoint。# 以华北2(北京)为例,your endpoint 填写 tos-cn-beijing.volces.com,your region 填写 cn-beijing。 endpoint = "your endpoint" region = "your region" role_name = "your role name" # 创建 TosClientV2 对象,并设置icredentials_provider=tos.EcsCredentialsProvider(),使用 ECS 免密登录 # 使用 ECS 免密登录前,需要创建 IAM 角色绑定到 ECS # 详情:https://www.volcengine.com/docs/6627/155606 client = tos.TosClientV2(endpoint=endpoint, region=region, credentials_provider=tos.EcsCredentialsProvider(role_name))
初始化 TosClient 支持参数如下。
参数 | 参数类型 | 是否必选 | 示例值 | 说明 |
---|---|---|---|---|
ak | str | 是 | AKTPYmI1ZGQwMDA0NjlhNGFkMzhjNzM0N2Q0OTQ3ZTV**** | Access Key ID,即密钥ID。 |
sk | str | 是 | T1dJM01UUXpOak0wTVdWak5EUmtOR0poWldJNU1HWmxaV1V5TkdReVl6**** | SecretAccess Key,即私有访问密钥。 |
endpoint | str | 是 | tos-cn-beijing.volces.com | 访问域名。 |
region | str | 是 | cn-beijing | TOS服务端所在地域。 |
security_token | str | 否 | STSeyJBY2NvdW50SWQiOjIxMDAwMDUyMjQsIklkZW50aXR5VHlwZSI6NCwiSWRlbnRpdHlJZCI6MTE3MjI5NiwiQ2hhbm5lbCI6IlVzZXIiLCJBY2Nlc3NLZXlJZCI6IkFLVFBZbUkxWkdRd01EQTBOamxoTkdGa016aGpOek0wTjJRME9UUTNaVFZqTXpFIiwiU2l**** | 临时访问凭证中的安全令牌。 |
enable_verify_ssl | bool | 否 | True | 配置是否开启 SSL 证书校验。 |
auto_recognize_content_type | bool | 否 | True | 自动识别 MIME 类型。 |
connection_timeout | int | 否 | 10 | 设置建立连接超时时间,单位为秒。 |
max_connections | int | 否 | 1024 | 设置连接池大小。 |
enable_crc | bool | 否 | True | 是否开启 CRC 数据校验。 |
max_retry_count | int | 否 | 3 | 请求失败最大重试次数。 |
dns_cache_time | int | 否 | 5 | DNS 缓存的有效期,单位:分钟。 |
proxy_host | str | 否 | None | 代理服务器的主机地址,当前只支持 HTTP 协议。 |
proxy_port | int | 否 | None | 代理服务器的端口号。 |
proxy_username | str | 否 | None | 连接代理服务器的用户名。 |
proxy_password | str | 否 | None | 连接代理服务器使用的用户密码。 |
is_custom_domain | bool | 否 | False | 是否为自定义域名。 |
high_latency_log_threshold | int | 否 | 100 | 大于 0 时,代表开启高延迟日志,单位:KB。默认为 100,当单次请求传输总速率低于该值且总请求耗时大于 500 毫秒时打印 WARN 级别日志。 |
socket_timeout | int | 否 | 30 | 连接建立成功后,单个请求的 Socket 读写超时时间。 |
credentials_provider | object | 否 | None | 通过 |