控制台指南

最佳实践

开发者指南

API 文档

SDK 文档

对象操作

最近更新时间:2021-03-31 16:05:46

简介

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

简单操作

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

分块操作

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

简单操作

查询对象列表

功能说明

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

方法原型

CosResult GetBucket(const GetBucketReq& req, GetBucketResp* resp)

请求示例

qcloud_cos::CosConfig config("./config.json");
qcloud_cos::CosAPI cos(config);
std::string bucket_name = "examplebucket-1250000000";
// GetBucketReq 的构造函数需要传入 bucket_name
qcloud_cos::GetBucketReq req(bucket_name);
qcloud_cos::GetBucketResp resp;
qcloud_cos::CosResult result = cos.GetBucket(req, &resp);
// 调用成功,调用 resp 的成员函数获取返回内容
if (result.IsSucc()) {
  std::cout << "Name=" << resp.GetName() << std::endl;
  std::cout << "Prefix=" << resp.GetPrefix() << std::endl;
  std::cout << "Marker=" << resp.GetMarker() << std::endl;
  std::cout << "MaxKeys=" << resp.GetMaxKeys() << std::endl;
} else {
  std::cout << "ErrorInfo=" << result.GetErrorInfo() << std::endl;
  std::cout << "HttpStatus=" << result.GetHttpStatus() << std::endl;
  std::cout << "ErrorCode=" << result.GetErrorCode() << std::endl;
  std::cout << "ErrorMsg=" << result.GetErrorMsg() << std::endl;
  std::cout << "ResourceAddr=" << result.GetResourceAddr() << std::endl;
  std::cout << "XCosRequestId=" << result.GetXCosRequestId() << std::endl;
  std::cout << "XCosTraceId=" << result.GetXCosTraceId() << std::endl;
} 

参数说明

参数 参数描述 类型 是否必填
req GetBucket 操作的请求 GetBucketReq
resp GetBucket 操作的响应 GetBucketResp

GetBucketResp 提供以下成员函数,用于获取 Get Bucket 返回的 XML 格式中的具体内容。

std::vector<Content> GetContents();
std::string GetName();
std::string GetPrefix();
std::string GetMarker();
uint64_t GetMaxKeys();
bool IsTruncated();
std::vector<std::string> GetCommonPrefixes();

其中 Content 的定义如下:

struct Content {
  std::string m_key; // Object 的 Key
  std::string m_last_modified; // Object 最后被修改时间
  std::string m_etag; // 文件的 MD-5 算法校验值
  std::string m_size; // 文件大小,单位是 Byte
  std::vector<std::string> m_owner_ids; // Bucket 持有者信息
  std::string m_storage_class; // Object 的存储类别,枚举值:STANDARD,STANDARD_IA
};

简单上传对象

功能说明

上传对象到指定的存储桶中。

方法原型

/// 通过 Stream 进行上传
CosResult PutObject(const PutObjectByStreamReq& req, PutObjectByStreamResp* resp)
/// 上传本地文件
CosResult PutObject(const PutObjectByFileReq& req, PutObjectByFileResp* resp)

请求示例

qcloud_cos::CosConfig config("./config.json");
qcloud_cos::CosAPI cos(config);
std::string bucket_name = "examplebucket-1250000000";
std::string object_name = "object_name";
// 简单上传(流)
{
  std::istringstream iss("put object");
  // request 的构造函数中需要传入 istream
  qcloud_cos::PutObjectByStreamReq req(bucket_name, object_name, iss);
  // 调用 Set 方法设置元数据或者 ACL 等
  req.SetXCosStorageClass("STANDARD_IA");
  // 关闭MD5校验,开启使用req.TurnOnComputeConentMd5(),默认情况开启
  req.TurnOffComputeConentMd5();
  qcloud_cos::PutObjectByStreamResp resp;
  qcloud_cos::CosResult result = cos.PutObject(req, &resp);

  if (result.IsSucc()) {
      // 调用成功,调用 resp 的成员函数获取返回内容
      do sth
  } else {
      // 调用失败,调用 result 的成员函数获取错误信息
      std::cout << "ErrorInfo=" << result.GetErrorInfo() << std::endl;
      std::cout << "HttpStatus=" << result.GetHttpStatus() << std::endl;
      std::cout << "ErrorCode=" << result.GetErrorCode() << std::endl;
      std::cout << "ErrorMsg=" << result.GetErrorMsg() << std::endl;
      std::cout << "ResourceAddr=" << result.GetResourceAddr() << std::endl;
      std::cout << "XCosRequestId=" << result.GetXCosRequestId() << std::endl;
      std::cout << "XCosTraceId=" << result.GetXCosTraceId() << std::endl;
   }
}
// 简单上传(文件)
{
  // request 的构造函数中需要传入本地文件路径
  qcloud_cos::PutObjectByFileReq req(bucket_name, object_name, "/path/to/local/file");
  // 调用 Set 方法设置元数据或者 ACL 等
  req.SetXCosStorageClass("STANDARD_IA");
  // 关闭 MD5 校验,开启使用 req.TurnOnComputeConentMd5(),默认情况开启
  req.TurnOffComputeConentMd5();
  qcloud_cos::PutObjectByFileResp resp;
  qcloud_cos::CosResult result = cos.PutObject(req, &resp);
      if (result.IsSucc()) {
      // 调用成功,调用 resp 的成员函数获取返回内容
      do sth
  } else {
      // 调用失败,调用 result 的成员函数获取错误信息
      std::cout << "ErrorInfo=" << result.GetErrorInfo() << std::endl;
      std::cout << "HttpStatus=" << result.GetHttpStatus() << std::endl;
      std::cout << "ErrorCode=" << result.GetErrorCode() << std::endl;
      std::cout << "ErrorMsg=" << result.GetErrorMsg() << std::endl;
      std::cout << "ResourceAddr=" << result.GetResourceAddr() << std::endl;
      std::cout << "XCosRequestId=" << result.GetXCosRequestId() << std::endl;
      std::cout << "XCosTraceId=" << result.GetXCosTraceId() << std::endl;
   }
}

