上传文件
上传文件
在BOS中,用户操作的基本数据单元是Object。Object包含Key、Meta和Data。其中,Key是Object的名字;Meta是用户对该Object的描述,由一系列Name-Value对组成;Data是Object的数据。
BOS C++ SDK提供了丰富的文件上传接口,可以通过以下方式上传文件:
- 简单上传
- 追加上传
- 分块上传
- 断点续传上传
简单上传
BOS在简单上传的场景中,支持以指定文件形式、以数据流方式、以文件描述符方式、以字符串方式执行Object上传,请参考如下代码:
int PutObjectDemo(Client& client,const std::string& bucketName, const std::string objectKey){
// 获取文件数据流
FileInputStream inputStream("/path/to/test.zip"); // bcesdk/util/util.h
int ret = 0;
// 以文件名作为参数上传Object
ret = client.upload_file(bucketName, objectKey, "/path/to/test.zip");
// 以数据流形式上传Object
ret = client.upload_file(bucketName, objectKey, inputStream);
// 以文件描述符形式上传Object
fd_t fd = open("/path/to/test.zip", O_RDWR, 0666);//linux下,fd_t在common.h中定义
ret = client.upload_file(bucketName, objectKey, fd);
// 以字符串形式上传Object
std::string data = "this is data";
ret = client.put_object(bucketName, objectKey, data);
return ret;
}
Object以文件的形式上传到BOS中,put_object、upload_file函数支持不超过5GB的Object上传。若要支持大文件(大于5G的文件)上传请使用upload_super_file,参考代码如下:
int PutLargeObjectDemo(Client& client,const std::string& bucketName, const std::string objectKey){
std::string fileName = "/path/to/test.zip"
return client.upload_super_file(bucketName, objectKey, fileName);//第三个参数用fd_t形式也可行
}
设置文件元信息
文件元信息(Object Meta),是对用户在向BOS上传文件时,同时对文件进行的属性描述,主要分为分为两种:设置HTTP标准属性(HTTP Headers)和用户自定义的元信息。
- 设定Object的Http Header
BOS C++ SDK本质上是调用后台的HTTP接口,因此用户可以在上传文件时自定义Object的Http Header。常用的http header说明如下:
名称 | 描述 | 默认值 |
---|---|---|
Content-MD5 | 文件数据校验,设置后BOS会启用文件内容MD5校验,把您提供的MD5与文件的MD5比较,不一致会抛出错误 | 无 |
Content-Type | 文件的MIME,定义文件的类型及网页编码,决定浏览器将以什么形式、什么编码读取文件。如没有指,BOS则根据文件的扩展名自动生成,如文件没有扩展名则填默认值 | application/octet-stream |
Content-Disposition | 指示MIME用户代理如何显示附加的文件,打开或下载,及文件名称 | 无 |
Content-Length | 上传的文件的长度,超过流/文件的长度会截断,不足为实际值 | 流/文件时间长度 |
Expires | 缓存过期时间 | 无 |
Cache-Control | 指定该Object被下载时的网页的缓存行为 | 无 |
参考代码如下:
...
// 初始化meta
ObjectMetaData meta;
// 设置ContentType
meta.set_content_type("application/json");
// 设置cache-control
meta.set_cache_control("no-cache");
// 设置x-bce-storage-class
meta.set_storage_class("STANDARD");
ret = client.upload_file(bucketName, objectKey, content, meta);
...
- 用户自定义元信息
BOS支持用户自定义元数据来对Object进行描述。如下代码所示:
// 设置自定义元数据name的值为my-data
meta.set_user_meta("name", "my-data");
// 上传Object
ret = client.upload_file(bucketName, objectKey, file_name, meta);
提示:
- 在上面代码中,用户自定义了一个名字为”name”,值为”my-data”的元数据
- 当用户下载此Object的时候,此元数据也可以一并得到
- 一个Object可以有多个类似的参数,但所有的User Meta总大小不能超过2KB
设置Object的Copy属性
BOS同时会提供CopyObject接口用于将一个已经存在的Object拷贝到另外一个Object,拷贝过程中会对源Object的Etag或修改状态进行判断,根据判断结果决定是否执行拷贝。详细的参数解释如下:
名称 | 类型 | 描述 | 是否必需 |
---|---|---|---|
x-bce-copy-source-if-match | std::string | 如果源Object的ETag值和用户提供的ETag相等,则执行拷贝操作,否则拷贝失败。 | 否 |
x-bce-copy-source-if-none-match | std::string | 如果源Object的ETag和用户提供的ETag不相等,则执行拷贝操作,否则拷贝失败。 | 否 |
x-bce-copy-source-if-unmodified-since | std::string | 如果源object在x-bce-copy-source-if-unmodified-since之后没被修改,则执行拷贝操作,否则拷贝失败。 | 否 |
x-bce-copy-source-if-modified-since | std::string | 如果源object在x-bce-copy-source-if-modified-since之后被修改了,则执行拷贝操作,否则拷贝失败。 | 否 |
对应的示例代码:
// 初始化BosClient
Client client = ...;
// 创建CopyObjectRequest对象
CopyObjectRequest copyObjectRequest(destBucketName, destKey, srcBucketName, srcKey);
CopyObjectResponse copyObjectResponse;
// 设置新的Metadata
StringMap& userMetadata = *(meta.mutable_user_meta());//StringMap == map<string, string>
userMetadata.clear();
userMetadata["<user-meta-key>"] = "<user-meta-value>";
copyObjectRequest.set_meta(&meta, false);//第二个参数(is_own)若为true则由copyObjectRequest析构时delete meta
//copy-source-if-match
copyObjectRequest.set_if_match("111111111183bf192b57a4afc76fa632");
//copy-source-if-none-match
copyObjectRequest.set_if_none_match("111111111183bf192b57a4afc76fa632");
std::string gmtDate = TimeUtil::now_gmttime();//当前GMT格式时间
//copy-source-if-modified-since
copyObjectRequest.set_if_modified_since(gmtDate);
//copy-source-if-unmodified-since
copyObjectRequest.set_if_unmodified_since(gmtDate);
// 复制Object
client.copy_object(copyObjectRequest, copyObjectResponse;);
std::cout << "ETag: " << copyObjectResponse.etag() << " LastModified: " << copyObjectResponse.last_modified() << std::endl;
上传Object时设置存储类型
BOS支持标准存储, 低频存储和冷存储,上传Object并存储为低频存储类型通过指定StorageClass实现,三种存储类型对应的参数如下:
存储类型 | 参数 |
---|---|
标准存储 | STANDARD |
低频存储 | STANDARD_IA |
冷存储 | COLD |
归档存储 | ARCHIVE |
以低频存储为例,代码如下:
void print_common_response(BceResponse &result) {
printf("status:%d\n", result.status_code());
if (result.is_ok()) {
printf("request-id:%s\n", result.request_id().c_str());
printf("debug-id:%s\n", result.debug_id().c_str());
}
if (result.is_fail()) {
printf("error-message:%s\n", result.error().message().c_str());
}
}
int putObjectStorageClass(){
std::string filename = "file.txt";
FileInputStream file(filename);
PutObjectRequest request(bucket, object, &file);
request.mutable_meta()->set_storage_class("STANDARD_IA");
PutObjectResponse result;
client.put_object(request, &result);
print_common_response(result);
printf("etag: %s\n", result.etag().c_str());
}
使用上传进度条
// 上传进度回调函数
// 注意该回调函数中不得出现耗时较长/阻塞操作, 会影响数据上传性能.
// increment: 当次上传的数据量
// transfered: 已上传数据量
// total: 需上传的数据总量
// userData: 用户自定义数据, 例如object bucket+key等.
void progress_callback(int64_t increment, int64_t transfered, int64_t total, void* user_data) {
std::cout << "progress_callback[" << user_data << "] => " <<
increment <<" ," << transfered << "," << total << std::endl;
}
//待上传文件
std::string filename = "/tmp/put_file_test";
FileInputStream file(filename);
PutObjectRequest req(BUCKET, "transfer_progress_t1", &file);
PutObjectResponse rsp;
// 设置上传进度相关数据
// TransferProgress结构在头文件: "bcesdk/common/common.h"
TransferProgress progress;
progress.transfer_progress_cb = progress_callback;
req.set_progress(progress);
//将filename文件中数据上传
int ret = client()->put_object(req, &rsp);
if (ret) {
LOGF(WARN, "client err: %d", ret);
}
if (rsp.is_fail()) {
LOGF(WARN,
"put_object: [status_code = %d], [message = %s], [requestid = %s]",
rsp.status_code(),
rsp.error().message().c_str(),
rsp.error().request_id().c_str());
}
追加上传
上文介绍的简单上传方式,创建的Object都是Normal类型,用户不可再进行追加写,这在日志、视频监控、视频直播等数据复写较频繁的场景中使用不方便。
正因如此,百度智能云BOS特别支持了AppendObject,即以追加写的方式上传文件。通过AppendObject操作创建的Object类型为Appendable Object,可以对该Object追加数据。AppendObject大小限制为0~5G。
通过AppendObject方式上传示例代码如下:
int AppendObjectDemo(Client& client,const std::string& bucketName, const std::string& objectKey) {
// 获取数据流
FileInputStream inputStream("/path/to/test.zip");
// 以数据流形式上传Object
AppendObjectRequest appendObjectFromInputStreamRequest(bucketName, objectKey, &inputStream);
AppendObjectResponse appendObjectFromInputStreamResponse;
int ret = client.append_object(appendObjectFromInputStreamRequest, &appendObjectFromInputStreamResponse);
// 以字符串上传Object
std::string data = "this is data";
AppendObjectRequest appendObjecFromStringtRequest(bucketName, objectKey, data);
AppendObjectResponse appendObjectFromStringResponse;
ret = client.append_object(appendObjecFromStringtRequest, &appendObjectFromStringResponse);
// 打印ETag
std::cout << appendObjectFromInputStreamResponse.etag() << std::endl;
// 打印NextAppendOffset
std::cout << appendObjectFromInputStreamResponse.next_append_offset() << std::endl;
// 追加上传的示例,需要在请求中加上下次追加写的位置
long long nextAppendOffset = appendObjectFromInputStreamResponse.next_append_offset();
AppendObjectRequest appendObjectFromStringRequest(bucketName,objectKey,data);
appendObjectFromStringRequest.set_offset(nextAppendOffset);
AppendObjectResponse appendObjectFromStringResponse;
ret = client.append_object(appendObjectFromStringRequest, &appendObjectFromStringResponse);
return ret;
}
分块上传
除了通过简单上传及追加上传方式将文上传件到BOS以外,BOS还提供了另外一种上传模式 —— Multipart Upload。用户可以在如下的应用场景内(但不仅限于此),使用Multipart Upload上传模式,如:
- 需要支持断点上传。
- 上传超过5GB大小的文件。
- 网络条件较差,和BOS的服务器之间的连接经常断开。
- 需要流式地上传文件。
- 上传文件之前,无法确定上传文件的大小。
下面将一步步介绍Multipart Upload的实现。假设有一个文件,本地路径为 /path/to/file.zip
,由于文件比较大,将其分块传输到BOS中。
初始化Multipart Upload
使用 initiateMultipartUpload
方法来初始化一个分块上传事件:
// 开始Multipart Upload
InitMultiUploadRequest initMultiUploadRequest(bucketName, objectKey);
InitMultiUploadResponse initMultiUploadResponse;
int ret = client.init_multipart_upload(initMultiUploadRequest, &initMultiUploadResponse);
//异常处理
...
// 打印UploadId
std::cout << "UploadId: " << initMultiUploadResponse.upload_id() << std::endl;
initMultiUploadResponse
的返回结果中含有 UploadId
,它是区分分块上传事件的唯一标识,在后面的操作中,我们将用到它。
- 上传低频存储类型Object的初始化
初始化低频存储的一个分块上传事件:
void putMultiUploadStorageClass(){
ObjectMetaData meta;
meta.set_storage_class("STANDARD_IA");
InitMultiUploadRequest initMultiUploadRequest(bucketName, objectKey);
InitMultiUploadResponse initMultiUploadResponse;
initMultiUploadRequest.set_meta(&meta);
client.init_multipart_upload(initMultiUploadRequest, &initMultiUploadResponse);
}
- 上传冷存储类型Object的初始化
初始化低频存储的一个分块上传事件:
void putMultiUploadStorageClass(){
ObjectMetaData meta;
meta.set_storage_class("COLD)");
InitMultiUploadRequest initMultiUploadRequest(bucketName, objectKey);
InitMultiUploadResponse initMultiUploadResponse;
initMultiUploadRequest.set_meta(&meta);
client.init_multipart_upload(initMultiUploadRequest, &initMultiUploadResponse);
}
上传分块
接着,把文件分块上传。
// 设置每块为 5MB
// [注意] 除了最后一个分块, 其余分块需满足size>=100kb
long partSize = 1024 * 1024 * 5L;
// 注意: 当分块上传的数据为string/内存数据, UploadPartRequest的构造函数如下:
// UploadPartRequest(const std::string &bucket_name, const std::string &object_name, const std::string &data, int part_number, const std::string &upload_id)
// 其中data字段为std::string, 不得传入C风格的char*串, 会导致计算数据size错误.
//待分块上传文件
std::string partFileName = "/path/to/file.zip";
FileInputStream file(partFileName);
// 计算分块数目
int partCount = static_cast<int>(file.get_size() / partSize);
if (file.get_size() % partSize != 0){
partCount++;
}
int64_t size = file.size();
int64_t off = 0;
for (int i = 0; off < file.size(); ++i) {
if (off + partSize > size) {
partSize = size - off;
}
FileInputStream partFile(file.fd(), off, partSize);
UploadPartRequest uploadPartRequest = UploadPartRequest(bucketName, objectName, partFile, i + 1, initMultiUploadResponse.upload_id());
UploadPartResponse uploadPartResponse;
int ret = client.upload_part(uploadPartRequest, &uploadPartResponse);
//校验返回值
// 将返回的PartETag保存到List中。
part_t partInfo;
partInfo.part_number = i+1;
partInfo.etag = uploadPartResponse.etag();
partEtags.push_back(partInfo);
off += partSize;
}
上面代码的核心是调用 upload_part
方法来并发的上传每一个分块,但是要注意以下几点:
upload_part
要求除最后一个Part以外,其他的Part大小都要大于等于100KB。但是Upload Part接口并不会立即校验上传Part的大小;只有当Complete Multipart Upload的时候才会校验, 若upload_part流程中的块大小不符合预期, 则complete_multipart_upload
接口会报错。- 为了保证数据在网络传输过程中不出现错误,建议您在
upload_part
后,使用每个分块BOS返回的Content-MD5值分别验证已上传分块数据的正确性。当所有分块数据合成一个Object后,不再含MD5值。 - Part号码的范围是1~10000。如果超出这个范围,BOS将返回InvalidArgument的错误码。
- 每次上传Part时都要把流定位到此次上传块开头所对应的位置。
- 每次上传Part之后,BOS的返回结果会包含一个
ETag
对象,它是上传块的ETag与块编号(PartNumber)的组合,在后续完成分块上传的步骤中会用到它,因此需要将其保存起来。一般来讲这些ETag
对象将被保存到vector中。
完成分块上传
如下代码所示,完成分块上传:
CompleteMultipartUploadRequest completeMultipartUploadRequest(bucketName, objectKey, initMultiUploadResponse.upload_id());
//添加part信息,即part合并顺序
for (part_t partInfo : partEtags) {
completeMultipartUploadRequest.add_part(partInfo.part_number, partInfo.etag);
}
// 完成分块上传
CompleteMultipartUploadResponse completeMultipartUploadResponse;
int ret = client.complete_multipart_upload(completeMultipartUploadRequest, &completeMultipartUploadResponse);
// 打印Object的ETag
std::cout << completeMultipartUploadResponse.etag() << std::endl;
上面代码中的 partETags
是第二部中保存的part_t的列表,BOS收到用户提交的Part列表后,会逐一验证每个数据Part的有效性。当所有的数据Part验证通过后,BOS将把这些数据part组合成一个完整的Object。
取消分块上传事件
用户可以使用abortMultipartUpload方法取消分块上传。
AbortMultipartUploadRequest abortMultipartUploadRequest(bucketName, objectKey, uploadId);
AbortMultipartUploadResponse abortMultipartUploadResponse;
// 取消分块上传
int ret = client.abort_multipart_upload(abortMultipartUploadRequest, &abortMultipartUploadResponse);
获取未完成的分块上传事件
用户可以使用 list_multipart_uploads
方法获取Bucket内未完成的分块上传事件。
ListMultipartUploadsRequest listMultipartUploadsRequest(bucketName);
ListMultipartUploadsResponse listMultipartUploadsResponse;
// 获取Bucket内所有上传事件
int ret = client.list_multipart_uploads(listMultipartUploadsRequest, &
listMultipartUploadsResponse);
if (ret != 0) {
return ret;
}
// 遍历所有上传事件
for (const MultipartUploadSummary& multipartUpload : listMultipartUploadsResponse.uploads()) {
std::cout << "Key: " << multipartUpload.key <<
" UploadId: " << multipartUpload.upload_id << std::endl;
}
注意:
- 默认情况下,如果Bucket中的分块上传事件的数目大于1000,则只会返回1000个Object,并且返回结果中is_truncated的值为True,同时返回next_marker作为下次读取的起点。
- 若想返回更多分块上传事件的数目,可以使用set_marker函数设置marker分次读取。
获取所有已上传的块信息
用户可以使用 listParts
方法获取某个上传事件中所有已上传的块。
ListPartsRequest listPartsRequest(bucketName, objectKey, uploadId);
// 获取上传的所有Part信息
ListPartsResponse listPartsResponse;
int ret = client.list_parts(listPartsRequest, &listPartsResponse);
if (ret != 0) {
return ret;
}
// 遍历所有Part
for (consr PartSummary& part : listPartsResponse.parts()) {
std::cout << "PartNumber: " << part.part_number << " ETag: " << part.etag;
}
如果需要查看Object的存储类型storage class使用以下代码:
public void listPartsStorageClass(){
ListPartsRequest listPartsRequest(bucketName, objectKey, uploadId);
// 获取上传的所有Part信息
ListPartsResponse listPartsResponse;
int ret = client.list_parts(listPartsRequest, &listPartsResponse);
if (ret != 0) {
return ret;
}
std::string storageClass = listPartsResponse.storage_class();
}
断点续传上传
当用户向BOS上传大文件时,如果网络不稳定或者遇到程序崩等情况,则整个上传就失败了,失败前已经上传的部分也作废,用户不得不重头再来。这样做不仅浪费资源,在网络不稳定的情况下,往往重试多次还是无法完成上传。 基于上述场景,BOS提供了断点续传上传的能力:
- 当网络情况一般的情况下,建议使用三步上传方式,将object分为5Mb的块,参考分块上传。
- 当您的网络情况非常差,推荐使用append_object的方式进行断点续传,每次append 较小数据256kb,参考追加上传。
提示
- 断点续传是分片上传的封装和加强,是用分片上传实现的;
- 文件较大或网络环境较差时,推荐使用分片上传;