控制台指南

最佳实践

开发者指南

API 文档

SDK 文档

对象操作

最近更新时间:2021-05-14 15:18:50

简介

本文档提供关于对象的简单操作、分块操作等其他操作相关的 API 概览以及 SDK 示例代码。

简单操作

API 操作名 操作描述
GET Bucket(List Object) 查询对象列表 查询存储桶下的部分或者全部对象
GET Bucket Object Versions 查询对象及其历史版本列表 查询存储桶下的部分或者全部对象及其历史版本信息
PUT Object 简单上传对象 上传一个对象至存储桶
HEAD Object 查询对象元数据 查询对象的元数据信息
GET Object 下载对象 下载一个对象至本地
PUT Object - Copy 设置对象复制 复制对象到目标路径
DELETE Object 删除单个对象 在存储桶中删除指定对象
DELETE Multiple Objects 删除多个对象 在存储桶中批量删除指定对象
POST Object restore 恢复归档对象 将归档类型的对象取回访问
SELECT Object content 检索对象内容 从指定对象中检索内容

分块操作

API 操作名 操作描述
List Multipart Uploads 查询分块上传 查询正在进行中的分块上传信息
Initiate Multipart Upload 初始化分块上传 初始化分块上传任务
Upload Part 上传分块 分块上传文件
Upload Part - Copy 复制分块 将其他对象复制为一个分块
List Parts 查询已上传块 查询特定分块上传操作中的已上传的块
Complete Multipart Upload 完成分块上传 完成整个文件的分块上传
Abort Multipart Upload 终止分块上传 终止一个分块上传操作并删除已上传的块

简单操作

查询对象列表

功能说明

查询存储桶下的部分或者全部对象。

方法原型

list_objects(Bucket, Delimiter="", Marker="", MaxKeys=1000, Prefix="", EncodingType="", **kwargs)

请求示例

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

全部参数请求示例

response = client.list_objects(
   Bucket='examplebucket-1250000000',
   Prefix='string',
   Delimiter='/',
   Marker='string',
   MaxKeys=100,
   EncodingType='url'
)

参数说明

参数名称 参数描述 类型 是否必填
Bucket 存储桶名称,由 BucketName-APPID 构成 String
Prefix 默认为空,对对象的对象键进行筛选,匹配 prefix 为前缀的对象 String
Delimiter 默认为空,设置分隔符,例如设置 / 来模拟文件夹 String
Marker 默认以 UTF-8 二进制顺序列出条目,标记返回对象的 list 的起点位置 String
MaxKeys 最多返回的对象数量,默认为最大的1000 Int
EncodingType 默认不编码,规定返回值的编码方式,可选值:url String

返回结果说明

获取对象的元信息,类型为 dict:

{
  'MaxKeys': '1000', 
  'Prefix': 'string',
  'Delimiter': 'string',
  'Marker': 'string',
  'NextMarker': 'string',
  'Name': 'examplebucket-1250000000',  
  'IsTruncated': 'false'|'true',
  'EncodingType': 'url',
  'Contents':[
      {
          'ETag': '"a5b2e1cfb08d10f6523f7e6fbf3643d5"', 
          'StorageClass': 'STANDARD', 
          'Key': 'exampleobject',
          'Owner': {
              'DisplayName': '1250000000',
              'ID': '1250000000'
          }, 
          'LastModified': '2017-08-08T09:43:35.000Z', 
          'Size': '23'
      },
  ],
  'CommonPrefixes':[
      {
          'Prefix': 'string'
      },
  ],
}
参数名称 参数描述 类型
MaxKeys 最多返回的对象数量,默认为最大的1000 String
Prefix 默认为空,匹配 Prefix 为前缀的对象 String
Delimiter 默认为空,设置分隔符,例如设置 / 来模拟文件夹 String
Marker 默认以 UTF-8 二进制顺序列出条目,标记返回对象的 list 的起点位置 String
NextMarker 当 IsTruncated 为 true 时,标记下一次返回对象的 list 的起点位置 String
Name 存储桶名称,由 BucketName-APPID 构成 String
IsTruncated 表示返回的对象是否被截断 String
EncodingType 默认不编码,规定返回值的编码方式,可选值:url String
Contents 包含所有对象元数据的 list,包括 'ETag','StorageClass','Key','Owner','LastModified','Size' 等信息 List
CommonPrefixes 所有以 Prefix 开头,以 Delimiter 结尾的对象被归到同一类 List

查询对象及其历史版本列表

功能说明

查询存储桶下的部分或者全部对象及其历史版本信息。

方法原型

list_objects_versions(Bucket, Prefix="", Delimiter="", KeyMarker="", VersionIdMarker="", MaxKeys=1000, EncodingType="", **kwargs)

请求示例

response = client.list_objects_versions(
   Bucket='examplebucket-1250000000',
   Prefix='string'
)

全部参数请求示例

response = client.list_objects_versions(
   Bucket='examplebucket-1250000000',
   Prefix='string',
   Delimiter='/',
   KeyMarker='string',
   VersionIdMarker='string',
   MaxKeys=100,
   EncodingType='url'
)

参数说明

参数名称 参数描述 类型 是否必填
Bucket 存储桶名称,由 BucketName-APPID 构成 String
Prefix 默认为空,对对象的对象键进行筛选,匹配 prefix 为前缀的对象 String
Delimiter 默认为空,设置分隔符,例如设置 / 来模拟文件夹 String
KeyMarker 默认以 UTF-8 二进制顺序列出条目,标记返回对象的 list 的 Key 的起点位置 String
VersionIdMarker 默认以 UTF-8 二进制顺序列出条目,标记返回对象的 list 的 VersionId 的起点位置 String
MaxKeys 最多返回的对象数量,默认为最大的1000 Int
EncodingType 默认不编码,规定返回值的编码方式,可选值:url String

返回结果说明

获取对象的元信息,类型为 dict:

{
  'MaxKeys': '1000', 
  'Prefix': 'string',
  'Delimiter': 'string',
  'KeyMarker': 'string',
  'VersionIdMarker': 'string',
  'NextKeyMarker': 'string',
  'NextVersionIdMarker': 'string',
  'Name': 'examplebucket-1250000000',  
  'IsTruncated': 'false'|'true',
  'EncodingType': 'url',
  'Version':[
      {
          'ETag': '"a5b2e1cfb08d10f6523f7e6fbf3643d5"', 
          'StorageClass': 'STANDARD', 
          'Key': 'exampleobject',
          'VersionId': 'string',
          'IsLatest': 'true'|'false',
          'Owner': {
              'DisplayName': '1250000000',
              'ID': '1250000000'
          }, 
          'LastModified': '2017-08-08T09:43:35.000Z', 
          'Size': '23'
      },
  ],
  'DeleteMarker': [
      {
          'Key': 'exampleobject',
          'VersionId': 'string',
          'IsLatest': 'true'|'false',
          'Owner': {
              'DisplayName': '1250000000',
              'ID': '1250000000'
          },
          'LastModified': '2017-08-08T09:43:35.000Z'
      },
  ],
  'CommonPrefixes':[
      {
          'Prefix': 'string'
      },
  ],
}
参数名称 参数描述 类型
MaxKeys 最多返回的对象数量,默认为最大的1000 String
Prefix 默认为空,匹配 Prefix 为前缀的对象 String
Delimiter 默认为空,设置分隔符,例如设置 / 来模拟文件夹 String
KeyMarker 默认以 UTF-8 二进制顺序列出条目,标记返回对象的 list 的 Key 的起点位置 String
VersionIdMarker 默认以 UTF-8 二进制顺序列出条目,标记返回对象的 list 的 VersionId 的起点位置 String
NextKeyMarker 当 IsTruncated 为 true 时,标记下一次返回对象的 list 的 Key 的起点位置 String
NextVersionIdMarker 当 IsTruncated 为 true 时,标记下一次返回对象的 list 的 VersionId 的起点位置 String
Name 存储桶名称,由 BucketName-APPID 构成 String
IsTruncated 表示返回的对象是否被截断 String
EncodingType 默认不编码,规定返回值的编码方式,可选值:url String
Version 包含所有多个版本对象元数据的 list,包括 'ETag','StorageClass','Key','VersionId','IsLatest','Owner','LastModified','Size' 等信息 List
DeleteMarker 包含所有delete marker 对象元数据的 list,包括 'Key','VersionId','IsLatest','Owner','LastModified' 等信息 List
CommonPrefixes 所有以 Prefix 开头,以 Delimiter 结尾的对象被归到同一类 List

简单上传对象

功能说明

上传一个对象至存储桶(PUT Object)。

方法原型

put_object(Bucket, Body, Key, **kwargs)

请求示例1:简单文件上传

# -*- coding=utf-8
from qcloud_cos import CosConfig
from qcloud_cos import CosS3Client
from qcloud_cos import CosServiceError
from qcloud_cos import CosClientError
import sys
import logging

logging.basicConfig(level=logging.INFO, stream=sys.stdout)

