You need to enable JavaScript to run this app.
导航
对象存储
  • 文档首页
    • /
  • 对象存储

初始化客户端（Python SDK）

最近更新时间：2024.03.06 16:20:26

首次发布时间：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)

配置 ECS 免密登录

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 缓存的有效期，单位：分钟。
默认为 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 秒。

credentials_provider

object

否

None

通过 credentials_provider 实现永久访问密钥、临时访问密钥、ECS 免密登录、环境变量获取访问密钥等方式。