参数说明

参数 参数描述 类型 是否必填
req PutObject 操作的请求 PutObjectByStreamReq/PutObjectByFileReq
resp PutObject 操作的响应 PutObjectByStreamResp/PutObjectByFileResp

参数 Req 包括如下成员函数:

// Cache-Control RFC 2616 中定义的缓存策略,将作为 Object 元数据保存
void SetCacheControl(const std::string& str);
// Content-Disposition RFC 2616 中定义的文件名称,将作为 Object 元数据保存
void SetContentDisposition(const std::string& str);
// Content-Encoding    RFC 2616 中定义的编码格式,将作为 Object 元数据保存-
void SetContentEncoding(const std::string& str);
// Content-Type    RFC 2616 中定义的内容类型(MIME),将作为 Object 元数据保存
void SetContentType(const std::string& str);
// Expect  当使用 Expect: 100-continue 时,在收到服务端确认后,才会发送请求内容
void SetExpect(const std::string& str);
// Expires RFC 2616 中定义的过期时间,将作为 Object 元数据保存
void SetExpires(const std::string& str);
// 允许用户自定义的头部信息,将作为 Object 元数据返回.大小限制2K
void SetXCosMeta(const std::string& key, const std::string& value);
// x-cos-storage-class 设置 Object 的存储级别,枚举值:STANDARD,STANDARD_IA,ARCHIVE
// 默认值:STANDARD
void SetXCosStorageClass(const std::string& storage_class);
// 定义 Object 的 ACL 属性,有效值:private,public-read
// 默认值:private
void SetXcosAcl(const std::string& str);
// 赋予被授权者读的权限.格式:x-cos-grant-read: id=" ",id=" ".
// 当需要给子账户授权时,id="qcs::cam::uin/<OwnerUin>:uin/<SubUin>"
// 当需要给根账户授权时,id="qcs::cam::uin/<OwnerUin>:uin/<OwnerUin>"
void SetXcosGrantRead(const std::string& str);
// 赋予被授权者读写权限.格式:x-cos-grant-full-control: id=" ",id=" ".
// 当需要给子账户授权时,id="qcs::cam::uin/<OwnerUin>:uin/<SubUin>",
// 当需要给根账户授权时,id="qcs::cam::uin/<OwnerUin>:uin/<OwnerUin>"
void SetXcosGrantFullControl(const std::string& str);
/// 设置Server端加密使用的算法, 目前支持AES256
void SetXCosServerSideEncryption(const std::string& str);

参数 Resp 包括如下成员函数:

/// 获取Object的版本号, 如果Bucket未开启多版本, 返回空字符串
std::string GetVersionId();
/// Server端加密使用的算法
std::string GetXCosServerSideEncryption();

查询对象元数据

功能说明

查询对象元数据信息。

方法原型

CosResult HeadObject(const HeadObjectReq& req, HeadObjectResp* resp)

请求示例

qcloud_cos::CosConfig config("./config.json");
qcloud_cos::CosAPI cos(config);
std::string bucket_name = "examplebucket-1250000000";
std::string object_name = "object_name";
qcloud_cos::HeadObjectReq req(bucket_name, object_name);
qcloud_cos::HeadObjectResp resp;
qcloud_cos::CosResult result = cos.HeadObject(req, &resp);
if (result.IsSucc()) {
  // 下载成功,可以调用 HeadObjectResp 的成员函数
} else {
  // 下载失败,可以调用 CosResult 的成员函数输出错误信息,例如 requestID 等
}

参数说明

参数 参数描述 类型 是否必填
req HeadObject 操作的请求 HeadObjectReq
resp HeadObject 操作的响应 HeadObjectResp

HeadObjectResp 除了读取公共头部的成员函数外,还提供以下成员函数:

std::string GetXCosObjectType();
std::string GetXCosStorageClass();
// 获取自定义的 meta, 参数可以为 x-cos-meta-* 中的 *
std::string GetXCosMeta(const std::string& key);
// 以 map 形式返回所有自定义的 meta, map 的 key 均不包含"x-cos-meta-"前缀
std::map<std::string, std::string> GetXCosMetas();
// 获取 Server 端加密使用的算法
std::string GetXCosServerSideEncryption(); 

下载对象

功能说明

下载对象到本地(Get Object)。

方法原型

// 将 Object 下载到本地文件中
CosResult GetObject(const GetObjectByFileReq& req, GetObjectByFileResp* resp)
// 将 Object 下载到流中
CosResult GetObject(const GetObjectByStreamReq& req, GetObjectByStreamResp* resp)
// 将 Object 下载到本地文件中(多线程)
CosResult GetObject(const MultiGetObjectReq& req, MultiGetObjectResp* resp)

请求示例