# 设置用户属性, 包括 secret_id, secret_key, region
# APPID 已在配置中移除,请在参数 Bucket 中带上 APPID。Bucket 由 BucketName-APPID 组成
secret_id = 'secret_id'     # 替换为用户的 secret_id
secret_key = 'secret_key'     # 替换为用户的 secret_key
region = 'ap-beijing'    # 替换为用户的 region
token = None               # 使用临时密钥需要传入 Token,默认为空,可不填
config = CosConfig(Region=region, SecretId=secret_id, SecretKey=secret_key, Token=token)  # 获取配置对象
client = CosS3Client(config)
# 文件流 简单上传
file_name = 'test.txt'
with open('test.txt', 'rb') as fp:
   response = client.put_object(
       Bucket='examplebucket-1250000000',  # Bucket 由 BucketName-APPID 组成
       Body=fp,
       Key=file_name,
       StorageClass='STANDARD',
       ContentType='text/html; charset=utf-8'
   )
   print(response['ETag'])
# 字节流 简单上传
response = client.put_object(
   Bucket='examplebucket-1250000000',
   Body=b'abcdefg',
   Key=file_name
)
print(response['ETag'])
# 本地路径 简单上传
response = client.put_object_from_local_file(
   Bucket='examplebucket-1250000000',
   LocalFilePath='local.txt',
   Key=file_name,
)
print(response['ETag'])
# 设置 HTTP 头部 简单上传
response = client.put_object(
   Bucket='examplebucket-1250000000',
   Body=b'test',
   Key=file_name,
   ContentType='text/html; charset=utf-8'
)
print(response['ETag'])
# 设置自定义头部 简单上传
response = client.put_object(
   Bucket='examplebucket-1250000000',
   Body=b'test',
   Key=file_name,
   Metadata={
       'x-cos-meta-key1': 'value1',
       'x-cos-meta-key2': 'value2'
   }
)
print(response['ETag'])

# 创建目录
# 对象存储中,目录是特殊的路径以‘/’结尾的 object。调用 Put Object 接口即可
try:
   dir_to_create='path/to/create/dir/'
   response = client.put_object(
       Bucket=bucket,
       Key=dir_to_create,
       Body=b'',
   )
   print(response)
except CosServiceError as e:
   print(e.get_status_code())

请求示例2:上传到指定的目录

#上传由 '/' 分隔的对象名,自动创建包含文件的文件夹。想要在此文件夹中添加新文件时,只需要在上传文件至 COS 时,将 Key 填写为此目录前缀即可。
dir_name = 'path/to/dir/'
file_name = 'test.txt'
object_key = dir_name + file_name
with open('test.txt', 'rb') as fp:
  response = client.put_object(
      Bucket='examplebucket-1250000000',  # Bucket 由 BucketName-APPID 组成
      Body=fp,
      Key=object_key,
      StorageClass='STANDARD',
      ContentType='text/html; charset=utf-8'
  )
  print(response['ETag'])

全部参数请求示例

response = client.put_object(
   Bucket='examplebucket-1250000000',
   Body=b'bytes'|file,
   Key='exampleobject',
   EnableMD5=False|True,
   ACL='private'|'public-read',  # 请慎用此参数,否则会达到1000条 ACL 上限
   GrantFullControl='string',
   GrantRead='string',
   StorageClass='STANDARD'|'STANDARD_IA'|'ARCHIVE',
   Expires='string',
   CacheControl='string',
   ContentType='string',
   ContentDisposition='string',
   ContentEncoding='string',
   ContentLanguage='string',
   ContentLength='123',
   ContentMD5='string',
   Metadata={
       'x-cos-meta-key1': 'value1',
       'x-cos-meta-key2': 'value2'
   },
   TrafficLimit='1048576'
)

参数说明

参数名称 参数描述 类型 是否必填
Bucket 存储桶名称,由 BucketName-APPID 构成 String
Body 上传对象的内容,可以为文件流或字节流 file/bytes
Key 对象键(Key)是对象在存储桶中的唯一标识。例如,在对象的访问域名 examplebucket-1250000000.cos.ap-guangzhou.myqcloud.com/doc/pic.jpg 中,对象键为 doc/pic.jpg String
EnableMD5 是否需要 SDK 计算 Content-MD5,默认关闭,打开后将增加上传耗时 Bool
ACL 设置对象的 ACL,例如 'private','public-read' String
GrantFullControl 赋予被授权者所有的权限,格式为 id="OwnerUin" String
GrantRead 赋予被授权者读的权限,格式为 id="OwnerUin" String
StorageClass 设置对象的存储类型,STANDARD,STANDARD_IA,ARCHIVE。默认值为 STANDARD。更多存储类型,请参见 存储类型概述 String
Expires 设置 Expires String
CacheControl 缓存策略,设置 Cache-Control String
ContentType 内容类型,设置 Content-Type String
ContentDisposition 对象名称,设置 Content-Disposition String
ContentEncoding 编码格式,设置 Content-Encoding String
ContentLanguage 语言类型,设置 Content-Language String
ContentLength 设置传输长度 String
ContentMD5 设置上传对象的 MD5 值用于校验 String
Metadata 用户自定义的对象元数据, 必须以 x-cos-meta 开头,否则会被忽略 Dict
TrafficLimit 单链接限速的值,单位为bit/s,限速值设置范围为819200 - 838860800,即100KB/s - 100MB/s String

返回结果说明

上传对象的属性,类型为 dict:

{
  'ETag': 'string',
  'x-cos-version-id': 'string'
}
参数名称 参数描述 类型
ETag 上传对象的 MD5 值 String
x-cos-version-id 开启版本控制后,对象的版本号 String

查询对象元数据

功能说明

查询对象的元数据信息(HEAD Object)。

方法原型

head_object(Bucket, Key, **kwargs)

请求示例

response = client.head_object(
   Bucket='examplebucket-1250000000',
   Key='exampleobject'
)

全部请求参数示例

response = client.head_object(
  Bucket='examplebucket-1250000000',
  Key='exampleobject',
  VersionId='string',
  IfModifiedSince='Wed, 28 Oct 2014 20:30:00 GMT',
)

参数说明

参数名称 参数描述 类型 是否必填
Bucket Bucket 名称,由 BucketName-APPID 构成 String
Key 对象键(Key)是对象在存储桶中的唯一标识。例如,在对象的访问域名 examplebucket-1250000000.cos.ap-guangzhou.myqcloud.com/doc/pic.jpg 中,对象键为 doc/pic.jpg String
VersionId 开启版本控制后,指定对象的具体版本 String
IfModifiedSince 在指定时间后被修改才返回,时间格式为 GMT String

返回结果说明

获取对象的元信息,类型为 dict:

{
  'ETag': '"9a4802d5c99dafe1c04da0a8e7e166bf"',
  'Last-Modified': 'Wed, 28 Oct 2014 20:30:00 GMT',
  'Cache-Control': 'max-age=1000000',
  'Content-Type': 'application/octet-stream',
  'Content-Disposition': 'attachment; filename="filename.jpg"',
  'Content-Encoding': 'gzip',
  'Content-Language': 'zh-cn',
  'Content-Length': '16807',
  'Expires': 'Wed, 28 Oct 2019 20:30:00 GMT',
  'x-cos-meta-test': 'test',
  'x-cos-version-id': 'MTg0NDUxODMzMTMwMDM2Njc1ODA',
  'x-cos-request-id': 'NTg3NzQ3ZmVfYmRjMzVfMzE5N182NzczMQ=='
}
参数名称 参数描述 类型
ETag 分块上传时,该值不是对象内容的 MD5 校验值,仅能用于检查对象唯一性 String
Last-Modified 对象最后修改时间 String
Cache-Control 缓存策略, HTTP 标准头部 String
Content-Type 内容类型,HTTP 标准头部 String
Content-Disposition 文件名称,HTTP 标准头部 String
Content-Encoding 编码格式,HTTP 标准头部 String
Content-Language 语言类型,HTTP 标准头部 String
Content-Length 对象大小 String
Expires 缓存过期时间, HTTP 标准头部 String
x-cos-meta-* 用户自定义的对象元数据, 必须以 x-cos-meta 开头,否则会被忽略 String
x-cos-version-id 开启版本控制后,对象的版本号 String

下载对象

功能说明

下载一个对象到本地(GET Object)。

方法原型

get_object(Bucket, Key, **kwargs)

请求示例

response = client.get_object(
   Bucket='examplebucket-1250000000',
   Key='exampleobject'
)
response['Body'].get_stream_to_file('exampleobject')

全部参数请求示例

response = client.get_object(
   Bucket='examplebucket-1250000000',
   Key='exampleobject',
   Range='string',
   IfMatch='"9a4802d5c99dafe1c04da0a8e7e166bf"',
   IfModifiedSince='Wed, 28 Oct 2014 20:30:00 GMT',
   IfNoneMatch='"9a4802d5c99dafe1c04da0a8e7e166bf"',
   IfUnmodifiedSince='Wed, 28 Oct 2014 20:30:00 GMT',
   ResponseCacheControl='string',
   ResponseContentDisposition='string',
   ResponseContentEncoding='string',
   ResponseContentLanguage='string',
   ResponseContentType='string',
   ResponseExpires='string',
   VersionId='string',
   TrafficLimit='819200'
)

参数说明

