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

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

• 简单上传
• 追加上传
• 分片上传
• 断点续传上传

简单上传

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

# 以数据流形式上传Object
client.put_object(bucket_name, object_name, data)

# 从字符串中上传Object
client.put_object_from_string(bucket_name, object_name, "string")

# 从文件中直接上传Object
client.put_object_from_file(bucket_name, object_name, file_path)

Object以文件的形式上传到BOS中，putObject相关接口支持不超过5GB的Object上传。在PutObject请求处理成功后，BOS会在Header中返回Object的ETag作为文件标识。

设置文件元信息

文件元信息(Object Meta)，是对用户在向BOS上传文件时，同时对文件进行的属性描述，主要分为分为两种：设置HTTP标准属性（HTTP Headers）和用户自定义的元信息。

设定Object的Http Header

BOS Ruby SDK本质上是调用后台的HTTP接口，因此用户可以在上传文件时自定义Object的Http Header。常用的http header说明如下：

参考代码如下：

options = { Http::CONTENT_TYPE => 'string',
            Http::CONTENT_MD5 => 'md5',
            Http::CONTENT_DISPOSITION => 'inline',
            'key1' => 'value1'
}

client.put_object_from_string(bucket_name, object_name, "string", options)

用户自定义元信息

BOS支持用户自定义元数据来对Object进行描述。如下代码所示：

options = { 
            'user-metadata' => { "key1" => "value1" }
}

client.put_object_from_string(bucket_name, object_name, "string", options)

提示：

• 在上面代码中，用户自定义了一个名字为”key1”，值为”value1”的元数据
• 当用户下载此Object的时候，此元数据也可以一并得到
• 一个Object可以有多个类似的参数，但所有的User Meta总大小不能超过2KB

上传Object时设置存储类型

BOS支持标准存储, 低频存储和冷存储，上传Object并存储为低频存储类型通过指定StorageClass实现，三种存储类型对应的参数如下：

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

# 上传一个低频object（默认为标准object）
client.put_object_from_file(bucket_name, object_name, file_path, Http::BOS_STORAGE_CLASS => 'STANDARD_IA')

putObject请求处理成功后，BOS会在Header中返回Object的Content-MD5，用户可以根据这个参数来对文件进行校验。

追加上传

上文介绍的简单上传方式，创建的Object都是Normal类型，用户不可再进行追加写，这在日志、视频监控、视频直播等数据复写较频繁的场景中使用不方便。

正因如此，百度智能云BOS特别支持了AppendObject，即以追加写的方式上传文件。通过AppendObject操作创建的Object类型为Appendable Object，可以对该Object追加数据。AppendObject大小限制为0~5G。

通过AppendObject方式上传示例代码如下：

# 从字符串上传一个appendable object
client.append_object_from_string(bucket_name, object_name, "string")

# 从offset处开始追加写
client.append_object_from_string(bucket_name, object_name, "append_str", 'offset' => 6)

分块上传

除了通过简单上传几追加上传方式将文上传件到BOS以外，BOS还提供了另外一种上传模式 —— Multipart Upload。用户可以在如下的应用场景内（但不仅限于此），使用Multipart Upload上传模式，如：

• 需要支持断点上传。
• 上传超过5GB大小的文件。
• 网络条件较差，和BOS的服务器之间的连接经常断开。
• 需要流式地上传文件。
• 上传文件之前，无法确定上传文件的大小。

下面将一步步介绍Multipart Upload的实现。假设有一个文件，本地路径为 /path/to/file.zip ，由于文件比较大，将其分块传输到BOS中。

初始化Multipart Upload

使用initiate_multipart_upload 方法来初始化一个分块上传事件：

upload_id = client.initiate_multipart_upload(bucket_name, object_name)["uploadId"]

initiate_multipart_upload的返回结果中含有 uploadId ，它是区分分块上传事件的唯一标识，在后面的操作中，我们将用到它。

上传低频存储类型Object的初始化

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

options = { 
            Http::BOS_STORAGE_CLASS => 'STANDARD_IA'
}
client.initiate_multipart_upload(bucket_name, object_name, options)

