You need to enable JavaScript to run this app.
导航

初始化客户端(Python SDK)

最近更新时间2024.02.04 18:30:55

首次发布时间2021.12.31 17:38:36

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

前提条件

配置长期访问凭证

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

  1. 打开终端并执行以下命令打开文件。
nano ~/.bash_profile
  1. 在文件末尾添加 AKSK 信息。
export TOS_ACCESS_KEY=AKTPYmI1Z****
export TOS_SECRET_KEY=T1dJM01UU****
  1. 保存文件并退出。
  2. 执行以下命令生效配置信息。
source ~/.bash_profile
  1. 执行以下命令验证配置信息。
echo $TOS_ACCESS_KEY
echo $TOS_SECRET_KEY

如果配置成功,则返回如下示例:

AKTPYmI1Z****
T1dJM01UU****

创建 TosClient

使用必选参数初始化

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

说明

  • Endpoint 为 TOS 对外服务的访问域名。TOS 支持的 Endpoint 信息,请参见访问域名 Endpoint
  • AKSK 信息可从环境变量获取,配置方式,请参见配置访问凭证
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

您可以通过 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)

初始化参数列表

初始化 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

是否为自定义域名。

high_latency_log_threshold

int

100

大于 0 时,代表开启高延迟日志,单位:KB。默认为 100,当单次请求传输总速率低于该值且总请求耗时大于 500 毫秒时打印 WARN 级别日志。

socket_timeout

int

30

连接建立成功后,单个请求的 Socket 读写超时时间。
单位:秒,默认为 30 秒。