参数名称 参数描述 类型 是否必填
Bucket 存储桶名称,由 BucketName-APPID 构成 String
Key 对象键(Key)是对象在存储桶中的唯一标识。例如,在对象的访问域名 examplebucket-1250000000.cos.ap-guangzhou.myqcloud.com/doc/pic.jpg 中,对象键为 doc/pic.jpg String
Range 设置下载对象的范围,格式为 bytes=first-last String
IfMatch ETag 与指定的内容一致时才返回 String
IfModifiedSince 在指定时间后被修改才返回,时间格式为 GMT String
IfNoneMatch ETag 与指定的内容不一致才返回 String
IfUnmodifiedSince 对象修改时间早于或等于指定时间才返回,时间格式为 GMT String
ResponseCacheControl 设置响应头部 Cache-Control String
ResponseContentDisposition 设置响应头部 Content-Disposition String
ResponseContentEncoding 设置响应头部 Content-Encoding String
ResponseContentLanguage 设置响应头部 Content-Language String
ResponseContentType 设置响应头部 Content-Type String
ResponseExpires 设置响应头部 Expires String
VersionId 指定下载对象的版本 String
TrafficLimit 单链接限速的值,单位为bit/s,限速值设置范围为819200 - 838860800,即100KB/s - 100MB/s,高级接口限制的是单线程的速度 String

返回结果说明

下载对象的 Body 和元信息,类型为 dict:

{
  'Body': StreamBody(),
  'ETag': '"9a4802d5c99dafe1c04da0a8e7e166bf"',
  'Last-Modified': 'Wed, 28 Oct 2014 20:30:00 GMT',
  'Accept-Ranges': 'bytes',
  'Content-Range': 'bytes 0-16086/16087',
  'Cache-Control': 'max-age=1000000',
  'Content-Type': 'application/octet-stream',
  'Content-Disposition': 'attachment; filename="filename.jpg"',
  'Content-Encoding': 'gzip',
  'Content-Language': 'zh-cn',
  'Content-Length': '16807',
  'Expires': 'Wed, 28 Oct 2019 20:30:00 GMT',
  'x-cos-meta-test': 'test',
  'x-cos-version-id': 'MTg0NDUxODMzMTMwMDM2Njc1ODA',
  'x-cos-request-id': 'NTg3NzQ3ZmVfYmRjMzVfMzE5N182NzczMQ=='
}
参数名称 参数描述 类型
Body 下载对象的内容,get_raw_stream() 方法可以得到一个文件流,get_stream_to_file(local_file_path) 方法可以将对象内容下载到指定本地文件中 StreamBody
ETag 对象的 MD5 值 String
Last-Modified 对象最后修改时间 String
Accept-Ranges 范围单位, HTTP 标准头部 String
Content-Range 内容范围, HTTP 标准头部 String
Cache-Control 缓存策略, HTTP 标准头部 String
Content-Type 内容类型,HTTP 标准头部 String
Content-Disposition 文件名称,HTTP 标准头部 String
Content-Encoding 编码格式,HTTP 标准头部 String
Content-Language 语言类型,HTTP 标准头部 String
Content-Length 对象大小 String
Expires 缓存过期时间, HTTP 标准头部 String
x-cos-meta-* 用户自定义的对象元数据, 必须以 x-cos-meta 开头,否则会被忽略 String
x-cos-version-id 开启版本控制后,对象的版本号 String

设置对象复制

功能说明

复制文件到目标路径(PUT Object - Copy)。

方法原型

copy_object(Bucket, Key, CopySource, CopyStatus='Copy', **kwargs)

请求示例

response = client.copy_object(
   Bucket='examplebucket-1250000000',
   Key='exampleobject',
   CopySource={
       'Bucket': 'sourcebucket-1250000000', 
       'Key': 'exampleobject', 
       'Region': 'ap-guangzhou'
   }
)

全部参数请求示例

response = client.copy_object(
  Bucket='examplebucket-1250000000',
  Key='exampleobject',
  CopySource={
      'Bucket': 'sourcebucket-1250000000', 
      'Key': 'exampleobject', 
      'Region': 'ap-guangzhou',
      'VesionId': 'string'
  },
  CopyStatus='Copy'|'Replaced',
  ACL='private'|'public-read',
  GrantFullControl='string',
  GrantRead='string',
  StorageClass='STANDARD'|'STANDARD_IA',
  Expires='string',
  CacheControl='string',
  ContentType='string',
  ContentDisposition='string',
  ContentEncoding='string',
  ContentLanguage='string',
  Metadata={
      'x-cos-meta-key1': 'value1',
      'x-cos-meta-key2': 'value2'
  }
)

参数说明

参数名称 参数描述 类型 是否必填
Bucket 存储桶名称,由 BucketName-APPID 构成 String
Key 对象键(Key)是对象在存储桶中的唯一标识。例如,在对象的访问域名 examplebucket-1250000000.cos.ap-guangzhou.myqcloud.com/doc/pic.jpg 中,对象键为 doc/pic.jpg String
CopySource 描述拷贝源对象的路径,包含 Bucket、Key、Region、VersionId Dict
CopyStatus 可选值为 Copy、Replaced,设置为 Copy 时,忽略设置的用户元数据信息直接复制,设置为 Replaced 时,按设置的元信息修改元数据,当目标路径和源路径一样时,必须设置为 Replaced String
ACL 设置对象的 ACL,如 private,public-read String
GrantFullControl 赋予指定账户对对象的所有权限,格式为 id="OwnerUin" String
GrantRead 赋予指定账户对对象的读权限,格式为 id="OwnerUin" String
StorageClass 设置对象的存储类型,STANDARD,STANDARD_IA,默认值 STANDARD String
Expires 设置 Expires String
CacheControl 缓存策略,设置 Cache-Control String
ContentType 内容类型,设置 Content-Type String
ContentDisposition 文件名称,设置 Content-Disposition String
ContentEncoding 编码格式,设置 Content-Encoding String
ContentLanguage 语言类型,设置 Content-Language String
Metadata 用户自定义的对象元数据 Dict

返回结果说明

上传对象的属性,类型为 dict:

{
  'ETag': 'string',
  'LastModified': 'string',
  'VersionId': 'string',
  'x-cos-copy-source-version-id': 'string'
}
参数名称 参数描述 类型
ETag 拷贝对象的 MD5 值 String
LastModified 拷贝对象的最后一次修改时间 String
VersionId 开启版本控制后,目的对象的版本号 String
x-cos-copy-source-version-id 源对象的版本号 String

删除单个对象

功能说明

删除指定的对象(DELETE Object)。

方法原型

delete_object(Bucket, Key, **kwargs)

请求示例1:删除单个对象

response = client.delete_object(
   Bucket='examplebucket-1250000000',
   Key='exampleobject'
)

请求示例2:删除目录

对象存储中,目录是特殊的路径以“/”结尾的 object。可直接调用 Delete Object 接口实现删除目录。

try:
   to_delete_dir='path/to/delete/dir/'
   response = client.delete_object(
       Bucket='examplebucket-1250000000',
       Key=to_delete_dir,
   )
   print(response)
except CosServiceError as e:
   print(e.get_status_code())

请求示例3:前缀批量删除

# -*- coding=utf-8
from qcloud_cos import CosConfig
from qcloud_cos import CosS3Client
from qcloud_cos import CosServiceError
from qcloud_cos import CosClientError
import sys
import os
import logging
# -*- coding=utf-8
from qcloud_cos import CosConfig
from qcloud_cos import CosS3Client
from qcloud_cos import CosServiceError
from qcloud_cos import CosClientError
import sys
import os
import logging
# 设置用户属性,包括 secret_id, secret_key, region
# APPID 已在配置中移除,请在参数 Bucket 中带上 APPID。Bucket 由 BucketName-APPID 组成
secret_id = ''     # 替换为用户的 secret_id
secret_key = ''     # 替换为用户的 secret_key
region = 'ap-guangzhou'    # 替换为用户的 region
token = None               # 使用临时密钥需要传入 Token,默认为空,可不填
config = CosConfig(Region=region, SecretId=secret_id, SecretKey=secret_key, Token=token)  # 获取配置对象
client = CosS3Client(config)
# 删除指定前缀 (prefix)的文件
bucket = 'examplebucket-1250000000'
is_over = False
marker = ''
prefix = 'root/logs'
while not is_over:
   try:
       response = client.list_objects(Bucket=bucket, Prefix=prefix, Marker=marker)
       if response['Contents']:
           for content in response['Contents']:
               print("delete object: ", content['Key'])
               client.delete_object(Bucket=bucket, Key=content['Key'])
            if response['IsTruncated'] == 'false':
               is_over = True
               marker = response['Marker']
   except CosServiceError as e:
       print(e.get_origin_msg())
       print(e.get_digest_msg())
       print(e.get_status_code())
       print(e.get_error_code())
       print(e.get_error_msg())
       print(e.get_resource_location())
       print(e.get_trace_id())
       print(e.get_request_id())
       break

全部参数请求示例

response = client.delete_object(
  Bucket='examplebucket-1250000000',
  Key='exampleobject',
  VersionId='string',
)

参数说明

参数名称 参数描述 类型 是否必填
Bucket 存储桶名称,由 BucketName-APPID 构成 String
Key 对象键(Key)是对象在存储桶中的唯一标识。例如,在对象的访问域名 examplebucket-1250000000.cos.ap-guangzhou.myqcloud.com/doc/pic.jpg 中,对象键为 doc/pic.jpg String
VersionId 开启版本控制后,指定对象的具体版本 String

返回结果说明

删除对象的信息,类型为 dict:

{
  'x-cos-version-id': 'string',
  'x-cos-delete-marker': 'true'|'false',
}
参数名称 参数描述 类型
x-cos-version-id 删除对象的版本号 String
x-cos-delete-marker 标识删除的对象是否为 delete marker String

