租户端 存储 对象存储（COS） SDK文档

快速入门

最近更新时间: 2024-10-17 17:10:00

下载与安装

相关资源

对象存储的 XML Python SDK 资源下载地址： XML Python SDK 。 演示示例 Demo 下载地址：XML Python Demo。

环境依赖

对象存储的 XML Python SDK 目前可以支持 Python 2.6、Python 2.7 以及 Python 3.x。

安装 SDK

安装 SDK 有三种安装方式：pip 安装、手动安装和离线安装。

  • 使用 pip 安装（推荐）
pip install -U cos-python-sdk-v5
  • 手动安装 从 XML Python SDK 下载源码，通过 setup 手动安装，执行以下命令。
python setup.py install
  • 离线安装
# 在有外网的机器下运行如下命令
mkdir cos-python-sdk-packages
pip download cos-python-sdk-v5 -d cos-python-sdk-packages
tar -czvf cos-python-sdk-packages.tar.gz cos-python-sdk-packages
# 将安装包拷贝到没有外网的机器后运行如下命令
# 请确保两台机器的 python 版本保持一致，否则会出现安装失败的情况
tar -xzvf cos-python-sdk-packages.tar.gz
pip install cos-python-sdk-v5 --no-index -f cos-python-sdk-packages

术语解释

名称 描述
APPID 开发者访问 COS 服务时拥有的用户维度唯一资源标识，用以标识资源
SecretId 开发者拥有的项目身份识别 ID，用以身份认证
SecretKey 开发者拥有的项目身份密钥
Bucket COS 中用于存储数据的容器
Object COS 中存储的具体文件，是存储的基本实体
Region 域名中的地域信息
Endpoint Endpoint 由 Region 和域名组成，具体格式为： "."，其中 Domain 为自定义的域名。
在控制台创建 Bucket 时，可以看到对应的访问地址为："."，Bucket 后面的部分即为 Endpoint。
ACL 访问控制列表（Access Control List），是指特定 Bucket 或 Object 的访问控制信息列表
CORS 跨域资源共享（Cross-Origin Resource Sharing）， 指发起请求的资源所在域不同于该请求所指向资源所在的域的 HTTP 请求
Multipart Uploads 分块上传，COS 服务为上传文件提供的一种分块上传模式

开始使用

下面为您介绍如何使用 COS Python SDK 完成一个基础操作，如初始化客户端、创建存储桶、查询存储桶列表、上传对象、查询对象列表、下载对象和删除对象。

初始化

请参考以下示例代码：

# Bucket 由 BucketName-APPID 组成
# 1. 设置用户配置, 包括 SecretId，SecretKey 以及 Region
from qcloud_cos import CosConfig
from qcloud_cos import CosS3Client
from qcloud_cos.cos_comm import format_region

secret_id = 'COS_SECRETID'    # 替换为用户的 SecretId
secret_key = 'COS_SECRETKEY'  # 替换为用户的 SecretKey

region = "REGION"             # 替换为用户的 Region
domain = "DOMAIN.COM"         # 替换为用户的 Domain
endpoint = "{}.{}".format(format_region(region), domain)
                              # 通过 Region 和 Domain 生成 Endpoint, 注意使用 format_region

token = None                  # 使用临时密钥需要传入 Token，默认为空，可不填
scheme = 'http'               # 指定使用 http/https 协议来访问 COS，默认为 https
config = CosConfig(Scheme=scheme, Secret_id=secret_id, Secret_key=secret_key, Endpoint=endpoint, Token=token)

# 2. 获取客户端对象
client = CosS3Client(config)

# 参照下文的描述。或者参照 Demo 程序，详见 https://github.com/tencentyun/cos-python-sdk-v5/blob/master/qcloud_cos/demo.py

创建存储桶

response = client.create_bucket(
    Bucket='examplebucket-1250000000'
)

上传对象

#### 文件流简单上传
# 强烈建议您以二进制模式(binary mode)打开文件,否则可能会导致错误
with open('picture.jpg', 'rb') as fp:
    response = client.put_object(
        Bucket='examplebucket-1250000000',
        Body=fp,
        Key='picture.jpg',
        StorageClass='STANDARD',
        EnableMD5=False
    )
print(response['ETag'])

#### 字节流简单上传
response = client.put_object(
    Bucket='examplebucket-1250000000',
    Body=b'bytes',
    Key='picture.jpg',
    EnableMD5=False
)
print(response['ETag'])


#### chunk 简单上传
import requests
stream = requests.get('/64296333127741440/64296342553391104')

# 网络流将以 Transfer-Encoding:chunked 的方式传输到 COS
response = client.put_object(
    Bucket='examplebucket-1250000000',
    Body=stream,
    Key='picture.jpg'
)
print(response['ETag'])

#### 高级上传接口（推荐）
根据文件大小自动选择简单上传或分块上传，分块上传具备断点续传功能。
response = client.upload_file(
    Bucket='examplebucket-1250000000',
    LocalFilePath='local.txt',
    Key='picture.jpg',
    PartSize=1,
    MAXThread=10,
    EnableMD5=False
)
print(response['ETag'])

查询对象列表

response = client.list_objects(
    Bucket='examplebucket-1250000000',
    Prefix='folder1'
)

单次调用 list_objects 接口一次只能查询1000个对象，如需要查询所有的对象，则需要循环调用。

marker = ""
while True:
    response = client.list_objects(
        Bucket='examplebucket-1250000000',
        Prefix='folder1',
        Marker=marker
    )
    print(response['Contents'])
    if response['IsTruncated'] == 'false':
        break 
    marker = response['NextMarker']

下载对象

####  获取文件到本地
response = client.get_object(
    Bucket='examplebucket-1250000000',
    Key='picture.jpg',
)
response['Body'].get_stream_to_file('output.txt')

#### 获取文件流
response = client.get_object(
    Bucket='examplebucket-1250000000',
    Key='picture.jpg',
)
fp = response['Body'].get_raw_stream()
print(fp.read(2))

#### 设置 Response HTTP 头部
response = client.get_object(
    Bucket='examplebucket-1250000000',
    Key='picture.jpg',
    ResponseContentType='text/html; charset=utf-8'
)
print response['Content-Type']
fp = response['Body'].get_raw_stream()
print(fp.read(2))

#### 指定下载范围
response = client.get_object(
    Bucket='examplebucket-1250000000',
    Key='picture.jpg',
    Range='bytes=0-10'
)
fp = response['Body'].get_raw_stream()
print(fp.read())

删除对象

# 删除object
## deleteObject
response = client.delete_object(
    Bucket='examplebucket-1250000000',
    Key='exampleobject'
)

# 删除多个object
## deleteObjects
response = client.delete_objects(
    Bucket='examplebucket-1250000000',
    Delete={
        'Object': [
            {
                'Key': 'exampleobject1',
            },
            {
                'Key': 'exampleobject2',
            },
        ],
        'Quiet': 'true'|'false'
    }
)