qcloud_cos::CosConfig config("./config.json");
qcloud_cos::CosAPI cos(config);
std::string bucket_name = "examplebucket-1250000000";
std::string object_name = "object_name";
std::string local_path = "/tmp/object_name";
// 下载到本地文件
{
  // request 需要提供 appid、bucketname、object,以及本地的路径(包含文件名)
  qcloud_cos::GetObjectByFileReq req(bucket_name, object_name, local_path);
  qcloud_cos::GetObjectByFileResp resp;
  qcloud_cos::CosResult result = cos.GetObject(req, &resp);
  if (result.IsSucc()) {
      // 下载成功,可以调用 GetObjectByFileResp 的成员函数
  } else {
      // 可以调用 CosResult 的成员函数输出错误信息,例如 requestID 等
  }
}
// 下载到流中
{
  // request 需要提供 appid、bucketname、object, 以及输出流
  std::ostringstream os;
  qcloud_cos::GetObjectByStreamReq req(bucket_name, object_name, os);
  qcloud_cos::GetObjectByStreamResp resp;
  qcloud_cos::CosResult result = cos.GetObject(req, &resp);
  if (result.IsSucc()) {
      // 下载成功,可以调用 GetObjectByStreamResp 的成员函数
  } else {
      // 下载失败,可以调用 CosResult 的成员函数输出错误信息,例如 requestID 等
  }
}
// 多线程下载文件到本地
{
  // request需要提供 appid、bucketname、object以及本地的路径(包含文件名)
  qcloud_cos::MultiGetObjectReq req(bucket_name, object_name, local_path);
  qcloud_cos::MultiGetObjectResp resp;
  qcloud_cos::CosResult result = cos.GetObject(req, &resp);
  if (result.IsSucc()) {
      // 下载成功,可以调用 MultiGetObjectResp 的成员函数
  } else {
      // 下载失败,可以调用 CosResult 的成员函数输出错误信息,例如 requestID 等
  }
}

参数说明

参数 参数描述 类型 是否必填
req GetObject 操作的请求 GetObjectByFileReq/GetObjectByStreamReq/MultiGetObjectReq
resp GetObject 操作的响应 GetObjectByFileResp/GetObjectByStreamResp/MultiGetObjectResp

成员函数如下:

// 设置响应头部中的 Content-Type 参数
void SetResponseContentType(const std::string& str);
// 设置响应头部中的 Content-Language 参数
void SetResponseContentLang(const std::string& str);
// 设置响应头部中的 Content-Expires 参数
void SetResponseExpires(const std::string& str);
// 设置响应头部中的 Cache-Control 参数
void SetResponseCacheControl(const std::string& str);
// 设置响应头部中的 Content-Disposition 参数
void SetResponseContentDisposition(const std::string& str);
// 设置响应头部中的 Content-Encoding 参数
void SetResponseContentEncoding(const std::string& str);

GetObjectResp 除了读取公共头部的成员函数外,还提供以下成员函数:

// 获取 Object 最后被修改的时间, 字符串格式 Date, 类似"Wed, 28 Oct 2014 20:30:00 GMT"
std::string GetLastModified();
// 获取 Object type, 表示 Object 是否可以被追加上传,枚举值:normal 或者 appendable
std::string GetXCosObjectType();
// 获取 Object 的存储类别,枚举值:STANDARD,STANDARD_IA
std::string GetXCosStorageClass();
// 以 map 形式返回所有自定义的 meta, map 的 key 均不包含"x-cos-meta-"前缀
std::map<std::string, std::string> GetXCosMetas();
// 获取自定义的 meta, 参数可以为 x-cos-meta-*中的*
std::string GetXCosMeta(const std::string& key);
// 获取Server端加密使用的算法
std::string GetXCosServerSideEncryption(); 

设置对象复制

复制文件到目标路径。

方法原型

CosResult PutObjectCopy(const PutObjectCopyReq& req, PutObjectCopyResp* resp)

请求示例

qcloud_cos::CosConfig config("./config.json");
qcloud_cos::CosAPI cos(config);
std::string bucket_name = "examplebucket-1250000000";
std::string object_name = "sevenyou";
qcloud_cos::PutObjectCopyReq req(bucket_name, object_name);                                                                                                                       
req.SetXCosCopySource("sevenyousouthtest-12345656.cn-south.myqcloud.com/sevenyou_source_obj");
qcloud_cos::PutObjectCopyResp resp;
qcloud_cos::CosResult result = cos.PutObjectCopy(req, &resp);

参数说明

参数 参数描述 类型 是否必填
req PutObjectCopy 操作的请求 PutObjectCopyReq
resp PutObjectCopy 操作的响应 PutObjectCopyResp

PutObjectCopyReq 包含以下成员函数:

// 源文件 URL 路径,可以通过 versionid 子资源指定历史版本
void SetXCosCopySource(const std::string& str);
// 是否拷贝元数据,枚举值:Copy, Replaced,默认值 Copy。
// 假如标记为 Copy,忽略 Header 中的用户元数据信息直接复制;
// 假如标记为 Replaced,按 Header 信息修改元数据。
// 当目标路径和原路径一致,即用户试图修改元数据时,必须为 Replaced
void SetXCosMetadataDirective(const std::string& str);
// 当 Object 在指定时间后被修改,则执行操作,否则返回 412。
// 可与 x-cos-copy-source-If-None-Match 一起使用,与其他条件联合使用返回冲突。
void SetXCosCopySourceIfModifiedSince(const std::string& str);
// 当 Object 在指定时间后未被修改,则执行操作,否则返回 412。
// 可与 x-cos-copy-source-If-Match 一起使用,与其他条件联合使用返回冲突。
void SetXCosCopySourceIfUnmodifiedSince(const std::string& str);
// 当 Object 的 Etag 和给定一致时,则执行操作,否则返回 412。
// 可与x-cos-copy-source-If-Unmodified-Since 一起使用,与其他条件联合使用返回冲突
void SetXCosCopySourceIfMatch(const std::string& str);
// 当 Object 的 Etag 和给定不一致时,则执行操作,否则返回 412。
// 可与 x-cos-copy-source-If-Modified-Since 一起使用,与其他条件联合使用返回冲突。
void SetXCosCopySourceIfNoneMatch(const std::string& str);
// x-cos-storage-class 设置 Object 的存储级别,枚举值:STANDARD,STANDARD_IA
// 默认值:STANDARD
void SetXCosStorageClass(const std::string& storage_class);
// 定义 Object 的 ACL 属性,有效值:private,public-read
// 默认值:private
void SetXCosAcl(const std::string& str);
// 赋予被授权者读的权限。格式:id="[OwnerUin]"  
void SetXCosGrantRead(const std::string& str);
// 赋予被授权者所有的权限。格式:id="[OwnerUin]"
void SetXCosGrantFullControl(const std::string& str);
// 允许用户自定义的头部信息,将作为 Object 元数据返回.大小限制2K
void SetXCosMeta(const std::string& key, const std::string& value);
/// 设置 Server 端加密使用的算法, 目前支持 AES256
void SetXCosServerSideEncryption(const std::string& str);