删除多个对象

功能说明

删除多个指定的对象(DELETE Multiple Objects)。

方法原型

delete_objects(Bucket, Delete={}, **kwargs)

请求示例

response = client.delete_objects(
   Bucket='examplebucket-1250000000',
   Delete={
       'Object': [
           {
               'Key': 'exampleobject1'
           },
           {
               'Key': 'exampleobject2'
           }
       ]
   }
)

全部参数请求示例

response = client.delete_objects(
  Bucket='examplebucket-1250000000',
  Delete={
      'Object': [
          {
              'Key': 'exampleobject1',
              'VersionId': 'string'
          },
          {
              'Key': 'exampleobject2',
              'VersionId': 'string'
          },
      ],
      'Quiet': 'true'|'false'
  }
)

参数说明

参数名称 参数描述 类型 是否必填
Bucket Bucket 名称,由 BucketName-APPID 构成 String
Delete 说明本次删除的返回结果方式和目标 Object Dict
Object 说明每个将要删除的目标 Object 信息 List
Key 对象键(Key)是对象在存储桶中的唯一标识。例如,在对象的访问域名 examplebucket-1250000000.cos.ap-guangzhou.myqcloud.com/doc/pic.jpg 中,对象键为 doc/pic.jpg String
VersionId 开启版本控制后,目的对象的版本号 String
Quiet 指明删除的返回结果方式,可选值为 true、false,默认为 false。设置为 true 只返回失败的错误信息,设置为 false 时返回成功和失败的所有信息 String

返回结果说明

批量删除对象的结果,类型为 dict:

{
   'Deleted': [
       {
           'Key': 'string',
           'VersionId': 'string',
           'DeleteMarker': 'true'|'false',
           'DeleteMarkerVersionId': 'string'
       },
       {
           'Key': 'string',
       },
   ],
   'Error': [
       {
           'Key': 'string',
           'VersionId': 'string',
           'Code': 'string',
           'Message': 'string'
       },
   ]
}
参数名称 参数描述 类型
Deleted 删除成功的 Object 信息 List
Key 删除成功的 Object 的路径 String
VersionId 删除成功的 Object 的版本号 String
DeleteMarker 删除成功的 Object 是否为 delete marker String
DeleteMarkerVersionId 删除成功的 Object 的 delete marker 的版本号 String
Error 删除失败的 Object 信息 List
Key 删除失败的 Object 的路径 String
VersionId 删除失败的 Object 的版本号 String
Code 删除失败的 Object 对应的错误码 String
Message 删除失败的 Object 对应的错误信息 String

恢复归档对象

功能说明

将归档类型的对象取回访问(POST Object restore)。

方法原型

restore_object(Bucket, Key, RestoreRequest={}, **kwargs)

请求示例

response = client.restore_object(
   Bucket='examplebucket-1250000000',
   Key='exampleobject',
   RestoreRequest={
       'Days': 100,
       'CASJobParameters': {
           'Tier': 'Standard'
       }
   }
)

全部参数请求示例

response = client.restore_object(
  Bucket='examplebucket-1250000000',
  Key='exampleobject',
  RestoreRequest={
      'Days': 100,
      'CASJobParameters': {
          'Tier': 'Expedited'|'Standard'|'Bulk'
      }
  }
)

参数说明

参数名称 参数描述 类型 是否必填
Bucket 存储桶名称,由 BucketName-APPID 构成 String
Key 对象键(Key)是对象在存储桶中的唯一标识。例如,在对象的访问域名 examplebucket-1250000000.cos.ap-guangzhou.myqcloud.com/doc/pic.jpg 中,对象键为 doc/pic.jpg String
RestoreRequest 描述取回的临时对象的规则 Dict
Days 描述临时对象的过期时间 Int
CASJobParameters 描述恢复类型的配置信息 Dict
Tier 描述恢复对象的模式,若需恢复归档存储类型的数据,可选值为 Expedited、Standard、Bulk,分别对应极速、标准以及批量这三种模式。若需恢复深度归档存储类型的数据,则可选值为 Standard、Bulk String

返回结果说明

该方法返回值为 None。

检索对象内容

功能说明

从指定对象中检索内容(SELECT Object content)。

方法原型

select_object_content(Bucket, Key, Expression, ExpressionType, InputSerialization, OutputSerialization, RequestProgress=None, **kwargs)

请求示例

response = client.select_object_content(
   Bucket='examplebucket-1250000000',
   Key='exampleobject',
   Expression='Select * from COSObject',
   ExpressionType='SQL',
   InputSerialization={
       'CompressionType': 'NONE',
       'JSON': {
           'Type': 'LINES'
       }
   },
   OutputSerialization={
       'CSV': {
           'RecordDelimiter': '\n'
       }
   }
)

全部参数请求示例

response = client.select_object_content(
  Bucket='examplebucket-1250000000',
  Key='exampleobject',
  Expression='Select * from COSObject',
  ExpressionType='SQL',
  InputSerialization={
      'CompressionType': 'GZIP',
      'JSON': {
          'Type': 'LINES'
      }
  },
  OutputSerialization={
      'CSV': {
          'RecordDelimiter': '\n'
      }
  },
  RequestProgress={
      'Enabled': 'FALSE'
  }
)

参数说明

参数名称 参数描述 类型 是否必填
Bucket 存储桶名称,由 BucketName-APPID 构成 String
Key 对象键(Key)是对象在存储桶中的唯一标识。例如,在对象的访问域名examplebucket-1250000000.cos.ap-guangzhou.myqcloud.com/doc/pic.jpg中,对象键为 doc/pic.jpg String
Expression SQL 表达式,代表您需要发起的检索操作 String
ExpressionType 表达式类型,该项为扩展项,目前只支持 SQL 表达式,仅支持 SQL 参数 String
InputSerialization 描述待检索对象的格式,详情参见请求示例 Dict
OutputSerialization 描述检索结果的输出格式,详情参见请求示例 Dict
RequestProgress 是否需要返回查询进度 QueryProgress 信息,如果选中 COS Select 将周期性返回查询进度 Dict

返回结果说明

对象的 Body 和元信息,类型为 dict。

{
   'Body': EventStream(),
   'ETag': '"9a4802d5c99dafe1c04da0a8e7e166bf"',
   'Last-Modified': 'Wed, 28 Oct 2014 20:30:00 GMT',
   'Accept-Ranges': 'bytes',
   'Content-Range': 'bytes 0-16086/16087',
   'Cache-Control': 'max-age=1000000',
   'Content-Type': 'application/octet-stream',
   'Content-Disposition': 'attachment; filename="filename.jpg"',
   'Content-Encoding': 'gzip',
   'Content-Language': 'zh-cn',
   'Content-Length': '16807',
   'Expires': 'Wed, 28 Oct 2019 20:30:00 GMT',
   'x-cos-meta-test': 'test',
   'x-cos-version-id': 'MTg0NDUxODMzMTMwMDM2Njc1ODA',
   'x-cos-request-id': 'NTg3NzQ3ZmVfYmRjMzVfMzE5N182NzczMQ=='
}

分块操作

分块上传对象可包括的操作:

  • 分块上传对象:初始化分块上传,上传分块,完成所有分块上传。
  • 分块续传:查询已上传的分块,上传分块,完成所有分块上传。
  • 删除已上传分块。

查询分块上传

功能说明

查询指定存储桶正在进行中的分块上传信息(List Multipart Uploads)。

方法原型

list_multipart_uploads(Bucket, Prefix="", Delimiter="", KeyMarker="", UploadIdMarker="", MaxUploads=1000, EncodingType="", **kwargs)

请求示例

response = client.list_multipart_uploads(
   Bucket='examplebucket-1250000000',
   Prefix='dir'
)

全部参数请求示例

response = client.list_multipart_uploads(
  Bucket='examplebucket-1250000000',
  Prefix='string',
  Delimiter='string',
  KeyMarker='string',
  UploadIdMarker='string',
  MaxUploads=100,
  EncodingType='url'
)

参数说明

参数名称 参数描述 类型 是否必填
Bucket 存储桶名称,由 BucketName-APPID 构成 String
Prefix 默认为空,对分块上传的 key 进行筛选,匹配 prefix 为前缀的分块上传 String
Delimiter 默认为空,设置分隔符 String
KeyMarker 和 UploadIdMarker 一起使用,指明列出分块上传的起始位置 String
UploadIdMarker 和 KeyMarker 一起使用,指明列出分块上传的起始位置。如果未指定 KeyMarker,UploadIdMarker 将被忽略 String
MaxUploads 最多返回的分块上传的数量,默认为最大的1000 Int
EncodingType 默认不编码,规定返回值的编码方式,可选值:url String

返回结果说明

获取分块上传的信息,类型为 dict:

{
  'Bucket': 'examplebucket-1250000000',
  'Prefix': 'string',
  'Delimiter': 'string',
  'KeyMarker': 'string',
  'UploadIdMarker': 'string',
  'NextKeyMarker': 'string',
  'NextUploadIdMarker': 'string',
  'MaxUploads': '1000',
  'IsTruncated': 'true'|'false',,
  'EncodingType': 'url',
  'Upload':[
      {
          'UploadId': 'string',
          'Key': 'string',
          'Initiated': 'string',
          'StorageClass': 'STANDARD',
          'Owner': {
              'DisplayName': 'string',
              'ID': 'string'
          },
          'Initiator': {
              'ID': 'string',
              'DisplayName': 'string'
          }
      },
  ],
  'CommonPrefixes':[
      {
          'Prefix': 'string'
      },
  ],
}
参数名称 参数描述 类型
Bucket 存储桶名称,由 BucketName-APPID 构成 String
Prefix 默认为空,对分块上传的 key 进行筛选,匹配 prefix 为前缀的分块上传 String
Delimiter 默认为空,设置分隔符 String
KeyMarker 和 UploadIdMarker 一起使用,指明列出分块上传的 key 起始位置 String
UploadIdMarker 和 KeyMarker 一起使用,指明列出分块上传的 uploadId 起始位置。如果未指定 KeyMarker,UploadIdMarker 将被忽略 String
NextKeyMarker 当 IsTruncated 为 true 时,指明下一次列出分块上传的 key 的起始位置 String
NextUploadIdMarker 当 IsTruncated 为 true 时,指明下一次列出分块上传的 uploadId 的起始位置 String
MaxUploads 最多返回的分块上传的数量,默认为最大的1000 Int
IsTruncated 表示返回的分块上传是否被截断 String
EncodingType 默认不编码,规定返回值的编码方式,可选值:url String
Upload 包含所有分块上传的 list,包括 'UploadId','StorageClass','Key','Owner','Initiator','Initiated' 等信息 List
CommonPrefixes 所有以 Prefix 开头,以 Delimiter 结尾的 Key 被归到同一类 List

初始化分块上传

功能说明

初始化分块上传,获取对应的 uploadId(Initiate Multipart Upload)。

方法原型

create_multipart_upload(Bucket, Key, **kwargs):

请求示例

response = client.create_multipart_upload(
   Bucket='examplebucket-1250000000',
   Key='exampleobject',
   StorageClass='STANDARD'
)

全部参数请求示例

response = client.create_multipart_upload(
  Bucket='examplebucket-1250000000',
  Key='multipart.txt',
  StorageClass='STANDARD'|'STANDARD_IA'|'ARCHIVE',
  Expires='string',
  CacheControl='string',
  ContentType='string',
  ContentDisposition='string',
  ContentEncoding='string',
  ContentLanguage='string',
  Metadata={
      'x-cos-meta-key1': 'value1',
      'x-cos-meta-key2': 'value2'
  },
  ACL='private'|'public-read',
  GrantFullControl='string',
  GrantRead='string'
)
# 获取UploadId供后续接口使用
uploadid = response['UploadId']

参数说明

参数名称 参数描述 类型 是否必填
Bucket Bucket 名称,由 BucketName-APPID 构成 String
Key 对象键(Key)是对象在存储桶中的唯一标识。例如,在对象的访问域名 examplebucket-1250000000.cos.ap-guangzhou.myqcloud.com/doc/pic.jpg 中,对象键为 doc/pic.jpg String
StorageClass 设置对象的存储类型,STANDARD,STANDARD_IA,ARCHIVE。默认值为 STANDARD。更多存储类型,请参见 存储类型概述 String
Expires 设置 Expires String
CacheControl 缓存策略,设置 Cache-Control String
ContentType 内容类型,设置 Content-Type String
ContentDisposition 文件名称,设置 Content-Disposition String
ContentEncoding 编码格式,设置 Content-Encoding String
ContentLanguage 语言类型,设置 Content-Language String
Metadata 用户自定义的对象元数据 Dict
ACL 设置对象的 ACL,例如 'private','public-read' String
GrantFullControl 赋予被授权者所有的权限,格式为 id="OwnerUin" String
GrantRead 赋予被授权者读的权限,格式为 id="OwnerUin" String

返回结果说明

获取分块上传的初始化信息,类型为 dict:

{
  'UploadId': '150219101333cecfd6718d0caea1e2738401f93aa531a4be7a2afee0f8828416f3278e5570',
  'Bucket': 'examplebucket-1250000000', 
  'Key': 'exampleobject' 
}
参数名称 参数描述 类型
UploadId 标识分块上传的 ID String
Bucket 存储桶名称,由 BucketName-APPID 组成 String
Key 对象键(Key)是对象在存储桶中的唯一标识。例如,在对象的访问域名 examplebucket-1250000000.cos.ap-guangzhou.myqcloud.com/doc/pic.jpg 中,对象键为 doc/pic.jpg String

上传分块

分块上传对象(Upload Part)。

方法原型

upload_part(Bucket, Key, Body, PartNumber, UploadId, **kwargs)

请求示例

# 注意,上传分块的块数最多10000块
response = client.upload_part(
   Bucket='examplebucket-1250000000',
   Key='exampleobject',
   Body=b'b'*1024*1024,
   PartNumber=1,
   UploadId='exampleUploadId'
)

全部参数请求示例

# 注意,上传分块的块数最多10000块
response = client.upload_part(
  Bucket='examplebucket-1250000000',
  Key='exampleobject',
  Body=b'bytes'|file,
  PartNumber=1,
  UploadId='string',
  EnableMD5=False|True,
  ContentLength='123',
  ContentMD5='string',
  TrafficLimit='1048576'
)

参数说明

参数名称 参数描述 类型 是否必填
Bucket Bucket 名称,由 BucketName-APPID 构成 String
Key 对象键(Key)是对象在存储桶中的唯一标识。例如,在对象的访问域名 examplebucket-1250000000.cos.ap-guangzhou.myqcloud.com/doc/pic.jpg 中,对象键为 doc/pic.jpg String
Body 上传分块的内容,可以为本地文件流或输入流 file/bytes
PartNumber 标识上传分块的序号 Int
UploadId 标识分块上传的 ID String
EnableMD5 是否需要 SDK 计算 Content-MD5,默认关闭,打开后会增加上传耗时 Bool
ContentLength 设置传输长度 String
ContentMD5 设置上传对象的 MD5 值用于校验 String
TrafficLimit 单链接限速的值,单位为bit/s,限速值设置范围为819200 - 838860800,即100KB/s - 100MB/s String

返回结果说明

上传分块的属性,类型为 dict:

{
  'ETag': 'string'
}
参数名称 参数描述 类型
ETag 上传分块的 MD5 值。 String

复制分块

将其他对象复制为一个分块(Upload Part - Copy)。

方法原型

upload_part_copy(Bucket, Key, PartNumber, UploadId, CopySource, CopySourceRange='', **kwargs)

请求示例

response = client.upload_part_copy(
   Bucket='examplebucket-1250000000',
   Key='exampleobject',
   PartNumber=1,
   UploadId='exampleUploadId',
   CopySource={
       'Bucket': 'sourcebucket-1250000000', 
       'Key': 'exampleobject', 
       'Region': 'ap-guangzhou'
   }
)

全部参数请求示例

response = client.upload_part_copy(
  Bucket='examplebucket-1250000000',
  Key='exampleobject',
  PartNumber=100,
  UploadId='string',
  CopySource={
      'Bucket': 'sourcebucket-1250000000', 
      'Key': 'sourceObject', 
      'Region': 'COS_REGION', #替换为源存储桶的 Region
      'VersionId': 'string'
  },
  CopySourceRange='string',
  CopySourceIfMatch='string',
  CopySourceIfModifiedSince='string',
  CopySourceIfNoneMatch='string',
  CopySourceIfUnmodifiedSince='string'
)

参数说明

参数名称 参数描述 类型 是否必填
Bucket 存储桶名称,由 BucketName-APPID 构成 String
Key 对象键(Key)是对象在存储桶中的唯一标识。例如,在对象的访问域名 examplebucket-1250000000.cos.ap-guangzhou.myqcloud.com/doc/pic.jpg 中,对象键为 doc/pic.jpg String
PartNumber 标识上传分块的序号 Int
UploadId 标识分块上传的 ID String
CopySource 描述拷贝源对象的路径,包含 Bucket、Key、Region、VersionId Dict
CopySourceRange 描述拷贝源对象的范围,格式为 bytes=first-last。不指定时,默认拷贝整个源对象 String
CopySourceIfMatch 源对象的 Etag 与给定的值相同时才拷贝 String
CopySourceIfModifiedSince 源对象在给定的时间后被修改相才拷贝 String
CopySourceIfNoneMatch 源对象的 Etag 与给定的值不相同时才拷贝 String
CopySourceIfUnmodifiedSince 源对象在给定的时间后没有修改相才拷贝 String

返回结果说明

复制分块的属性,类型为 dict:

{
   'ETag': 'string',
   'LastModified': 'string',
   'x-cos-copy-source-version-id': 'string',
}
参数名称 参数描述 类型
ETag 拷贝分块的 MD5 值 String
LastModified 拷贝分块的最后一次修改时间 String
x-cos-copy-source-version-id 源对象的版本号 String

查询已上传块

功能说明

查询特定分块上传操作中的已上传的块(List Parts)。

方法原型

list_parts(Bucket, Key, UploadId, MaxParts=1000, PartNumberMarker=0, EncodingType='', **kwargs)

请求示例

response = client.list_parts(
   Bucket='examplebucket-1250000000',
   Key='exampleobject',
   UploadId='exampleUploadId'
)

全部参数请求示例

response = client.list_parts(
  Bucket='examplebucket-1250000000',
  Key='exampleobject',
  UploadId=uploadid,
  MaxParts=1000,
  PartNumberMarker=100,
  EncodingType='url'
)

