You need to enable JavaScript to run this app.
导航
快速入门(Python SDK)
最近更新时间:2024.02.04 18:30:54首次发布时间:2021.12.31 17:38:35

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

安装和初始化

安装 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 扩展模式安装成功。

如果出现错误,可以按照以下方式解决:

  1. 卸载 crcmod。

    pip uninstall crcmod
    
  2. 安装 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
      
  3. 重新安装 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))