PutObjectCopyResp 包含以下成员函数:

// 返回文件的 MD5 算法校验值。ETag 的值可以用于检查 Object 的内容是否发生变化。
std::string GetEtag();
// 返回文件最后修改时间,GMT 格式
std::string GetLastModified();
// 返回版本号
std::string GetVersionId();
/// Server端加密使用的算法
std::string GetXCosServerSideEncryption();

删除单个对象

功能说明

在存储桶中删除指定对象。

方法原型

CosResult DeleteObject(const DeleteObjectReq& req, DeleteObjectResp* resp)

请求示例

qcloud_cos::CosConfig config("./config.json");
qcloud_cos::CosAPI cos(config);
std::string bucket_name = "examplebucket-1250000000";
std::string object_name = "test_object";
qcloud_cos::DeleteObjectReq req(bucket_name, object_name);
qcloud_cos::DeleteObjectResp resp;
qcloud_cos::CosResult result = cos.DeleteObject(req, &resp);
// 调用成功,调用 resp 的成员函数获取返回内容
if (result.IsSucc()) {
  // ...
} else {
  // 可以调用 CosResult 的成员函数输出错误信息,例如 requestID 等
} 

参数说明

参数 参数描述 类型 是否必填
req DeleteObject 操作的请求 DeleteObjectReq
resp DeleteObject 操作的响应 DeletObjectResp

删除多个对象

功能说明

在存储桶中批量删除对象。

方法原型

CosResult DeleteObjects(const DeleteObjectsReq& req, DeleteObjectsResp* resp)

请求示例

qcloud_cos::CosConfig config("./config.json");
qcloud_cos::CosAPI cos(config);
std::string bucket_name = "examplebucket-1250000000";
std::vector<std::string> objects;
std::vector<ObjectVersionPair> to_be_deleted;
objects.push_back("batch_delete_test_00");
objects.push_back("batch_delete_test_01");
objects.push_back("batch_delete_test_02");
objects.push_back("batch_delete_test_03");
for (size_t idx = 0; idx < objects.size(); ++idx) {
  ObjectVersionPair pair;
  pair.m_object_name = objects[idx];
  to_be_deleted.push_back(pair);
}
qcloud_cos::DeleteObjectsReq req(bucket_name, to_be_deleted);  
qcloud_cos::DeleteObjectsResp resp;                 
qcloud_cos::CosResult result = cos.DeleteObjects(req, &resp);
// 调用成功,调用 resp 的成员函数获取返回内容
if (result.IsSucc()) {
  // ...
} else {
  // 可以调用 CosResult 的成员函数输出错误信息,例如 requestID 等
} 

参数说明

参数 参数描述 类型 是否必填
req DeleteObjects 操作的请求 DeleteObjectsReq
resp DeleteObjects 操作的响应 DeletObjectsResp

DeleteObjectsReq 包含以下成员函数:

// 添加对象,并指定版本
void AddObjectVersion(const std::string& object, const std::string& version)
// 添加对象,非多版本
void AddObject(const std::string& object)

DeleteObjectsResp 包含以下成员函数:

// 获取删除成功的 objects 信息
std::vector<DeletedInfo> GetDeletedInfos() const
// 获取删除失败的 objects 信息
std::vector<ErrorInfo> GetErrorinfos() const

对应 DeletedInfo 和 ErrorInfo 的结构如下:

struct DeletedInfo{
  std::string m_key; // object key
}
struct ErrorInfo{
  std::string m_key; // object key
  std::string m_code; // error code
  std::string m_message; // error message
}

恢复归档对象

功能说明

将归档类型的对象取回访问。

方法原型

CosResult PostObjectRestore(const PostObjectRestoreReq& req, PostObjectRestoreResp* resp)

请求示例

qcloud_cos::CosConfig config("./config.json");
qcloud_cos::CosAPI cos(config);
std::string bucket_name = "examplebucket-1250000000";
std::string object_name = "sevenyou";
{   
  qcloud_cos::PostObjectRestoreReq req(bucket_name, object_name);
  req.SetExiryDays(30);
  req.SetTier("Standard");
  qcloud_cos::PostObjectRestoreResp resp;
  qcloud_cos::CosResult result = cos.PostObjectRestore(req, &resp);
  // 调用成功,调用 resp 的成员函数获取返回内容
  if (result.IsSucc()) {
      // ...
  } else {
      // 可以调用 CosResult 的成员函数输出错误信息,例如 requestID 等
  } 
}   

参数说明

参数 参数描述 类型 是否必填
req PostObjectRestore 操作的请求 PostObjectRestoreReq
resp PostObjectRestore 操作的响应 PostObjectRestoreResp

PostObjectRestoreReq 包含以下成员函数:

// 设置临时副本的过期时间
void SetExiryDays(uint64_t days);
// 枚举值: Expedited ,Standard ,Bulk;默认值:Standard
void SetTier(const std::string& tier);