参数说明

参数名称 参数描述 类型 是否必填
Bucket 存储桶名称,由 BucketName-APPID 构成 String
Key 对象键(Key)是对象在存储桶中的唯一标识。例如,在对象的访问域名 examplebucket-1250000000.cos.ap-guangzhou.myqcloud.com/doc/pic.jpg 中,对象键为 doc/pic.jpg String
UploadId 标识分块上传的 ID String
MaxParts 最多返回的分块的数量,默认为最大的1000 Int
PartNumberMarker 默认为0,从第一块列出分块,从 PartNumberMarker 下一个分块开始列出 Int
EncodingType 默认不编码,规定返回值的编码方式,可选值:url String

返回结果说明

所有上传分块的信息,类型为 dict:

{
  'Bucket': 'examplebucket-1250000000', 
  'Key': 'exampleobject', 
  'UploadId': '1502192444bdb382add546a35b2eeab81e06ed84086ca0bb75ea45ca7fa073fa9cf74ec4f2', 
  'EncodingType': None, 
  'MaxParts': '1000',
  'IsTruncated': 'true',
  'PartNumberMarker': '0', 
  'NextPartNumberMarker': '1000', 
  'StorageClass': 'Standard',
  'Part': [
      {
          'LastModified': '2017-08-08T11:40:48.000Z',
          'PartNumber': '1',
          'ETag': '"8b8378787c0925f42ccb829f6cc2fb97"',
          'Size': '10485760'
      },
  ], 
  'Initiator': {
      'DisplayName': '3333333333', 
      'ID': 'qcs::cam::uin/3333333333:uin/3333333333'
  }, 
  'Owner': {
      'DisplayName': '124564654654',
      'ID': '124564654654'
  }
}
参数名称 参数描述 类型
Bucket 存储桶名称,由 BucketName-APPID 构成 String
Key 对象键(Key)是对象在存储桶中的唯一标识。例如,在对象的访问域名 examplebucket-1250000000.cos.ap-guangzhou.myqcloud.com/doc/pic.jpg 中,对象键为 doc/pic.jpg String
UploadId 标识分块上传的 ID String
EncodingType 默认不编码,规定返回值的编码方式,可选值:url String
MaxParts 最多返回的分块的数量,默认为最大的1000 String
IsTruncated 表示返回的分块是否被截断 String
PartNumberMarker 默认为0,从第一块列出分块,从 PartNumberMarker 下一个分块开始列出 String
NextPartNumberMarker 指明下一次列出分块的起始位置 String
StorageClass 对象的存储类型,STANDARD,STANDARD_IA,ARCHIVE。默认值为 STANDARD,更多存储类型,请参见 存储类型概述 String
Part 上传分块的相关信息,包括 ETag,PartNumber,Size,LastModified String
Initiator 分块上传的创建者,包括 DisplayName 和 ID Dict
Owner 对象拥有者的信息,包括 DisplayName 和 ID Dict

完成分块上传

功能说明

完成整个对象的分块上传(Complete Multipart Upload)。

方法原型

complete_multipart_upload(Bucket, Key, UploadId, MultipartUpload={}, **kwargs)

请求示例

response = client.complete_multipart_upload(
   Bucket='examplebucket-1250000000',
   Key='exampleobject',
   UploadId='exampleUploadId',
   MultipartUpload={
       'Part': [
           {
               'ETag': 'string',
               'PartNumber': 1
           },
           {
               'ETag': 'string',
               'PartNumber': 2
           },
       ]
   },
)

参数说明

参数名称 参数描述 类型 是否必填
Bucket Bucket 名称,由 BucketName-APPID 构成 String
Key 对象键(Key)是对象在存储桶中的唯一标识。例如,在对象的访问域名 examplebucket-1250000000.cos.ap-guangzhou.myqcloud.com/doc/pic.jpg 中,对象键为 doc/pic.jpg String
UploadId 标识分块上传的 ID String
MultipartUpload 所有分块的 ETag 和 PartNumber 信息 Dict

返回结果说明

组装后的对象的相关信息,类型为 dict:

{
  'ETag': '"3f866d0050f044750423e0a4104fa8cf-2"', 
  'Bucket': 'examplebucket-1250000000', 
  'Location': 'examplebucket-1250000000.cos.ap-guangzhou.myqcloud.com/exampleobject', 
  'Key': 'exampleobject'
}
参数名称 参数描述 类型
ETag 合并后对象的唯一标签值,该值不是对象内容的 MD5 校验值,仅能用于检查对象唯一性。如需校验对象内容,可以在上传过程中校验单个分块的 ETag 值。 String
Bucket 存储桶名称,由 BucketName-APPID 构成 String
Location URL 地址 String
Key 对象键(Key)是对象在存储桶中的唯一标识。例如,在对象的访问域名 examplebucket-1250000000.cos.ap-guangzhou.myqcloud.com/doc/pic.jpg 中,对象键为 doc/pic.jpg String

终止分块上传

功能说明

终止一个分块上传操作并删除已上传的块(Abort Multipart Upload)。

方法原型

abort_multipart_upload(Bucket, Key, UploadId, **kwargs)

请求示例

response = client.abort_multipart_upload(
   Bucket='examplebucket-1250000000',
   Key='exampleobject',
   UploadId='exampleUploadId'
)

参数说明

参数名称 参数描述 类型 是否必填
Bucket 存储桶名称,由 BucketName-APPID 构成 String
Key 对象键(Key)是对象在存储桶中的唯一标识。例如,在对象的访问域名 examplebucket-1250000000.cos.ap-guangzhou.myqcloud.com/doc/pic.jpg 中,对象键为 doc/pic.jpg String
UploadId 标识分块上传的 ID String

返回结果说明

该方法返回值为 None。

高级接口(推荐)

上传对象(断点续传)

功能说明

该高级接口根据用户文件的长度自动选择简单上传以及分块上传,对于小于等于20M的文件调用简单上传,对于大于20MB的文件调用分块上传,对于分块上传未完成的文件会自动进行断点续传。
对于分块上传的文件,可以通过 progress_callback 回调函数,获取上传进度。

方法原型

upload_file(Bucket, Key, LocalFilePath, PartSize=1, MAXThread=5, EnableMD5=False, progress_callback=None, **kwargs)

请求示例


response = client.upload_file(
   Bucket='examplebucket-1250000000',
   Key='exampleobject',
   LocalFilePath='local.txt',
   EnableMD5=False,
   progress_callback=None
)

全部参数请求示例

def upload_percentage(consumed_bytes, total_bytes):
   """进度条回调函数,计算当前上传的百分比
    :param consumed_bytes: 已经上传的数据量
   :param total_bytes: 总数据量
   """
   if total_bytes:
       rate = int(100 * (float(consumed_bytes) / float(total_bytes)))
       print('\r{0}% '.format(rate))
       sys.stdout.flush()

response = client.upload_file(
   Bucket='examplebucket-1250000000',
   Key='exampleobject',
   LocalFilePath='local.txt',
   PartSize=1,
   MAXThread=5,
   progress_callback=upload_percentage,
   EnableMD5=False|True,
   ACL='private'|'public-read', # 请慎用此参数,否则会达到1000条ACL上限
   GrantFullControl='string',
   GrantRead='string',
   StorageClass='STANDARD'|'STANDARD_IA'|'ARCHIVE',
   Expires='string',
   CacheControl='string',
   ContentType='string',
   ContentDisposition='string',
   ContentEncoding='string',
   ContentLanguage='string',
   ContentLength='123',
   ContentMD5='string',
   Metadata={
       'x-cos-meta-key1': 'value1',
       'x-cos-meta-key2': 'value2'
   },
   TrafficLimit='1048576'
)

参数说明

参数名称 参数描述 类型 是否必填
Bucket 存储桶名称,由 BucketName-APPID 构成 String
Key 对象键(Key)是对象在存储桶中的唯一标识。例如,在对象的访问域名 examplebucket-1250000000.cos.ap-guangzhou.myqcloud.com/doc/pic.jpg 中,对象键为 doc/pic.jpg String
LocalFilePath 本地文件的路径名 String
PartSize 分块上传的分块大小,默认为1MB Int
MAXThread 分块上传的并发数量,默认为5个线程上传分块 Int
progress_callback 上传进度的回调函数,可以通过自定义此函数,来获取上传进度 Func
EnableMD5 是否需要 SDK 计算 Content-MD5,默认关闭,打开后会增加上传耗时 Bool
ACL 设置对象的 ACL,例如 private,public-read String
GrantFullControl 赋予被授权者所有的权限,格式为 id="OwnerUin" String
GrantRead 赋予被授权者读的权限,格式为 id="OwnerUin" String
StorageClass 设置对象的存储类型,例如 STANDARD,STANDARD_IA,ARCHIVE。默认值为 STANDARD,更多存储类型,请参见 存储类型概述 String
Expires 设置 Expires String
CacheControl 缓存策略,设置 Cache-Control String
ContentType 内容类型,设置 Content-Type String
ContentDisposition 文件名称,设置 Content-Disposition String
ContentEncoding 编码格式,设置 Content-Encoding String
ContentLanguage 语言类型,设置 Content-Language String
ContentLength 设置传输长度 String
ContentMD5 设置上传对象的 MD5 值用于校验 String
Metadata 用户自定义的对象元数据 Dict
TrafficLimit 单链接限速的值,单位为bit/s,限速值设置范围为819200 - 838860800,即100KB/s - 100MB/s,高级接口限制的是单线程的速度 String

