上传文件

更新时间：2025-08-21

上传文件

在BOS中，用户操作的基本数据单元是Object。Object包含Key、Meta和Data。其中，Key是Object的名字；Meta是用户对该Object的描述，由一系列Name-Value对组成；Data是Object的数据。

BOS C++ SDK提供了丰富的文件上传接口，可以通过以下方式上传文件：

简单上传
追加上传
分块上传
断点续传上传

简单上传

BOS在简单上传的场景中，支持以指定文件形式、以数据流方式、以文件描述符方式、以字符串方式执行Object上传，请参考如下代码：

                C++
                
            

                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，参考代码如下:

                C++
                
                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被下载时的网页的缓存行为	无

参考代码如下：

                C++
                
            

                ...
// 初始化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进行描述。如下代码所示：

                C++
                
                // 设置自定义元数据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之后被修改了，则执行拷贝操作，否则拷贝失败。	否

对应的示例代码：

                Cpp
                
            

                // 初始化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

以低频存储为例，代码如下：

                Cpp
                
            

                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());
}
            

使用上传进度条

                C++
                
            

                // 上传进度回调函数
// 注意该回调函数中不得出现耗时较长/阻塞操作, 会影响数据上传性能. 
// 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方式上传示例代码如下：

                Cpp
                
            

                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 方法来初始化一个分块上传事件：

                Cpp
                
            

                // 开始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的初始化

初始化低频存储的一个分块上传事件：

                Cpp
                
            

                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的初始化

初始化低频存储的一个分块上传事件：

                Cpp
                
            

                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);
}
            

上传分块

接着，把文件分块上传。

                C++
                
            

                // 设置每块为 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;
std::vector<part_t> partEtags;
for (int i = 0; off < file.size(); ++i) {
    if (off + partSize > size) {
        partSize = size - off;
    }
    FileInputStream partFile(file.fd(), off, partSize);
    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中。

完成分块上传

如下代码所示，完成分块上传：

                Cpp
                
            

                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方法取消分块上传。

                Cpp
                
                AbortMultipartUploadRequest abortMultipartUploadRequest(bucketName, objectKey, uploadId);
AbortMultipartUploadResponse abortMultipartUploadResponse;
// 取消分块上传
int ret = client.abort_multipart_upload(abortMultipartUploadRequest, &abortMultipartUploadResponse);

获取未完成的分块上传事件

用户可以使用 list_multipart_uploads 方法获取Bucket内未完成的分块上传事件。

                Cpp
                
            

                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 方法获取某个上传事件中所有已上传的块。

                Cpp
                
            

                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使用以下代码：

                Cpp
                
            

                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，参考追加上传。

提示

断点续传是分片上传的封装和加强，是用分片上传实现的；

文件较大或网络环境较差时，推荐使用分片上传；

列举存储空间中的文件

获取及更新文件元信息

对象存储 BOS

对象存储 BOS

上传文件

上传文件

简单上传

使用上传进度条

追加上传

分块上传

断点续传上传