分块操作

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

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

查询分块上传

功能说明

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

方法原型

CosResult CosAPI::ListMultipartUpload(const ListMultipartUploadReq& request, ListMultipartUploadResp* response)

请求示例

qcloud_cos::CosConfig config("./config.json");
qcloud_cos::CosAPI cos(config);
std::string bucket_name = "examplebucket-1250000000";
std::string object_name = "test_object";
qcloud_cos::ListMultipartUploadReq req(bucket_name, object_name);
qcloud_cos::ListMultipartUploadResp resp;
qcloud_cos::CosResult result = cos.ListMultipartUpload(req, &resp);
for (std::vector<qcloud_cos::Upload>::const_iterator itr = rst.begin(); itr != rst.end(); ++itr) {
  const qcloud_cos::Upload& upload = *itr;
  std::cout << "key = " << upload.m_key << ", uploadid= " << upload.m_uploadid << ", storagen class = " << upload.m_storage_class << ", m_initiated= " << upload.m_initiated << std::endl;
}   
// 调用成功,调用 resp 的成员函数获取返回内容
if (result.IsSucc()) {
  // ...
} else {
  // 可以调用 CosResult 的成员函数输出错误信息,例如 requestID 等
} 

参数说明

参数 参数描述 类型 是否必填
req ListMultipartUpload 操作的请求 ListMultipartUploadReq
resp ListMultipartUpload 操作的响应 ListMultipartUploadResp

ListMultipartUploadReq 成员函数:

// 限定返回的 Object key 必须以 Prefix 作为前缀。注意使用 prefix 查询时,返回的 key 中仍会包含 Prefix。
void SetPrefix(const std::string& prefix);
// 定界符为一个符号,对 Object 名字包含指定前缀且第一次出现 delimiter 字符之间的 Object 作为一组元素:common prefix。如果没有 prefix,则从路径起点开始
void SetDelimiter(const std::string& delimiter);
// 规定返回值的编码格式,合法值:url
void SetEncodingType(const std::string& encoding_type);
// 与 upload-id-marker 一起使用当 upload-id-marker 未被指定时,ObjectName 字母顺序大于 key-marker 的条目将被列出,当 upload-id-marker 被指定时,ObjectName 字母顺序大于 key-marker 的条目被列出,ObjectName 字母顺序等于 key-marker 同时 UploadID 大于 upload-id-marker 的条目将被列出。
void SetKeyMarker(const std::string& marker);
// 设置最大返回的 multipart 数量,合法取值从1到1000,默认1000
void SetMaxUploads(const std::string& max_uploads);
// 与 key-marker 一起使用,当 key-marker 未被指定时,upload-id-marker 将被忽略,当 key-marker 被指定时,ObjectName字母顺序大于 key-marker 的条目被列出,ObjectName 字母顺序等于 key-marker 同时 UploadID 大于 upload-id-marker 的条目将被列出。
void SetUploadIdMarker(const std::string& upload_id_marker);

ListMultipartUploadResp 成员函数:

// 获取Bucket中Object对应的元信息
std::vector<Upload> GetUpload();
// Bucket 名称
std::string GetName();
// 编码格式
std::string GetEncodingType() const// 默认以UTF-8二进制顺序列出条目,所有列出条目从marker开始
std::string GetMarker() const// 列出条目从该 UploadId 值开始
std::string GetUploadIdMarker() const// 假如返回条目被截断,则返回 NextKeyMarker 就是下一个条目的起点
std::string GetNextKeyMarker() const// 假如返回条目被截断,则返回 UploadId 就是下一个条目的起点
std::string GetNextUploadIdMarker() const// 最大返回的 multipart 数量,合法取值从0到1000
std::string GetMaxUploads () const// 响应请求条目是否被截断,布尔值:true,false
bool IsTruncated();
// 返回的文件前缀
std::string GetPrefix() const// 获取定界符 
std::string GetDelimiter() const// 将 Prefix 到 delimiter 之间的相同路径归为一类,定义为 Common Prefix
std::vector<std::string> GetCommonPrefixes() const

初始化分块上传

功能说明

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

方法原型

CosResult InitMultiUpload(const InitMultiUploadReq& req, InitMultiUploadResp* resp)

请求示例

qcloud_cos::CosConfig config("./config.json");
qcloud_cos::CosAPI cos(config);
std::string bucket_name = "examplebucket-1250000000";
std::string object_name = "object_name";
qcloud_cos::InitMultiUploadReq req(bucket_name, object_name);
qcloud_cos::InitMultiUploadResp resp;
qcloud_cos::CosResult result = cos.InitMultiUpload(req, &resp);
std::string upload_id = "";
if (result.IsSucc()) {
  upload_id = resp.GetUploadId();
}

参数说明

参数 参数描述 类型 是否必填
req InitMultiUpload 操作的请求 InitMultiUploadReq
resp InitMultiUpload 操作的响应 InitMultiUploadResp

InitMultiUploadReq 的成员函数如下:

