快速入门（Python SDK）--对象存储-火山引擎

文档中心

对象存储

Python

快速入门（Python SDK）

本文介绍如何通过 TOS Python SDK 来完成常见的操作，如创建桶、上传对象、下载对象和删除对象等。

注意事项

多进程场景下需要创建多个 TosClient，不能共享同一个 TosClient，否则会有多进程并发安全问题，可能会导致读写请求数据错乱。

安装和初始化

安装 python-devel

您需要安装 python-devel 包。
TOS Python SDK 依赖 crcmod 计算 CRC 校验码，而 crcmod 的 C 扩展模式依赖 python-devel 包中的 Python.h 文件。如果缺少 Python.h，crcmod 的 C 扩展模式安装失败，crcmod 会运行在纯 Python 模式，纯 Python 模式计算 CRC 性能远差于 C 扩展模式，会导致上传、下载等操作效率低下。

说明

如果开启 CRC 校验导致上传下载性能差，您可以关闭 CRC64 校验。

验证 crcmod 模式

进入 Python 环境，输入 import crcmod._crcfunext。

如果出现以下错误提示，则表明 crcmod 库的 C 扩展模式安装失败，crcmod 库是纯 Python 方式。原因是编译 crcmod 时，_crcfunext.so 依赖 Python.h 文件，而系统中缺少这个头文件，因此 _crcfunext.so 库生成失败。

Traceback (most recent call last):
File "<stdin>", line 1, in <module>
ImportError: No module named _crcfunext

如果没有出现错误提示，则表明 crcmod 库的 C 扩展模式安装成功。

如果出现错误，可以按照以下方式解决：

卸载 crcmod。
```
pip uninstall crcmod
```
安装 python-devel。
- 如果您是 Windows 和 Mac OS X 系统，在安装 Python 的时候会将 Python 依赖的头文件一并安装，因此您无需安装 python-devel。
- 如果您是 CentOS、RHEL、Fedora 系统，可以使用以下命令安装：
```
# Python2.x版本
yum install python-devel

# Python3.x版本
yum install python3-devel
```
- 如果您是 Debian、Ubuntu 系统，您可以使用以下命令安装：
```
# Python2.x版本
apt-get install python-dev

# Python3.x版本
apt-get install python3-dev
```
重新安装 crcmod。
```
pip install crcmod
```

客户端通用示例

以下代码是使用 TOS Python SDK 的通用代码模版。

import os
import tos

# 从环境变量获取 AK 和 SK 信息。
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"
bucket = "bucket-test"
key = "object-test"
data = "Hello world"

try:
    # 创建TosClientV2对象
    client = tos.TosClientV2(ak, sk, endpoint, region)
    # 调用接口请求TOS服务，例如上传对象
    resp = client.put_object(bucket, key, content=data)
    print('success, request id {}'.format(resp.request_id))
except tos.exceptions.TosClientError as e:
    # 操作失败，捕获客户端异常，一般情况为非法请求参数或网络异常
    print('fail with client error, message:{}, cause: {}'.format(e.message, e.cause))
except tos.exceptions.TosServerError as e:
    # 操作失败，捕获服务端异常，可从返回信息中获取详细错误信息
    print('fail with server error, code: {}'.format(e.code))
    # request id 可定位具体问题，强烈建议日志中保存
    print('error with request id: {}'.format(e.request_id))
    print('error with message: {}'.format(e.message))
    print('error with http code: {}'.format(e.status_code))
    print('error with ec: {}'.format(e.ec))
    print('error with request url: {}'.format(e.request_url))
except Exception as e:
    print('fail with unknown error: {}'.format(e))

创建桶

存储桶（Bucket）是 TOS 的全局唯一的命名空间，相当于数据的容器，用来储存对象数据。以下代码用于创建一个新存储桶 bucket-test。

import os
import tos

# 从环境变量获取 AK 和 SK 信息。
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"
bucket_name = "bucket-test"
key = "object-test"
data = "Hello world"

try:
    # 创建 TosClientV2 对象，对桶和对象的操作都通过 TosClientV2 实现
    client = tos.TosClientV2(ak, sk, endpoint, region)
    # 设置桶存储桶为私有读写权限
    client.create_bucket(bucket_name, acl=tos.ACLType.ACL_Private)
