# 分段上传
![](https://support.huaweicloud.com/sdk-browserjs-devg-obs/public_sys-resources/notice_3.0-zh-cn.png)
开发过程中，您有任何问题可以在github上[提交issue](https://github.com/huaweicloud/huaweicloud-sdk-browserjs-obs/issues)，或者在[华为云对象存储服务论坛](https://bbs.huaweicloud.com/forum/forum-620-1.html)中发帖求助。[接口参考文档](https://support.huaweicloud.com/api-obs_browserjs_sdk_api_zh/obs_34_0001.html)详细介绍了每个接口的参数和使用方法。
对于较大文件上传，可以切分成段上传。用户可以在如下的应用场景内（但不仅限于此），使用分段上传的模式：
- 上传超过100MB大小的文件。
- 网络条件较差，和OBS服务端之间的连接经常断开。
- 上传前无法确定将要上传文件的大小。
分段上传分为如下3个步骤：
1. 初始化分段上传任务（ObsClient.initiateMultipartUpload）。
2. 逐个或并行上传段（ObsClient.uploadPart）。
3. 合并段（ObsClient.completeMultipartUpload）或取消分段上传任务(ObsClient.abortMultipartUpload)。
![](https://support.huaweicloud.com/sdk-browserjs-devg-obs/public_sys-resources/note_3.0-zh-cn.png)
您也可以直接使用SDK提供的[断点续传上传](https://support.huaweicloud.com/sdk-browserjs-devg-obs/obs_24_0511.html)接口（对分段上传的封装和加强）实现分段上传。
#### 初始化分段上传任务
使用分段上传方式传输数据前，必须先通知OBS初始化一个分段上传任务。该操作会返回一个OBS服务端创建的全局唯一标识（Upload ID），用于标识本次分段上传任务。您可以根据这个唯一标识来发起相关的操作，如取消分段上传任务、列举分段上传任务、列举已上传的段等。
您可以通过ObsClient.initiateMultipartUpload初始化一个分段上传任务：
```
// 创建ObsClient实例
var obsClient = new ObsClient({
    // 认证用的ak和sk硬编码到代码中或者明文存储都有很大的安全风险，建议在配置文件或者环境变量中密文存放，使用时解密，确保安全；本示例以ak和sk保存在环境变量中为例，运行本示例前请先在本地环境中设置环境变量AccessKeyID和SecretAccessKey。
    // 前端本身没有process对象，可以使用webpack类打包工具定义环境变量，就可以在代码中运行了。
    // 您可以登录访问管理控制台获取访问密钥AK/SK，获取方式请参见https://support.huaweicloud.com/usermanual-ca/ca_01_0003.html
    access_key_id: process.env.AccessKeyID,
    secret_access_key: process.env.SecretAccessKey,
    // 这里以华北-北京四为例，其他地区请按实际情况填写
    server: 'https://obs.cn-north-4.myhuaweicloud.com'
});
obsClient.initiateMultipartUpload({
       Bucket : 'bucketname',
       Key : 'objectname',
       ContentType : 'text/plain',
       Metadata : {'property' : 'property-value'}
}, function (err, result) {
       if(err){
              console.error('Error-->' + err);
       }else{
              console.log('Status-->' + result.CommonMsg.Status);
              if(result.CommonMsg.Status < 300 && result.InterfaceResult){
                     console.log('UploadId-->' + result.InterfaceResult.UploadId);
              }
       }
});
```
![](https://support.huaweicloud.com/sdk-browserjs-devg-obs/public_sys-resources/note_3.0-zh-cn.png)
- 初始化分段上传任务时，除了指定上传对象的名称和所属桶外，您还可以使用**ContentType参数** 和**Metadata参数**分别指定对象MIME类型和对象自定义元数据。
- 调用初始化分段上传任务接口成功后，会返回分段上传任务的全局唯一标识（Upload ID），在后面的操作中将用到它。
 
#### 上传段
初始化一个分段上传任务之后，可以根据指定的对象名和Upload ID来分段上传数据。每一个上传的段都有一个标识它的号码------分段号（Part Number，范围是1\~10000）。对于同一个Upload ID，该分段号不但唯一标识这一段数据，也标识了这段数据在整个对象内的相对位置。如果您用同一个分段号上传了新的数据，那么OBS上已有的这个段号的数据将被覆盖。**除了最后一段以外，其他段的大小范围100KB\~5GB**；最后段大小范围是0\~5GB。每个段不需要按顺序上传，甚至可以在不同进程、不同机器上上传，OBS会按照分段号排序组成最终对象。
您可以通过ObsClient.uploadPart上传段：
```
// 创建ObsClient实例
var obsClient = new ObsClient({
    // 认证用的ak和sk硬编码到代码中或者明文存储都有很大的安全风险，建议在配置文件或者环境变量中密文存放，使用时解密，确保安全；本示例以ak和sk保存在环境变量中为例，运行本示例前请先在本地环境中设置环境变量AccessKeyID和SecretAccessKey。
    // 前端本身没有process对象，可以使用webpack类打包工具定义环境变量，就可以在代码中运行了。
    // 您可以登录访问管理控制台获取访问密钥AK/SK，获取方式请参见https://support.huaweicloud.com/usermanual-ca/ca_01_0003.html
    access_key_id: process.env.AccessKeyID,
    secret_access_key: process.env.SecretAccessKey,
    // 这里以华北-北京四为例，其他地区请按实际情况填写
    server: 'https://obs.cn-north-4.myhuaweicloud.com'
});
const bucketname = 'examplebucket';
const objectname = 'exampleobject';
const PartSize = 5 * 1024 * 1024;
const UploadId = 'upload id from initiateMultipartUpload';
const file = document.getElementById('input-file').files[0];
const lastPartSize = file.size % PartSize;
// 段数量
const count = Math.ceil(file.size / PartSize);
// 上传第n段
const uploadPart = (n) => {
    obsClient.uploadPart({
        Bucket: bucketname,
        Key: objectname,
        // 设置分段号，范围是1~10000
        PartNumber: n,
        // 设置Upload ID
        UploadId,
        // 设置将要上传的大文件
        SourceFile: file,
        // 设置分段大小
        PartSize: count === n ? lastPartSize : PartSize,
        // 设置分段的起始偏移大小
        Offset: (n-1) * PartSize
    }, function (err, result) {
        if(err){
                console.log('Error-->' + err);
        }else{
                console.log('Status-->' + result.CommonMsg.Status);
                if(result.CommonMsg.Status < 300 && result.InterfaceResult){
                      console.log('ETag-->' + result.InterfaceResult.ETag);
                }
        }
    });
}
// 上传第1段
uploadPart(1);
```
![](https://support.huaweicloud.com/sdk-browserjs-devg-obs/public_sys-resources/caution_3.0-zh-cn.png)
如果ETag值获取是undefined，则需要配置CORS规则，将ETag添加到附加头域中即可，参考**[•ETag](https://support.huaweicloud.com/sdk-browserjs-devg-obs/obs_24_0107.html#obs_24_0107__li11765181505511)。**
![](https://support.huaweicloud.com/sdk-browserjs-devg-obs/public_sys-resources/note_3.0-zh-cn.png)
- 使用**PartNumber参数** 指定分段号；使用**UploadId参数** 指定分段上传任务的全局唯一标识；使用**SourceFile参数** 指定待上传的文件；使用**PartSize参数** 指定分段大小；使用**Offset参数**指定待上传文件的起始偏移大小。
- **SourceFile参数**必须是File对象或者Blob对象，例如在HTML页面中使用类型为"file"的input标签指定待上传的文件：\<input type="file" id="input-file"/\>。
- 上传段接口要求除最后一段以外，其他的段大小都要大于100KB。但是上传段接口并不会立即校验上传段的大小（因为不知道是否为最后一块）；只有调用合并段接口时才会校验。
- OBS会将服务端收到段数据的ETag值（段数据的MD5值）返回给用户。
- 可以通过**ContentMD5参数**设置上传数据的MD5值，提供给OBS服务端用于校验数据完整性。
- 分段号的范围是1\~10000。如果超出这个范围，OBS将返回400 Bad Request错误。
- OBS 3.0的桶支持最小段的大小为100KB，OBS 2.0的桶支持最小段的大小为5MB。请在OBS 3.0的桶上执行分段上传操作。
 
#### 合并段
所有分段上传完成后，需要调用合并段接口来在OBS服务端生成最终对象。在执行该操作时，需要提供所有有效的分段列表（包括分段号和分段ETag值）；OBS收到提交的分段列表后，会逐一验证每个段的有效性。当所有段验证通过后，OBS将把这些分段组合成最终的对象。
您可以通过ObsClient.completeMultipartUpload合并段：
```
// 创建ObsClient实例
var obsClient = new ObsClient({
    // 认证用的ak和sk硬编码到代码中或者明文存储都有很大的安全风险，建议在配置文件或者环境变量中密文存放，使用时解密，确保安全；本示例以ak和sk保存在环境变量中为例，运行本示例前请先在本地环境中设置环境变量AccessKeyID和SecretAccessKey。
    // 前端本身没有process对象，可以使用webpack类打包工具定义环境变量，就可以在代码中运行了。
    // 您可以登录访问管理控制台获取访问密钥AK/SK，获取方式请参见https://support.huaweicloud.com/usermanual-ca/ca_01_0003.html
    access_key_id: process.env.AccessKeyID,
    secret_access_key: process.env.SecretAccessKey,
    // 这里以华北-北京四为例，其他地区请按实际情况填写
    server: 'https://obs.cn-north-4.myhuaweicloud.com'
});
obsClient.completeMultipartUpload({
       Bucket:'bucketname',
       Key:'objectname',
       // 设置Upload ID
       UploadId:'upload id from initiateMultipartUpload',
       Parts: [{'PartNumber':1,'ETag':'etag value from uploadPart'}]
}, function (err, result) {
       if(err){
              console.log('Error-->' + err);
       }else{
              console.log('Status-->' + result.CommonMsg.Status);
       }
});
```
![](https://support.huaweicloud.com/sdk-browserjs-devg-obs/public_sys-resources/caution_3.0-zh-cn.png)
- 如果最后一个段之外的其它段尺寸过小（小于100KB），OBS返回400 Bad Request。
 
![](https://support.huaweicloud.com/sdk-browserjs-devg-obs/public_sys-resources/note_3.0-zh-cn.png)
- 使用**UploadId参数** 指定分段上传任务的全局唯一标识；使用**Parts参数**指定分段号与分段ETag值的列表，该列表必须按分段号升序排列。
- 分段可以是不连续的。
 
#### 取消分段上传任务
分段上传任务可以被取消，当一个分段上传任务被取消后，就不能再使用其Upload ID做任何操作，已经上传段也会被OBS删除。
采用分段上传方式上传对象过程中或上传对象失败后会在桶内产生段，这些段会占用您的存储空间，您可以通过取消该分段上传任务来清理掉不需要的段，节约存储空间。
您可以通过ObsClient.abortMultipartUpload取消分段上传任务：
```
// 创建ObsClient实例
var obsClient = new ObsClient({
    // 认证用的ak和sk硬编码到代码中或者明文存储都有很大的安全风险，建议在配置文件或者环境变量中密文存放，使用时解密，确保安全；本示例以ak和sk保存在环境变量中为例，运行本示例前请先在本地环境中设置环境变量AccessKeyID和SecretAccessKey。
    // 前端本身没有process对象，可以使用webpack类打包工具定义环境变量，就可以在代码中运行了。
    // 您可以登录访问管理控制台获取访问密钥AK/SK，获取方式请参见https://support.huaweicloud.com/usermanual-ca/ca_01_0003.html
    access_key_id: process.env.AccessKeyID,
    secret_access_key: process.env.SecretAccessKey,
    // 这里以华北-北京四为例，其他地区请按实际情况填写
    server: 'https://obs.cn-north-4.myhuaweicloud.com'
});
obsClient.abortMultipartUpload({
       Bucket:'bucketname',
       Key:'objectname',
       // 设置Upload ID
       UploadId:'upload id from initiateMultipartUpload',
}, function (err, result) {
       if(err){
              console.log('Error-->' + err);
       }else{
              console.log('Status-->' + result.CommonMsg.Status);
       }
});
```
#### 列举已上传的段
您可使用ObsClient.listParts列举出某一分段上传任务所有已经上传成功的段。
该接口可设置的参数如下：
| **参数**           | **作用**                                                  |
|:---|:---|
| UploadId         | 分段上传任务全局唯一标识，从ObsClient.initiateMultipartUpload返回的结果获取。 |
| MaxParts         | 表示列举已上传段的返回结果最大段数目，即分页时每一页中段数目。                         |
| PartNumberMarker | 表示列举已上传段的起始位置，只有Part Number大于该参数的段会被列出。                 |
   
- 简单列举
```
// 创建ObsClient实例
var obsClient = new ObsClient({
    // 认证用的ak和sk硬编码到代码中或者明文存储都有很大的安全风险，建议在配置文件或者环境变量中密文存放，使用时解密，确保安全；本示例以ak和sk保存在环境变量中为例，运行本示例前请先在本地环境中设置环境变量AccessKeyID和SecretAccessKey。
    // 前端本身没有process对象，可以使用webpack类打包工具定义环境变量，就可以在代码中运行了。
    // 您可以登录访问管理控制台获取访问密钥AK/SK，获取方式请参见https://support.huaweicloud.com/usermanual-ca/ca_01_0003.html
    access_key_id: process.env.AccessKeyID,
    secret_access_key: process.env.SecretAccessKey,
    // 这里以华北-北京四为例，其他地区请按实际情况填写
    server: 'https://obs.cn-north-4.myhuaweicloud.com'
});
// 列举已上传的段，其中uploadId来自于initiateMultipartUpload
obsClient.listParts({
       Bucket : 'bucketname',
       Key: 'objectname',
       UploadId : 'upload id from initiateMultipartUpload'
}, function (err, result) {
       if(err){
              console.log('Error-->' + err);
       }else{
              console.log('Status-->' + result.CommonMsg.Status);
              if(result.CommonMsg.Status < 300 && result.InterfaceResult){
                     for(var i in result.InterfaceResult.Parts){
                           console.log('Part['+ i +']:');
                           // 分段号，上传时指定
                           console.log('PartNumber-->' + result.InterfaceResult.Parts[i]['PartNumber']);
                           // 段的最后上传时间
                           console.log('LastModified-->' + result.InterfaceResult.Parts[i]['LastModified']);
                           // 分段的ETag值
                           console.log('ETag-->' + result.InterfaceResult.Parts[i]['ETag']);
                           // 段数据大小
                           console.log('Size-->' + result.InterfaceResult.Parts[i]['Size']);
                     }
              }
       }
});
```
![](https://support.huaweicloud.com/sdk-browserjs-devg-obs/public_sys-resources/note_3.0-zh-cn.png)
- 列举段至多返回1000个段信息，如果指定的Upload ID包含的段数量大于1000，则返回结果中InterfaceResult.IsTruncated为true表明本次没有返回全部段，并可通过InterfaceResult.NextPartNumberMarker获取下次列举的起始位置。
- 如果想获取指定Upload ID包含的所有分段，可以采用分页列举的方式。
 
- 列举所有段
由于ObsClient.listParts只能列举至多1000个段，如果段数量大于1000，列举所有分段请参考如下示例：
```
// 创建ObsClient实例
var obsClient = new ObsClient({
    // 认证用的ak和sk硬编码到代码中或者明文存储都有很大的安全风险，建议在配置文件或者环境变量中密文存放，使用时解密，确保安全；本示例以ak和sk保存在环境变量中为例，运行本示例前请先在本地环境中设置环境变量AccessKeyID和SecretAccessKey。
    // 前端本身没有process对象，可以使用webpack类打包工具定义环境变量，就可以在代码中运行了。
    // 您可以登录访问管理控制台获取访问密钥AK/SK，获取方式请参见https://support.huaweicloud.com/usermanual-ca/ca_01_0003.html
    access_key_id: process.env.AccessKeyID,
    secret_access_key: process.env.SecretAccessKey,
    // 这里以华北-北京四为例，其他地区请按实际情况填写
    server: 'https://obs.cn-north-4.myhuaweicloud.com'
});
var listAll = function (partNumberMarker) {
       // 列举已上传的段，其中uploadId来自于initiateMultipartUpload
       obsClient.listParts({
              Bucket : 'bucketname',
              Key: 'objectname',
              UploadId : 'upload id from initiateMultipartUpload',
              PartNumberMarker : partNumberMarker
       }, function (err, result) {
              if(err){
                     console.log('Error-->' + err);
              }else{
                     console.log('Status-->' + result.CommonMsg.Status);
                     if(result.CommonMsg.Status < 300 && result.InterfaceResult){
                           for(var i in result.InterfaceResult.Parts){
                                  console.log('Part['+ i +']:');
                                  // 分段号，上传时指定
                                  console.log('PartNumber-->' + result.InterfaceResult.Parts[i]['PartNumber']);
                                  // 段的最后上传时间
                                  console.log('LastModified-->' + result.InterfaceResult.Parts[i]['LastModified']);
                                  // 分段的ETag值
                                  console.log('ETag-->' + result.InterfaceResult.Parts[i]['ETag']);
                                  // 段数据大小
                                  console.log('Size-->' + result.InterfaceResult.Parts[i]['Size']);
                           }
                           if(result.InterfaceResult.IsTruncated === 'true'){
                                  listAll(result.InterfaceResult.NextPartNumberMarker);
                           }
                     }
              }
       });
};
listAll();
```
#### 列举分段上传任务
您可以通过ObsClient.listMultipartUploads列举分段上传任务。列举分段上传任务可设置的参数如下：
| **参数**         | **作用**                                                                                                                             |
|:---|:---|
| Prefix         | 限定返回的分段上传任务中的对象名必须带有Prefix前缀。                                                                                                      |
| Delimiter      | 用于对分段上传任务中的对象名进行分组的字符。对于对象名中包含Delimiter的任务，其对象名（如果请求中指定了Prefix，则此处的对象名需要去掉Prefix）中从首字符至第一个Delimiter之间的字符串将作为一个分组并作为CommonPrefix返回。 |
| MaxUploads     | 列举分段上传任务的最大数目，取值范围为1\~1000，当超出范围时，按照默认的1000进行处理。                                                                                   |
| KeyMarker      | 表示列举时返回指定的KeyMarker之后的分段上传任务。                                                                                                      |
| UploadIdMarker | 只有与KeyMarker参数一起使用时才有意义，用于指定返回结果的起始位置，即列举时返回指定KeyMarker的UploadIdMarker之后的分段上传任务。                                                   |
   
- 简单列举分段上传任务
```
// 创建ObsClient实例
var obsClient = new ObsClient({
    // 认证用的ak和sk硬编码到代码中或者明文存储都有很大的安全风险，建议在配置文件或者环境变量中密文存放，使用时解密，确保安全；本示例以ak和sk保存在环境变量中为例，运行本示例前请先在本地环境中设置环境变量AccessKeyID和SecretAccessKey。
    // 前端本身没有process对象，可以使用webpack类打包工具定义环境变量，就可以在代码中运行了。
    // 您可以登录访问管理控制台获取访问密钥AK/SK，获取方式请参见https://support.huaweicloud.com/usermanual-ca/ca_01_0003.html
    access_key_id: process.env.AccessKeyID,
    secret_access_key: process.env.SecretAccessKey,
    // 这里以华北-北京四为例，其他地区请按实际情况填写
    server: 'https://obs.cn-north-4.myhuaweicloud.com'
});
obsClient.listMultipartUploads({
       Bucket : 'bucketname'
}, function (err, result) {
       if(err){
              console.log('Error-->' + err);
       }else{
              console.log('Status-->' + result.CommonMsg.Status);
              if(result.CommonMsg.Status < 300 && result.InterfaceResult){
                     for(var i in result.InterfaceResult.Uploads){
                           console.log('Uploads[' + i + ']');
                           console.log('UploadId-->' + result.InterfaceResult.Uploads[i]['UploadId']);
                           console.log('Key-->' + result.InterfaceResult.Uploads[i]['Key']);
                           console.log('Initiated-->' + result.InterfaceResult.Uploads[i]['Initiated']);
                     }
              }
       }
});
```
![](https://support.huaweicloud.com/sdk-browserjs-devg-obs/public_sys-resources/note_3.0-zh-cn.png)
- 列举分段上传任务至多返回1000个任务信息，如果指定的桶包含的分段上传任务数量大于1000，则返回结果中InterfaceResult.IsTruncated为true表明本次没有返回全部结果，并可通过InterfaceResult.NextKeyMarker和InterfaceResult.NextUploadIdMarker获取下次列举的起点。
- 如果想获取指定桶包含的所有分段上传任务，可以采用分页列举的方式。
 
- 列举全部分段上传任务
```
// 创建ObsClient实例
var obsClient = new ObsClient({
    // 认证用的ak和sk硬编码到代码中或者明文存储都有很大的安全风险，建议在配置文件或者环境变量中密文存放，使用时解密，确保安全；本示例以ak和sk保存在环境变量中为例，运行本示例前请先在本地环境中设置环境变量AccessKeyID和SecretAccessKey。
    // 前端本身没有process对象，可以使用webpack类打包工具定义环境变量，就可以在代码中运行了。
    // 您可以登录访问管理控制台获取访问密钥AK/SK，获取方式请参见https://support.huaweicloud.com/usermanual-ca/ca_01_0003.html
    access_key_id: process.env.AccessKeyID,
    secret_access_key: process.env.SecretAccessKey,
    // 这里以华北-北京四为例，其他地区请按实际情况填写
    server: 'https://obs.cn-north-4.myhuaweicloud.com'
});
var listAll = function (keyMarker, uploadIdMarker) {
       obsClient.listMultipartUploads({
              Bucket : 'bucketname',
              KeyMarker : keyMarker,
              UploadIdMarker : uploadIdMarker
       }, function (err, result) {
              if(err){
                     console.log('Error-->' + err);
              }else{
                     console.log('Status-->' + result.CommonMsg.Status);
                     if(result.CommonMsg.Status < 300 && result.InterfaceResult){
                           for(var i in result.InterfaceResult.Uploads){
                                  console.log('Uploads[' + i + ']');
                                  console.log('UploadId-->' + result.InterfaceResult.Uploads[i]['UploadId']);
                                  console.log('Key-->' + result.InterfaceResult.Uploads[i]['Key']);
                                  console.log('Initiated-->' + result.InterfaceResult.Uploads[i]['Initiated']);
                           }
                           
                           if(result.InterfaceResult.IsTruncated === 'true'){
                                  listAll(result.InterfaceResult.NextKeyMarker, result.InterfaceResult.NextUploadIdMarker);
                           }
                     }
              }
       });
}
listAll();
```