// Cache-Control RFC 2616 中定义的缓存策略,将作为 Object 元数据保存
void SetCacheControl(const std::string& str);
// Content-Disposition RFC 2616 中定义的文件名称,将作为 Object 元数据保存
void SetContentDisposition(const std::string& str);
// Content-Encoding    RFC 2616 中定义的编码格式,将作为 Object 元数据保存-
void SetContentEncoding(const std::string& str);
// Content-Type    RFC 2616 中定义的内容类型(MIME),将作为 Object 元数据保存
void SetContentType(const std::string& str);
// Expires RFC 2616 中定义的过期时间,将作为 Object 元数据保存
void SetExpires(const std::string& str);
// 允许用户自定义的头部信息,将作为 Object 元数据返回.大小限制2K
void SetXCosMeta(const std::string& key, const std::string& value);
// x-cos-storage-class 设置 Object 的存储级别,枚举值:STANDARD,STANDARD_IA,ARCHIVE
// 默认值:STANDARD
void SetXCosStorageClass(const std::string& storage_class);
// 定义 Object 的 ACL 属性,有效值:private,public-read
// 默认值:private
void SetXcosAcl(const std::string& str);
// 赋予被授权者读的权限.格式:x-cos-grant-read: id=" ",id=" ".
// 当需要给子账户授权时,id="qcs::cam::uin/<OwnerUin>:uin/<SubUin>"
// 当需要给根账户授权时,id="qcs::cam::uin/<OwnerUin>:uin/<OwnerUin>"
void SetXcosGrantRead(const std::string& str);
// 赋予被授权者读写权限.格式:x-cos-grant-full-control: id=" ",id=" ".
// 当需要给子账户授权时,id="qcs::cam::uin/<OwnerUin>:uin/<SubUin>",
// 当需要给根账户授权时,id="qcs::cam::uin/<OwnerUin>:uin/<OwnerUin>"
void SetXcosGrantFullControl(const std::string& str);
/// 设置 Server 端加密使用的算法, 目前支持 AES256
void SetXCosServerSideEncryption(const std::string& str);

当成功执行此请求后,返回的 response 中会包含 bucket、key、uploadId, 分别表示分块上传的目标 Bucket、Object 名称以及后续分块上传所需的编号。

InitMultiUploadResp 的成员函数如下:

std::string GetBucket();
std::string GetKey();
std::string GetUploadId();
// Server端加密使用的算法
std::string GetXCosServerSideEncryption();

上传分块

上传分块(Upload Part)。

方法原型

CosResult UploadPartData(const UploadPartDataReq& request, UploadPartDataResp* response)

请求示例

qcloud_cos::CosConfig config("./config.json");
qcloud_cos::CosAPI cos(config);
std::string bucket_name = "examplebucket-1250000000";
std::string object_name = "test_object";
// 上传第一个分块
{
  std::fstream is("demo_5M.part1");
  qcloud_cos::UploadPartDataReq req(bucket_name, object_name, upload_id, is);
  req.SetPartNumber(1);
  // 关闭 MD5 校验,开启使用 req.TurnOnComputeConentMd5(),默认情况开启
  req.TurnOffComputeConentMd5();
  qcloud_cos::UploadPartDataResp resp;
  qcloud_cos::CosResult result = cos.UploadPartData(req, &resp);
   // 上传成功需要记录分块编号以及返回的 ETag
  if (result.IsSucc()) {
      etags.push_back(resp.GetEtag());
      part_numbers.push_back(1);
  }
  is.close();
}
// 上传第二个分块
{
  std::fstream is("demo_5M.part2");
  qcloud_cos::UploadPartDataReq req(bucket_name, object_name,
                                    upload_id, is);
  req.SetPartNumber(2);
  qcloud_cos::UploadPartDataResp resp;
  qcloud_cos::CosResult result = cos.UploadPartData(req, &resp);
   // 上传成功需要记录分块编号以及返回的 ETag 
  if (result.IsSucc()) {
      etags.push_back(resp.GetEtag());
      part_numbers.push_back(2);
  }
  is.close();
}

参数说明

参数 参数描述 类型 是否必填
req UploadPartData 操作的请求 UploadPartDataReq
resp UploadPartData 操作的响应 UploadPartDataResp

UploadPartDataReq 在构造时,需要指明请求的 APPID、Bucket、Object、初始化成功后获取的 UploadId,以及上传的数据流(调用完成后,流由调用方自己负责关闭)。

UploadPartDataReq(const std::string& bucket_name,
                  const std::string& object_name, const std::string& upload_id,
                  std::istream& in_stream);

此外,请求还需要设置分块编号, 这个分块在完成分块上传时也会用到。

void SetPartNumber(uint64_t part_number);

UploadPartDataResp 的成员函数如下:

/// Server 端加密使用的算法
std::string GetXCosServerSideEncryption();

复制分块

将其他对象复制为一个分块。

方法原型

CosResult UploadPartCopyData(const UploadPartCopyDataReq& request,UploadPartCopyDataResp* response)

请求示例

qcloud_cos::CosConfig config("./config.json");
qcloud_cos::CosAPI cos(config);
std::string bucket_name = "examplebucket-1250000000";
std::string object_name = "test_object";
std::string upload_id;
std::vector<uint64_t> numbers;
std::vector<std::string> etags;
std::string etag1 = "", etag2 = "";
InitMultiUpload(cos, bucket_name, object_name, &upload_id);
// First part
qcloud_cos::UploadPartCopyDataReq req(bucket_name, object_name, upload_id, 1);
req.SetXCosCopySource("sevenyousouth-1251668577.cos.ap-guangzhou.myqcloud.com/seven_10G.tmp");
req.SetXCosCopySourceRange("bytes=0-1048576000");
qcloud_cos::UploadPartCopyDataResp resp;
qcloud_cos::CosResult result = cos.UploadPartCopyData(req, &resp);
if(result.IsSucc()) {
  etag1 = resp.GetEtag();
}
numbers.push_back(1);
etags.push_back(etag1);
// Second part
qcloud_cos::UploadPartCopyDataReq req2(bucket_name, object_name, upload_id, 2);                                                       
req2.SetXCosCopySource("sevenyoutest-7319456.cos.cn-north.myqcloud.com/sevenyou_2G_part");
req2.SetXCosCopySourceRange("bytes=1048576000-2097152000");
qcloud_cos::UploadPartCopyDataResp resp2;
qcloud_cos::CosResult result = cos.UploadPartCopyData(req2, &resp2);
if(result.IsSucc()) {
  etag2 = resp2.GetEtag();
}
numbers.push_back(2);
etags.push_back(etag2);
CompleteMultiUpload(cos, bucket_name, object_name, upload_id, etags, numbers);

