文档中心

对象存储

请输入

Python

初始化客户端（Python SDK）

TosClient 提供了一系列接口用与 TOS 服务进行交互，以管理存储桶和对象等 TOS 服务上的资源。可通过AccessKey/SecretKey、STS (Security Token Service）等方式初始化 TosClient 。在初始化时，可设置建立连接超时时间、超时重试次数和最大空闲连接数量等可选参数。本文介绍如何初始化 TOS Python SDK。

前提条件

安装 SDK

获取 AKSK 信息

注意事项

单进程多线程场景建议使用一个 TosClient，避免重复初始化 TosClient；多进程场景下需要创建多个 TosClient，不能共享同一个 TosClient，否则会有多进程并发安全问题，可能会导致读写请求数据错乱。

配置长期访问凭证

初始化 SDK 前，您需要先配置长期访问凭证。本章节介绍不同操作系统下配置长期访问凭证的操作步骤。

macOS

Linux

Windows

打开终端并执行以下命令打开文件。

在文件末尾添加 AKSK 信息。

保存文件并退出。

执行以下命令生效配置信息。

执行以下命令验证配置信息。

如果配置成功，则返回如下示例：

创建 TosClient

使用必选参数初始化

以下代码用于使用 TOS 域名初始化。

说明

Endpoint 为 TOS 对外服务的访问域名。TOS 支持的 Endpoint 信息，请参见访问域名 Endpoint。

AKSK 信息可从环境变量获取，配置方式，请参见配置访问凭证。

使用可选参数

以下代码用于使用可选参数初始化。

常见配置场景

配置 STS

您可以通过 STS 服务向其他用户颁发临时访问凭证，在凭证有效期内，用户可访问您的 TOS 资源，而无需透露您的长期密钥，保障您 TOS 资源的安全性。

说明

您可以通过 STS 服务的 AssumeRole 接口获取临时访问凭证，临时访问凭证中包含安全密钥（AccessKeyId、SecretAccessKey）和安全令牌（SessionToken），后续您可以使用该信息访问 TOS 服务。关于搭建 STS 服务的基本操作，请参见使用 STS 临时 AK/SK+Token 访问火山引擎 TOS。

以下代码用于使用 STS 初始化。

配置超时机制

您可以在初始化 TosClient 时，通过添加可选参数配置网络请求的超时时间，目前 TOS Python SDK支持配置连接超时 connection_time 和请求超时 socket_timeout。

以下代码用于初始化 TosClient 时配置超时时间。

配置重试策略

网络波动或短期 TOS 服务异常（返回 500 状态码）等场景会导致调用 TOS 服务失败，针对此问题 Python SDK 内部提供了重试机制，幂等操作的接口在失败后会使用指数避让策略进行重试，非幂接口则直接抛出对应异常。您可以在初始化 TosClient 时，添加可选参数配置重试次数。

配置数据校验

对象上传和下载时 TOS 返回对象的 CRC 值，SDK 验证本地计算的 CRC 和 TOS 返回的 CRC 是否相等，校验上传和下载数据的完整性。为确保上传和下载过程中数据的完整性，SDK 默认开启 CRC 数据校验，您可以在初始化 TosClient 时，添加可选参数关闭 CRC 校验功能。

警告

强烈建议不要关闭 CRC 数据校验功能。若关闭此功能，TOS 不保障上传和下载过程中数据完整性。

配置代理服务器

TOS Python SDK 支持配置代理服务器的方式访问 TOS 服务，您可以在初始化 TosClient 时，添加可选参数配置代理服务器。

说明

目前只支持 HTTP 协议代理。

配置连接池

TOS Python SDK 支持连接池配置，您可以在初始化 TosClient 时，添加可选参数配置连接池大小。

说明

连接池大小默认配置为 1024，单进程多线程场景建议您使用一个 TosClient 实例。

设置自定义域名

TOS Python SDK 支持设置自定义域名，您可以在初始化 TosClient 时，传入自定义域名作为 Host。指定自定义域名后，使用 SDK 接口中无需传入 Bucket 。

说明

使用自定义域名前需要在服务端配置自定义域名，详情请参见设置自定义域名。

配置 ECS 免密登录

免密登录指无需指定密钥，而是通过安全令牌服务（STS）提供的临时安全凭证验证身份，完成鉴权。该方式无需透露长期 AccessKey，可以保证账号下的密钥安全。

TOS Python SDK 支持设置 ECS 免密登录，您可以在初始化 TosClient 时，添加 credentials_provider 参数。

说明

在使用 ECS 免密登录之前，需要先绑定 IAM 角色到 ECS，详细信息请参见 ECS绑定 IAM 角色，并使用角色名作为参数初始化TosClient。

初始化参数列表

初始化 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 缓存的有效期，单位：分钟。默认为 0，小于等于 0 时代表关闭 DNS 缓存。
proxy_host	str	否	None	代理服务器的主机地址，当前只支持 HTTP 协议。
proxy_port	int	否	None	代理服务器的端口号。
proxy_username	str	否	None	连接代理服务器的用户名。
proxy_password	str	否	None	连接代理服务器使用的用户密码。
is_custom_domain	bool	否	False	是否将桶名拼接到 Endpoint 前，通过虚拟主机域名的方式访问 TOS，取值说明如下： true：不拼接。 false：拼接。默认为 false。说明通过自定义域名访问 TOS 时，需要设置 isCustomDomain 为 true。
high_latency_log_threshold	int	否	100	大于 0 时，代表开启高延迟日志，单位：KB。默认为 100，当单次请求传输总速率低于该值且总请求耗时大于 500 毫秒时打印 WARN 级别日志。
socket_timeout	int	否	30	连接建立成功后，单个请求的 Socket 读写超时时间。单位：秒，默认为 30 秒。
credentials_provider	object	否	None	通过 credentials_provider 实现永久访问密钥、临时访问密钥、ECS 免密登录、环境变量获取访问密钥等方式。

最近更新时间：2025.12.11 10:10:24

这个页面对您有帮助吗？

有用

无用