except tos.exceptions.TosClientError as e:
    # 操作失败，捕获客户端异常，一般情况为非法请求参数或网络异常
    print('fail with client error, message:{}, cause: {}'.format(e.message, e.cause))
except tos.exceptions.TosServerError as e:
    # 操作失败，捕获服务端异常，可从返回信息中获取详细错误信息
    print('fail with server error, code: {}'.format(e.code))
    # request id 可定位具体问题，强烈建议日志中保存
    print('error with request id: {}'.format(e.request_id))
    print('error with message: {}'.format(e.message))
    print('error with http code: {}'.format(e.status_code))
    print('error with ec: {}'.format(e.ec))
    print('error with request url: {}'.format(e.request_url))
except Exception as e:
    print('fail with unknown error: {}'.format(e))

说明

关于创建桶的更多信息，请参见创建桶。

上传对象

新建存储桶成功后，可以往存储桶中上传对象，以下代码将字符串上传到 TOS 桶 bucket-test 中。

import os
import tos

# 从环境变量获取 AK 和 SK 信息。
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"
bucket_name = "bucket-test"
object_key = "object-test"

try:
    client = tos.TosClientV2(ak, sk, endpoint, region)
    # 通过字符串方式添加 Object
    client.put_object(bucket_name, object_key, content='Hello World')
except tos.exceptions.TosClientError as e:
    # 操作失败，捕获客户端异常，一般情况为非法请求参数或网络异常
    print('fail with client error, message:{}, cause: {}'.format(e.message, e.cause))
except tos.exceptions.TosServerError as e:
    # 操作失败，捕获服务端异常，可从返回信息中获取详细错误信息
    print('fail with server error, code: {}'.format(e.code))
    # request id 可定位具体问题，强烈建议日志中保存
    print('error with request id: {}'.format(e.request_id))
    print('error with message: {}'.format(e.message))
    print('error with http code: {}'.format(e.status_code))
    print('error with ec: {}'.format(e.ec))
    print('error with request url: {}'.format(e.request_url))
except Exception as e:
    print('fail with unknown error: {}'.format(e))

说明

关于上传对象的更多示例链接，请参见上传对象。

下载对象

以下代码用于将指定的 TOS 对象下载到内存中。

import os
import tos

# 从环境变量获取 AK 和 SK 信息。
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"
bucket_name = "bucket-test"
object_key = "object-test"

try:
    # 创建 TosClientV2 对象，对桶和对象的操作都通过 TosClientV2 实现
    client = tos.TosClientV2(ak, sk, endpoint, region)
    # 下载对象到内存中
    object_stream = client.get_object(bucket_name, object_key)
    # object_stream 为迭代器可迭代读取数据
    # for content in object_stream:
    #     print(content)
    # 您也可调用 read()方法一次在内存中获取完整的数据
    print(object_stream.read())
except tos.exceptions.TosClientError as e:
    # 操作失败，捕获客户端异常，一般情况为非法请求参数或网络异常
    print('fail with client error, message:{}, cause: {}'.format(e.message, e.cause))
except tos.exceptions.TosServerError as e:
    # 操作失败，捕获服务端异常，可从返回信息中获取详细错误信息
    print('fail with server error, code: {}'.format(e.code))
    # request id 可定位具体问题，强烈建议日志中保存
    print('error with request id: {}'.format(e.request_id))
    print('error with message: {}'.format(e.message))
    print('error with http code: {}'.format(e.status_code))
    print('error with ec: {}'.format(e.ec))
    print('error with request url: {}'.format(e.request_url))
except Exception as e:
    print('fail with unknown error: {}'.format(e))

说明

关于下载对象的更多示例链接，请参见下载对象。

列举对象

以下代码用于列举指定桶 bucket-test 中的对象，最多可列举 2000 个。

import os
import tos

# 从环境变量获取 AK 和 SK 信息。
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"
bucket_name = "bucket-test"
object_key = "object-test"