参数说明

参数 参数描述 类型 是否必填
req UploadPartCopyData 操作的请求 UploadPartCopyDataReq
resp UploadPartCopyData 操作的响应 UploadPartCopyDataResp
/// 设置本次分块复制的 ID
void SetUploadId(const std::string& upload_id)
/// 设置本次分块复制的编号
void SetPartNumber(uint64_t part_number)
/// 设置本次分块复制的源文件 URL 路径,可以通过 versionid 子资源指定历史版本
void SetXCosCopySource(const std::string& src)
/// 设置源文件的字节范围,范围值必须使用 bytes=first-last 格式。
void SetXCosCopySourceRange(const std::string& range)
/// 当 Object 在指定时间后被修改,则执行操作,否则返回 412
void SetXCosCopySourceIfModifiedSince(const std::string& date)
/// 当 Object 在指定时间后未被修改,则执行操作,否则返回 412
void SetXCosCopySourceIfUnmodifiedSince(const std::string& date)
/// 当 Object 的 Etag 和给定一致时,则执行操作,否则返回 412 
void SetXCosCopySourceIfMatch(const std::string& etag)
/// 当 Object 的 Etag 和给定不一致时,则执行操作,否则返回 412
void SetXCosCopySourceIfNoneMatch(const std::string& etag)
/// 获取返回文件的MD5算法校验值。
std::string GetEtag() const
/// 返回文件最后修改时间,GMT 格式
std::string GetLastModified() const
/// Server端加密使用的算法
std::string GetXCosServerSideEncryption() const

查询已上传块

功能说明

查询特定分块上传操作中的已上传的块。

方法原型

CosResult ListParts(const ListPartsReq& req, ListPartsResp* resp)

请求示例

qcloud_cos::CosConfig config("./config.json");
qcloud_cos::CosAPI cos(config);
std::string bucket_name = "examplebucket-1250000000";
std::string object_name = "test_object";
// uploadId 是调用 InitMultiUpload 后获取的
qcloud_cos::ListPartsReq req(bucket_name, object_name, upload_id);
req.SetMaxParts(1);                                                                                                                                                               
req.SetPartNumberMarker("1");
qcloud_cos::ListPartsResp resp;
qcloud_cos::CosResult result = cos.ListParts(req, &resp);
// 调用成功,调用 resp 的成员函数获取返回内容
if (result.IsSucc()) {
  // ...
} else {
  // 可以调用 CosResult 的成员函数输出错误信息,例如 requestID 等
} 

参数说明

参数 参数描述 类型 是否必填
req ListParts 操作的请求 ListPartsReq
resp ListParts 操作的响应 ListPartsResp

ListPartsReq 包含以下成员函数:

// 构造函数,Bucket 名、Object 名、分块上传的 ID
ListPartsReq(const std::string& bucket_name,                                                                                                                                      
           const std::string& object_name,
           const std::string& upload_id); 
// \brief 规定返回值的编码方式
void SetEncodingType(const std::string& encoding_type);
// \brief 单次返回最大的条目数量,若不设置,默认1000
void SetMaxParts(uint64_t max_parts);
// \brief 默认以 UTF-8 二进制顺序列出条目,所有列出条目从 marker 开始
void SetPartNumberMarker(const std::string& part_number_marker);

ListPartsResp 包含以下成员函数:

// 分块上传的目标 Bucket
std::string GetBucket();
// 规定返回值的编码方式
std::string GetEncodingType();
// Object 的名称
std::string GetKey();
// 标识本次分块上传的 ID
std::string GetUploadId();
// 用来表示本次上传发起者的信息
Initiator GetInitiator();
// 用来表示这些分块所有者的信息
Owner GetOwner();
// 默认以 UTF-8 二进制顺序列出条目,所有列出条目从 marker 开始
uint64_t GetPartNumberMarker();
// 返回每一个块的信息
std::vector<Part> GetParts();
// 假如返回条目被截断,则返回 NextMarker 就是下一个条目的起点
uint64_t GetNextPartNumberMarker();
// 用来表示这些分块的存储级别,枚举值:Standard,Standard_IA,ARCHIVE
std::string GetStorageClass();
// 单次返回最大的条目数量
uint64_t GetMaxParts();
// 返回条目是否被截断,布尔值:TRUE,FALSE
bool IsTruncated();

其中 Part、Owner、Initiator 的定义如下:

struct Initiator {
  std::string m_id; // 创建者的一个唯一标识
  std::string m_display_name; // 创建者的用户名描述
};
struct Owner {
  std::string m_id; // 用户的一个唯一标识
  std::string m_display_name; // 用户名描述
};
struct Part {
  uint64_t m_part_num; // 块的编号
  uint64_t m_size; // 块大小,单位 Byte
  std::string m_etag; // Object 块的 MD5 算法校验值
  std::string m_last_modified; // 块最后修改时间
};

完成分块上传

功能说明

完成整个文件的分块上传。

方法原型

CosResult CompleteMultiUpload(const CompleteMultiUploadReq& request, CompleteMultiUploadResp* response)

请求示例

qcloud_cos::CompleteMultiUploadReq req(bucket_name, object_name, upload_id);
qcloud_cos::CompleteMultiUploadResp resp;
req.SetEtags(etags);
req.SetPartNumbers(part_numbers);
qcloud_cos::CosResult result = cos.CompleteMultiUpload(req, &resp);