返回结果说明

上传对象的属性,类型为 dict:

{
  'ETag': 'string'
}
参数名称 参数描述 类型
ETag 分块上传的对象,该值不是对象内容的 MD5 校验值,仅能用于检查对象唯一性 String

下载对象(断点续传)

功能说明

该高级接口仅支持下载整个文件,根据用户文件的长度自动选择简单下载以及分块下载,对于小于等于20MB的文件使用简单下载,大于20MB的文件使用续传下载,对于分块下载未完成的文件会自动进行断点续传。

方法原型

download_file(Bucket, Key, DestFilePath, PartSize=20, MAXThread=5, EnableCRC=False, **Kwargs)

请求示例

response = client.download_file(
   Bucket='examplebucket-1250000000',
   Key='exampleobject',
   DestFilePath='local.txt'
)

全部参数请求示例

response = client.download_file(
   Bucket='examplebucket-1250000000',
   Key='exampleobject',
   DestFilePath='local.txt',
   PartSize=1,
   MAXThread=5,
   EnableCRC=True,
   TrafficLimit='1048576'
   IfMatch='"9a4802d5c99dafe1c04da0a8e7e166bf"',
   IfModifiedSince='Wed, 28 Oct 2014 20:30:00 GMT',
   IfNoneMatch='"9a4802d5c99dafe1c04da0a8e7e166bf"',
   IfUnmodifiedSince='Wed, 28 Oct 2014 20:30:00 GMT',
   ResponseCacheControl='string',
   ResponseContentDisposition='string',
   ResponseContentEncoding='string',
   ResponseContentLanguage='string',
   ResponseContentType='string',
   ResponseExpires='string',
   VersionId='string'
)

参数说明

参数名称 参数描述 类型 是否必填
Bucket 存储桶名称,由 BucketName-APPID 构成 String
Key 对象键(Key)是对象在存储桶中的唯一标识。例如,在对象的访问域名examplebucket-1250000000.cos.ap-guangzhou.myqcloud.com/doc/pic.jpg中,对象键为 doc/pic.jpg String
DestFilePath 文件下载的本地目的路径名 String
PartSize 分块下载的分块大小,默认为20MB Int
MAXThread 分块下载的并发数量,默认为5个线程下载分块 Int
EnableCRC 是否开启本地文件与远程文件的 crc 校验,默认为 False Bool
TrafficLimit 单链接限速的值,单位为bit/s,限速值设置范围为819200 - 838860800,即100KB/s - 100MB/s,高级接口限制的是单线程的速度 String
IfMatch ETag 与指定的内容一致时才返回 String
IfModifiedSince 在指定时间后被修改才返回,时间格式为 GMT String
IfNoneMatch ETag 与指定的内容不一致才返回 String
IfUnmodifiedSince 对象修改时间早于或等于指定时间才返回,时间格式为 GMT String
ResponseCacheControl 设置响应头部 Cache-Control String
ResponseContentDisposition 设置响应头部 Content-Disposition String
ResponseContentEncoding 设置响应头部 Content-Encoding String
ResponseContentLanguage 设置响应头部 Content-Language String
ResponseContentType 设置响应头部 Content-Type String
ResponseExpires 设置响应头部 Expires String
VersionId 指定下载对象的版本 String

返回结果说明

None

批量上传(本地文件夹上传)

功能说明

该示例展示通过组合 SDK 的基本接口,完成批量上传本地文件夹到 COS。

请求示例

# -*- coding=utf-8
from qcloud_cos import CosConfig
from qcloud_cos import CosS3Client
from qcloud_cos import CosServiceError
from qcloud_cos import CosClientError
from qcloud_cos.cos_threadpool import SimpleThreadPool
import sys
import os
import logging
# 设置用户属性, 包括secret_id, secret_key, region
# APPID 已在配置中移除,请在参数 Bucket 中带上 APPID。Bucket 由 BucketName-APPID 组成
secret_id = ''     # 替换为用户的 secret_id
secret_key = ''     # 替换为用户的 secret_key
region = 'ap-guangzhou'    # 替换为用户的 region
token = None               # 使用临时密钥需要传入 Token,默认为空,可不填
config = CosConfig(Region=region, SecretId=secret_id, SecretKey=secret_key, Token=token)  # 获取配置对象
client = CosS3Client(config)
uploadDir = '/root/logs'
bucket = 'examplebucket-125000000'
g = os.walk(uploadDir)
# 创建上传的线程池
pool = SimpleThreadPool()
for path, dir_list, file_list in g:
   for file_name in file_list:
       srcKey = os.path.join(path, file_name)
       cosObjectKey = srcKey.strip('/')
       # 判断COS上文件是否存在
       exists = False
       try:
           response = client.head_object(Bucket=bucket, Key=cosObjectKey)
           exists = True
       except CosServiceError as e:
           if e.get_status_code() == 404:
               exists = False
           else:
               print("Error happened, reupload it.")
       if not exists:
           print("File %s not exists in cos, upload it", srcKey)
           pool.add_task(client.upload_file, bucket, cosObjectKey, srcKey)

pool.wait_completion()
result = pool.get_result()
if not result['success_all']:
   print("Not all files upload sucessed. you should retry")

批量下载(从 COS 下载目录)

功能说明

该示例展示通过组合 SDK 的基本接口,完成批量下载 COS 目录中的文件到本地磁盘。

请求示例

# -*- coding=utf-8
import logging
import sys
import json
import os
from qcloud_cos import CosConfig, CosServiceError
from qcloud_cos import CosS3Client
from qcloud_cos.cos_threadpool import SimpleThreadPool
logging.basicConfig(level=logging.INFO, stream=sys.stdout)
# 设置用户属性, 包括secret_id, secret_key, region
# appid已在配置中移除,请在参数Bucket中带上appid。Bucket由bucketname-appid组成
secret_id = 'secret_id'  # 替换为用户的secret_id
secret_key = 'secret_key'  # 替换为用户的secret_key
region = 'ap-shanghai'  # 替换为用户的region
token = None  # 使用临时密钥需要传入Token,默认为空,可不填
scheme = 'http'
config = CosConfig(Region=region, SecretId=secret_id, SecretKey=secret_key, Token=token, Scheme=scheme)  # 获取配置对象
client = CosS3Client(config)
# 用户的 bucket 信息
test_bucket = 'chenxi-1253870963'
start_prefix = 'data/'
# 对象存储依赖 分隔符 '/' 来模拟目录语义,
# 使用默认的空分隔符可以列出目录下面的所有子节点,实现类似本地目录递归的效果,
# 如果 delimiter 设置为 "/",则需要在程序里递归处理子目录
delimiter = ''

# 列出当前目录子节点,返回所有子节点信息
def listCurrentDir(prefix):
   file_infos = []
   sub_dirs = []
   marker = ""
   count = 1
   while True:
       response = client.list_objects(test_bucket, prefix, delimiter, marker)
       # 调试输出
       # json_object = json.dumps(response, indent=4)
       # print(count, " =======================================")
       # print(json_object)
       count += 1
        if "CommonPrefixes" in response:
           common_prefixes = response.get("CommonPrefixes")
           sub_dirs.extend(common_prefixes)
        if "Contents" in response:
           contents = response.get("Contents")
           file_infos.extend(contents)
        if "NextMarker" in response.keys():
           marker = response["NextMarker"]
       else:
           break
    print("=======================================================")
    # 如果 delimiter 设置为 "/",则需要进行递归处理子目录,
   # sorted(sub_dirs, key=lambda sub_dir: sub_dir["Prefix"])
   # for sub_dir in sub_dirs:
   #     print(sub_dir)
   #     sub_dir_files = listCurrentDir(sub_dir["Prefix"])
   #     file_infos.extend(sub_dir_files)
    print("=======================================================")
    sorted(file_infos, key=lambda file_info: file_info["Key"])
   for file in file_infos:
       print(file)
   return file_infos

# 下载文件到本地目录,如果本地目录已经有同名文件则会被覆盖;
# 如果目录结构不存在,则会创建和对象存储一样的目录结构
def downLoadFiles(file_infos):
   localDir = "./download/"
    pool = SimpleThreadPool()
   for file in file_infos:
       # 文件下载 获取文件到本地
       file_cos_key = file["Key"]
       localName = localDir + file_cos_key
        # 如果本地目录结构不存在,递归创建
       if not os.path.exists(os.path.dirname(localName)):
           os.makedirs(os.path.dirname(localName))
        # skip dir, no need to download it
       if str(localName).endswith("/"):
           continue
        # 实际下载文件
       # 使用线程池方式
       pool.add_task(client.download_file, test_bucket, file_cos_key, localName)
        # 简单下载方式
       # response = client.get_object(
       #     Bucket=test_bucket,
       #     Key=file_cos_key,
       # )
       # response['Body'].get_stream_to_file(localName)
    pool.wait_completion()
   return None

# 功能封装,下载对象存储上面的一个目录到本地磁盘
def downLoadDirFromCos(prefix):
   global file_infos
    try:
       file_infos = listCurrentDir(prefix)
    except CosServiceError as e:
       print(e.get_origin_msg())
       print(e.get_digest_msg())
       print(e.get_status_code())
       print(e.get_error_code())
       print(e.get_error_msg())
       print(e.get_resource_location())
       print(e.get_trace_id())
       print(e.get_request_id())
    downLoadFiles(file_infos)
   return None