try:
    # 创建 TosClientV2 对象，对桶和对象的操作都通过 TosClientV2 实现
    client = tos.TosClientV2(ak, sk, endpoint, region)
    # 默认单次列举最多1000个对象
    list_out_1 = client.list_objects(bucket_name)
    for ob in list_out_1.contents:
        print(ob.key)

    # 若未列举完对象，可设置可选参数marker继续列举
    if list_out_1.is_truncated:
        list_out_2 = client.list_objects(bucket_name, marker=list_out_1.next_marker)
        for ob in list_out_2.contents:
            print(ob.key)
except tos.exceptions.TosClientError as e:
    # 操作失败，捕获客户端异常，一般情况为非法请求参数或网络异常
    print('fail with client error, message:{}, cause: {}'.format(e.message, e.cause))
except tos.exceptions.TosServerError as e:
    # 操作失败，捕获服务端异常，可从返回信息中获取详细错误信息
    print('fail with server error, code: {}'.format(e.code))
    # request id 可定位具体问题，强烈建议日志中保存
    print('error with request id: {}'.format(e.request_id))
    print('error with message: {}'.format(e.message))
    print('error with http code: {}'.format(e.status_code))
    print('error with ec: {}'.format(e.ec))
    print('error with request url: {}'.format(e.request_url))
except Exception as e:
    print('fail with unknown error: {}'.format(e))

说明

关于列举对象的更多示例链接，请参见列举对象。

删除对象

以下代码用于删除指定桶 bucket-test 中的对象 object-test。

import os
import tos

# 从环境变量获取 AK 和 SK 信息。
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"
bucket_name = "bucket-test"
object_key = "object-test"

try:
    client = tos.TosClientV2(ak, sk, endpoint, region)
    # 从桶中删除对象
    client.delete_object(bucket_name, object_key)
except tos.exceptions.TosClientError as e:
    # 操作失败，捕获客户端异常，一般情况为非法请求参数或网络异常
    print('fail with client error, message:{}, cause: {}'.format(e.message, e.cause))
except tos.exceptions.TosServerError as e:
    # 操作失败，捕获服务端异常，可从返回信息中获取详细错误信息
    print('fail with server error, code: {}'.format(e.code))
    # request id 可定位具体问题，强烈建议日志中保存
    print('error with request id: {}'.format(e.request_id))
    print('error with message: {}'.format(e.message))
    print('error with http code: {}'.format(e.status_code))
    print('error with ec: {}'.format(e.ec))
    print('error with request url: {}'.format(e.request_url))
except Exception as e:
    print('fail with unknown error: {}'.format(e))

说明

关于删除对象的更多示例链接，请参见删除对象。

关闭 TosClient

TOS Python SDK 默认开启长连接，您创建多个 TosClient 实例访问 TOS 后，可使用以下代码关闭不再使用的 TosClient 实例，释放连接资源。

import os
import tos

# 从环境变量获取 AK 和 SK 信息。
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"

try:
    # 创建 TosClientV2 对象，对桶和对象的操作都通过 TosClientV2 实现
    client = tos.TosClientV2(ak, sk, endpoint, region)
    # 执行相关操作后，将不再使用的TosClient关闭
    client.close()
except tos.exceptions.TosClientError as e:
    # 操作失败，捕获客户端异常，一般情况为非法请求参数或网络异常
    print('fail with client error, message:{}, cause: {}'.format(e.message, e.cause))
except tos.exceptions.TosServerError as e:
    # 操作失败，捕获服务端异常，可从返回信息中获取详细错误信息
    print('fail with server error, code: {}'.format(e.code))
    # request id 可定位具体问题，强烈建议日志中保存
    print('error with request id: {}'.format(e.request_id))
    print('error with message: {}'.format(e.message))
    print('error with http code: {}'.format(e.status_code))
    print('error with ec: {}'.format(e.ec))
    print('error with request url: {}'.format(e.request_url))
except Exception as e:
    print('fail with unknown error: {}'.format(e))

最近更新时间：2025.03.05 11:20:56

这个页面对您有帮助吗？

有用

无用

对象存储

注意事项 #

安装和初始化 #

安装 python-devel #

验证 crcmod 模式 #

客户端通用示例 #

创建桶 #

上传对象 #

下载对象 #

列举对象 #

删除对象 #

关闭 TosClient #