参数说明

参数 参数描述 类型 是否必填
req CompleteMultiUpload 操作的请求 CompleteMultiUploadReq
resp CompleteMultiUpload 操作的响应 CompleteMultiUploadResp

CompleteMultiUploadReq 在构造时,需要指明请求的 APPID、Bucket、Object、初始化成功后获取的 UploadId。

CompleteMultiUploadReq(const std::string& bucket_name,
                     const std::string& object_name, const std::string& upload_id)

此外,request 还需要设置所有上传的分块编号和 ETag。

// 调用下列方法时,应注意编号和 ETag 的顺序必须一一对应
void SetPartNumbers(const std::vector<uint64_t>& part_numbers);
void SetEtags(const std::vector<std::string>& etags) ;
// 添加 part_number 和 ETag 对
void AddPartEtagPair(uint64_t part_number, const std::string& etag);
/// 设置 Server 端加密使用的算法, 目前支持 AES256
void SetXCosServerSideEncryption(const std::string& str);

CompleteMultiUploadResp 的返回内容中包括 Location、Bucket、Key、ETag,分别表示创建的 Object 的外网访问域名、分块上传的目标 Bucket、Object 的名称、合并后文件的 MD5 算法校验值。可以调用下列成员函数对 response 中的内容进行访问。

std::string GetLocation();
std::string GetKey();
std::string GetBucket();
std::string GetEtag();
// Server端加密使用的算法
std::string GetXCosServerSideEncryption();

终止分块上传

功能说明

终止一个分块上传操作并删除已上传的块。

方法原型

CosResult AbortMultiUpload(const AbortMultiUploadReq& request, AbortMultiUploadResp* response)

请求示例

qcloud_cos::AbortMultiUploadReq req(bucket_name, object_name, upload_id);
qcloud_cos::AbortMultiUploadResp resp;
qcloud_cos::CosResult result = cos.AbortMultiUpload(req, &resp);

参数说明

参数 参数描述 类型 是否必填
req AbortMultiUpload 操作的请求 AbortMultiUploadReq
resp AbortMultiUpload 操作的响应 AbortMultiUploadResp

AbortMultiUploadReq 需要在构造的时候指明 Bucket、Object 以及 Upload_id。

AbortMultiUploadReq(const std::string& bucket_name,
                  const std::string& object_name, const std::string& upload_id);

无特殊方法,可调用 BaseResp 的成员函数来获取公共头部内容。

高级接口(推荐)

复合上传

功能说明

封装分块上传各接口,并发上传。

方法原型

CosResult MultiUploadObject(const MultiUploadObjectReq& request, MultiUploadObjectResp* response)

请求示例

qcloud_cos::CosConfig config("./config.json");
qcloud_cos::CosAPI cos(config);
std::string bucket_name = "examplebucket-1250000000";
std::string object_name = "exampleobject";
std::string local_file = "./test"
qcloud_cos::MultiUploadObjectReq req(bucket_name, object_name, local_file);
// Complete 接口内部 chunk 保活,建议设置较长时间的 timeout。
req.SetRecvTimeoutInms(1000 * 60);
qcloud_cos::MultiUploadObjectResp resp;
qcloud_cos::CosResult result = cos.MultiUploadObject(req, &resp);
// 调用成功,调用 resp 的成员函数获取返回内容
if (result.IsSucc()) {
  // ...
} else {
  // 可以调用 CosResult 的成员函数输出错误信息,例如 requestID 等
} 

参数说明

参数 参数描述 类型 是否必填
req MultiUploadObject 操作的请求 MultiUploadObjectReq
resp MultiUploadObject 操作的响应 MultiUploadObjectResp

MultiUploadObjectReq 包含以下成员函数:

// 设置分块大小,若小于1M,则按1M计算;若大于5G,则按5G计算
void SetPartSize(uint64_t bytes)
// 允许用户自定义的头部信息,将作为 Object 元数据返回,大小限制2K 
void SetXCosMeta(const std::string& key, const std::string& value)
// 设置 Server 端加密使用的算法,目前支持 AES256
void SetXCosServerSideEncryption(const std::string& str)
// 设置内部线程池大小
void SetThreadPoolSize(int size)

MultiUploadObjectResp 包含以下成员函数:

std::string GetRespTag()
/// Server 端加密使用的算法 
std::string GetXCosServerSideEncryption() const

复合下载

功能说明

并发 Range 下载。

方法原型

CosResult GetObject(const MultiGetObjectReq& request, 
MultiGetObjectResp* response)

请求示例

qcloud_cos::CosConfig config("./config.json");
qcloud_cos::CosAPI cos(config);
std::string bucket_name = "examplebucket-1250000000";
std::string object_name = "exampleobject";
std::string file_path = "./test";
qcloud_cos::MultiGetObjectReq req(bucket_name, object_name, file_path);  
qcloud_cos::MultiGetObjectResp resp;                                    
qcloud_cos::CosResult result = cos.GetObject(req, &resp); 
// 调用成功,调用 resp 的成员函数获取返回内容
if (result.IsSucc()) {
  // ...
} else {
  // 可以调用 CosResult 的成员函数输出错误信息,例如 requestID 等
} 

参数说明

参数 参数描述 类型 是否必填
req MultiGetObject 操作的请求 MultiGetObjectReq
resp MultiGetObject 操作的响应 MultiGetObjectResp

MultiGetObjectReq 包含以下成员函数:

// 设置分块大小
void SetSliceSize(uint64_t bytes)
// 设置线程池大小
void SetThreadPoolSize(int size)

MultiGetObjectResp 包含以下成员函数:

/// Server 端加密使用的算法
std::string GetXCosServerSideEncryption() const
目录