if __name__ == "__main__":
   downLoadDirFromCos(start_prefix)

复制对象

功能说明

文件拷贝,小于5G的文件调用 copy_object,大于等于5G的文件调用分块上传的 upload_part_copy。

方法原型

copy(Bucket, Key, CopySource, CopyStatus='Copy', PartSize=10, MAXThread=5, **kwargs)

请求示例1:复制对象

response = client.copy(
   Bucket='test',
   Key='copy_10G.txt',
   CopySource={
       'Bucket': 'sourcebucket-1250000000', 
       'Key': 'exampleobject', 
       'Region': 'ap-guangzhou'
   }
)

请求示例2:移动对象

# -*- coding=utf-8
from qcloud_cos import CosConfig
from qcloud_cos import CosS3Client
from qcloud_cos import CosServiceError
from qcloud_cos import CosClientError
import sys
import os
import logging
# -*- coding=utf-8
from qcloud_cos import CosConfig
from qcloud_cos import CosS3Client
from qcloud_cos import CosServiceError
from qcloud_cos import CosClientError
import sys
import os
import logging
# 设置用户属性, 包括 secret_id, secret_key, region
# APPID 已在配置中移除,请在参数 Bucket 中带上 APPID。Bucket 由 BucketName-APPID 组成
secret_id = ''     # 替换为用户的 secret_id
secret_key = ''     # 替换为用户的 secret_key
region = 'ap-guangzhou'    # 替换为用户的 region
token = None               # 使用临时密钥需要传入 Token,默认为空,可不填
config = CosConfig(Region=region, SecretId=secret_id, SecretKey=secret_key, Token=token)  # 获取配置对象
client = CosS3Client(config)
# 移动对象
bucket = 'examplebucket-1250000000'
srcKey = 'src_object_key'  # 原始的对象路径
destKey = 'dest_object_key'   # 目的对象路径
#本示例展示利用 SDK 基本接口完成文件的 move 操作。
try:
   response = client.copy_object(
       Bucket=bucket,
       Key=destKey,
       CopySource={
           'Bucket':bucket,
           'Key':srcKey,
           'Region':'ap-guangzhou',
       })
   client.delete_object(Bucket=bucket, Key=srcKey)
except CosException as e:
    print(e.get_error_msg())

全部参数请求示例

response = client.copy(
   Bucket='examplebucket-1250000000',
   Key='exampleobject',
   CopySource={
       'Bucket': 'sourcebucket-1250000000', 
       'Key': 'exampleobject', 
       'Region': 'ap-guangzhou'
   }
   CopyStatus='Copy',
   PartSize=20,
   MAXThread=10
)

参数说明

参数名称 参数描述 类型 是否必填
Bucket 存储桶名称,由 BucketName-APPID 构成 String
Key 对象键(Key)是对象在存储桶中的唯一标识。例如,在对象的访问域名examplebucket-1250000000.cos.ap-guangzhou.myqcloud.com/doc/pic.jpg中,对象键为 doc/pic.jpg String
CopySource 描述拷贝源对象的路径,包含 Bucket、Key、Region、VersionId Dict
CopyStatus 拷贝状态,可选值 Copy、Replaced String 否 |
PartSize 分块下载的分块大小,默认为10MB Int
MAXThread 分块下载的并发数量,默认为5个线程下载分块 Int

返回结果说明

若小于5G的文件,则为 copy_object 的返回结果,否则为 complete_multipart_upload 的返回结果,类型为 dict。

客户端加密

功能说明

Python 支持客户端加密,将文件加密后再进行上传,并在下载时进行解密。客户端加密支持对称 AES 和非对称 RSA 加密。
这里的对称和非对称只是用来加密每次生成的随机密钥,对文件数据的加密始终使用 AES256 对称加密。
客户端加密适用于存储敏感数据的客户,客户端加密会牺牲部分上传速度,SDK 内部对于分块上传会使用串行的方式进行上传。

上传加密流程

  1. 每次上传一个文件对象前,我们随机生成一个对称加密密钥,随机生成的密钥通过用户的提供的对称或非对称密钥进行加密,将加密后的结果 base64 编码存储在对象的元数据中。
  2. 进行文件对象的上传,上传时在内存使用 AES256 算法加密。

下载解密流程

  1. 获取文件元数据中加密必要的信息,Base64 解码后使用用户密钥进行解密,得到当时加密数据的密钥。
  2. 使用密钥对下载输入流进行使用 AES256 解密,得到解密后的文件输入流。

请求示例

示例1:使用对称 AES256 加密每次生成的随机密钥示例。

# 初始化用户身份信息(SECRET_ID, SECRET_KEY)
SECRET_ID = "COS_SECRETID"
SECRET_KEY = "COS_SECRETKEY"
REGION = "COS_REGION"
conf = CosConfig(
   Region=REGION,
   SecretId=SECRET_ID,
   SecretKey=SECRET_KEY,
)
# 方式一:通过密钥值初始化加密客户端
aes_provider = AESProvider(aes_key='aes_key_value')
# 方式二:通过密钥路径初始化加密客户端
aes_key_pair = AESProvider(aes_key_path='aes_key_path')
client_for_aes = CosEncryptionClient(conf, aes_provider)
# 上传对象,兼容非加密客户端的put_object的所有功能,具体使用可参考put_object
response = client_for_aes.put_object(
                       Bucket='examplebucket-1250000000',
                       Body=b'bytes'|file,
                       Key='exampleobject',
                       EnableMD5=False)
# 下载对象,兼容非加密客户端的get_object的所有功能,具体使用可参考get_object
response = client_for_aes.get_object(
                       Bucket='examplebucket-1250000000',
                       Key='exampleobject')
# 分块上传,兼容非加密客户端的分块上传,除了最后一个part,每个part的大小必须为16字节的整数倍
response = client_for_aes.create_multipart_upload(
                       Bucket='examplebucket-1250000000',
                       Key='exampleobject_upload')
uploadid = response['UploadId']
client_for_aes.upload_part(
               Bucket='examplebucket-1250000000',
               Key='exampleobject_upload',
               Body=b'bytes'|file,
               PartNumber=1,
               UploadId=uploadid)
response = client_for_aes.list_parts(
               Bucket='examplebucket-1250000000',
               Key='exampleobject_upload',
               UploadId=uploadid)
client_for_aes.complete_multipart_upload(
               Bucket='examplebucket-1250000000',
               Key='exampleobject_upload',
               UploadId=uploadid,
               MultipartUpload={'Part':response['Part']})
# 断点续传方式上传对象,`partsize`大小必须为16字节的整数倍
response = client_for_aes.upload_file(
   Bucket='test04-123456789',
   LocalFilePath='local.txt',
   Key=file_name,
   PartSize=10,
   MAXThread=10
)

示例2:使用非对称 RSA 加密每次生成的随机密钥示例。

# 初始化用户身份信息(SECRET_ID, SECRET_KEY)
SECRET_ID = "COS_SECRETID"
SECRET_KEY = "COS_SECRETKEY"
REGION = "COS_REGION"
conf = CosConfig(
   Region=REGION,
   SecretId=SECRET_ID,
   SecretKey=SECRET_KEY,
)
# 方式一:通过密钥值初始化加密客户端
rsa_key_pair = RSAProvider.get_rsa_key_pair('public_key_value', 'private_key_value')
# 方式二:通过密钥路径初始化加密客户端
rsa_key_pair = RSAProvider.get_rsa_key_pair('public_key_path', 'private_key_path')
rsa_provider = RSAProvider(key_pair_info=rsa_key_pair)
client_for_rsa = CosEncryptionClient(conf, rsa_provider)
# 上传对象,兼容非加密客户端的put_object的所有功能,具体使用可参考put_object
response = client_for_rsa.put_object(
                       Bucket='examplebucket-1250000000',
                       Body=b'bytes'|file,
                       Key='exampleobject',
                       EnableMD5=False)
# 下载对象,兼容非加密客户端的get_object的所有功能,具体使用可参考get_object
response = client_for_rsa.get_object(
                       Bucket='examplebucket-1250000000',
                       Key='exampleobject')
# 分块上传,兼容非加密客户端的分块上传,除了最后一个part,每个part的大小必须为16字节的整数倍
response = client_for_rsa.create_multipart_upload(
                       Bucket='examplebucket-1250000000',
                       Key='exampleobject_upload')
uploadid = response['UploadId']
client_for_rsa.upload_part(
               Bucket='examplebucket-1250000000',
               Key='exampleobject_upload',
               Body=b'bytes'|file,
               PartNumber=1,
               UploadId=uploadid)
response = client_for_rsa.list_parts(
               Bucket='examplebucket-1250000000',
               Key='exampleobject_upload',
               UploadId=uploadid)
client_for_rsa.complete_multipart_upload(
               Bucket='examplebucket-1250000000',
               Key='exampleobject_upload',
               UploadId=uploadid,
               MultipartUpload={'Part':response['Part']})
# 断点续传方式上传对象,`partsize`大小必须为16字节的整数倍
response = client_for_rsa.upload_file(
   Bucket='test04-123456789',
   LocalFilePath='local.txt',
   Key=file_name,
   PartSize=10,
   MAXThread=10
)
目录