上传冷存储类型Object的初始化

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

options = { 
            Http::BOS_STORAGE_CLASS => 'COLD'
}
client.initiate_multipart_upload(bucket_name, object_name, options)

上传分块

接着，把文件分块上传。

# 设置分块的开始偏移位置
left_size = File.open(multi_file, "r").size()
offset = 0
part_number = 1
part_list = []

while left_size > 0 do
    part_size = 5 * 1024 * 1024
    if left_size < part_size
        part_size = left_size
    end

    response = client.upload_part_from_file(
        bucket_name, object_name, upload_id, part_number, part_size, multi_file, offset)
    left_size -= part_size
    offset += part_size
    # your should store every part number and etag to invoke complete multi-upload
    part_list << {
        "partNumber" => part_number,
        "eTag" => response['etag']
    }
    part_number += 1
end

上面代码的核心是调用 UploadPart 方法来上传每一个分块，但是要注意以下几点：

• UploadPart 方法要求除最后一个Part以外，其他的Part大小都要大于等于5MB。但是Upload Part接口并不会立即校验上传Part的大小；只有当Complete Multipart Upload的时候才会校验。
• 为了保证数据在网络传输过程中不出现错误，建议您在UploadPart后，使用每个分块BOS返回的Content-MD5值分别验证已上传分块数据的正确性。当所有分块数据合成一个Object后，不再含MD5值。
• Part号码的范围是1~10000。如果超出这个范围，BOS将返回InvalidArgument的错误码。
• 每次上传Part时都要把流定位到此次上传块开头所对应的位置。
• 每次上传Part之后，BOS的返回结果会包含eTag和partNumber，需要保存到part_list中。part_list类型是array，里面每个元素是个hash，每个hash包含两个关键字，一个是partNumber, 一个是eTag；在后续完成分块上传的步骤中会用到它。

完成分块上传

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

client.complete_multipart_upload(bucket_name, object_name, upload_id, part_list)

上面代码中的 part_list 是第二步中保存的part列表，BOS收到用户提交的Part列表后，会逐一验证每个数据Part的有效性。当所有的数据Part验证通过后，BOS将把这些数据part组合成一个完整的Object。

取消分块上传

用户可以使用abort_multipart_upload方法取消分块上传。

client.abort_multipart_upload(bucket_name, object_name, upload_id)

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

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

response = client.list_multipart_uploads(bucket_name)
puts response['bucket']
puts response['uploads'][0]['key']

注意：

1. 默认情况下，如果Bucket中的分块上传事件的数目大于1000，则只会返回1000个Object，并且返回结果中IsTruncated的值为True，同时返回NextKeyMarker作为下次读取的起点。
2. 若想返回更多分块上传事件的数目，可以使用KeyMarker参数分次读取。

获取所有已上传的块信息

用户可以使用list_parts方法获取某个上传事件中所有已上传的块：

response = client.list_parts(bucket_name, object_name, upload_id)
puts response['bucket']
puts response['uploads'][0]['key']

注意：

1. 默认情况下，如果Bucket中的分块上传事件的数目大于1000，则只会返回1000个Object，并且返回结果中IsTruncated的值为True，同时返回NextPartNumberMarker作为下次读取的起点。
2. 若想返回更多分块上传事件的数目，可以使用PartNumberMarker参数分次读取。

断点续传上传

当用户向BOS上传大文件时，如果网络不稳定或者遇到程序崩等情况，则整个上传就失败了，失败前已经上传的部分也作废，用户不得不重头再来。这样做不仅浪费资源，在网络不稳定的情况下，往往重试多次还是无法完成上传。 基于上述场景，BOS提供了断点续传上传的能力:

• 当网络情况一般的情况下，建议使用三步上传方式，将object分为1Mb的块，参考分块上传。
• 当您的网络情况非常差，推荐使用appendObject的方式进行断点续传，每次append 较小数据256kb，参考追加上传。

提示

• 断点续传是分片上传的封装和加强，是用分片上传实现的；
• 文件较大或网络环境较差时，推荐使用分片上传；