文档首页/ 对象存储服务 OBS/ SDK参考/ BrowserJS/ 对象相关接口/ 多段操作/ 上传段
更新时间：2026-04-28 GMT+08:00
查看PDF
分享

上传段

功能说明

初始化分段上传任务后，通过分段上传任务的ID，上传段到指定桶中。除了最后一段以外，其他段的大小范围是100KB~5GB；最后一段的大小范围是0~5GB。上传的段的编号也有范围限制，其范围是1~10000。

上传段时，除了指定上传ID，还必须指定段编号。您可以选择1和10000之间的任意段编号。段编号在您正在上传的对象中唯一地标示了段及其位置。如果您使用之前上传的段的同一段编号上传新段，则之前上传的段将被覆盖。无论您何时上传段，OBS都将在其响应中返回ETag标头。对于每个段上传任务，您必须记录每个段编号和ETag值。您在后续的合并请求中需要添加这些值以完成多段上传。

开发过程中，您有任何问题可以在github上提交issue，或者在华为云对象存储服务论坛中发帖求助。接口参考文档详细介绍了每个接口的参数和使用方法。

接口约束

  • 您必须是桶拥有者或拥有上传段的权限，才能上传段。建议使用IAM或桶策略进行授权，如果使用IAM则需授予obs:object:PutObject权限，如果使用桶策略则需授予PutObject权限。相关授权方式介绍可参见OBS权限控制概述，配置方式详见使用IAM自定义策略、配置对象策略。
  • OBS支持的region以及region与endPoint的对应关系，详细信息请参见地区与终端节点。
  • 初始化上传段任务并上传一个或多个段之后，您必须合并段或取消多段上传任务，否则碎片会占用您的存储空间并产生一定的存储费用。
  • 段任务中的partNumber是唯一的，重复上传相同partNumber的段，后一次上传会覆盖前一次上传内容。多并发上传同一对象的同一partNumber时，服务端遵循Last Write Win策略，但“Last Write”的时间定义为段元数据创建时间。为了保证数据准确性，客户端需要保证同一对象的同一个段不能并发上传。

方法定义

ObsClient.uploadPart(params)

请求参数说明

表1 请求参数列表

参数名称

参数类型

是否必选

描述

Bucket

String

必选

参数解释：

桶名。

约束限制：

  • 桶的名字需全局唯一，不能与已有的任何桶名称重复，包括其他用户创建的桶。
  • 桶命名规则如下：
    • 3～63个字符，数字或字母开头，支持小写字母、数字、“-”、“.”。
    • 禁止使用IP地址。
    • 禁止以“-”或“.”开头及结尾。
    • 禁止两个“.”相邻（如：“my..bucket”）。
    • 禁止“.”和“-”相邻（如：“my-.bucket”和“my.-bucket”）。
  • 同一用户在同一个区域多次创建同名桶不会报错，创建的桶属性以第一次请求为准。

默认取值：

无

Key

String

必选

参数解释：

对象名。对象名是对象在存储桶中的唯一标识。对象名是对象在桶中的完整路径，路径中不包含桶名。

例如，您对象的访问地址为examplebucket.obs.cn-north-4.myhuaweicloud.com/folder/test.txt 中，对象名为folder/test.txt。

取值范围：

长度大于0且不超过1024的字符串。

默认取值：

无

说明：

对象链接地址格式为：https://桶名.域名/文件夹目录层级/对象名。如果该对象存在于桶的根目录下，则链接地址将不需要有文件夹目录层级。

RequestDate

String

或

Date

可选

参数解释：

指定请求时间。

说明：

当为String类型时，必须符合ISO8601或RFC822规范。

PartNumber

Number

必选

参数解释：

段号。

取值范围：

[1,10000]

默认取值：

无

UploadId

String

必选

参数解释：

分段上传任务的ID。任务ID可以通过初始化分段上传任务生成。例如：000001648453845DBB78F2340DD460D8。

约束限制：

长度为32的字符串。

默认取值：

无

ContentMD5

String

可选

参数解释：

待上传段数据的MD5值（经过Base64编码），是上传段数据内容的唯一标识，可以通过该值识别对象内容是否有变化。

取值范围：

长度为32的字符串。

默认取值：

无

Body

String

可选

参数解释：

待上传对象的内容。

约束限制：

不与SourceFile同时使用。

默认取值：

无

SourceFile

File

或

Blob

可选

参数解释：

待上传段的源文件（浏览器必须支持FileReader）。

约束限制：

不与Body同时使用。

默认取值：

无

ProgressCallback

Function

可选

参数解释：

获取上传进度的回调函数。

默认取值：

无

说明：

该回调函数依次包含三个参数：已上传的字节数、总字节数、已使用的时间（单位：秒）。

Offset

Number

可选

参数解释：

代表源文件中某一分段的起始偏移大小。

约束限制：

当设置了SourceFile时有效。

取值范围：

非负整数，不大于待上传对象的大小，单位：字节。

默认取值：

0

PartSize

Number

可选

参数解释：

代表源文件中某一分段的大小。

约束限制：

  • 当设置了SourceFile时有效。
  • 上传段接口要求除最后一段以外，其他的段大小都要大于100KB。但是上传段接口并不会立即校验上传段的大小（因为不知道是否为最后一段），只有调用合并段接口时才会校验。
  • OBS 3.0的桶支持最小段的大小为100KB，OBS 2.0的桶支持最小段的大小为5MB。

取值范围：

100KB~5GB，单位：字节。

默认取值：

文件大小减去Offset的剩下字节数。

SseKms

String

可选

参数解释：

指定加密方式

取值范围：

kms：使用SSE-KMS加密方式

AES256：使用SSE-OBS加密方式，且使用AES256算法

默认取值：

无。

SseKmsKey

String

可选

参数解释：

指定加密方式

取值范围：

不携带：使用AES256算法

SM4：使用SM4算法

默认取值：

无。

SseKmsProjectId

String

可选

参数解释：

SSE-KMS加密方式下使用的KMS主密钥的ID值。

取值范围：

有效值支持两种格式：

  1. regionID:domainID(账号ID):key/key_id
  2. key_id

其中：

  • regionID是使用密钥所属region的ID，可在地区和终端节点页面获取；
  • domainID是使用密钥所属账号的账号ID，获取方法参见；
  • key_id是从密码安全中心创建的密钥ID，获取方法请参见查看密钥。

默认取值：

  • 如果用户没有提供该头域，那么默认的主密钥将会被使用。
  • 如果默认主密钥不存在，将默认创建并使用。

SseC

String

可选

参数解释：

使用SSE-C时使用的算法。

取值范围：

AES256：表示使用SSE-C加密方式且使用AES256算法

默认取值：

无。

SseCKey

String

可选

参数解释：

SSE-C方式下加密的密钥，该密钥需要您自定义，并由256bit的密钥经过base64编码得到。

默认取值：

无

返回结果说明

表2 ICommonMsg

参数名称

参数类型

描述

Status

number

参数解释：

OBS服务端返回的HTTP状态码。

取值范围：

状态码是一组从2xx（成功）到4xx或5xx（错误）的数字代码，状态码表示了请求响应的状态。完整的状态码列表请参见状态码。

Code

string

参数解释：

OBS服务端返回的错误码。

Message

string

参数解释：

OBS服务端返回的错误描述。

HostId

string

参数解释：

OBS服务端返回的请求服务端ID。

RequestId

string

参数解释：

OBS服务端返回的请求ID。

Id2

string

参数解释：

OBS服务端返回的请求ID2。

Indicator

string

参数解释：

OBS服务端返回的详细错误码。
表3 InterfaceResult

参数名称

参数类型

描述

ETag

String

参数解释：

段的base64编码的128位MD5摘要。ETag是段内容的唯一标识，可以通过该值识别段内容是否有变化。

取值范围：

长度为32的字符串。

默认取值：

无

代码示例

您可以通过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);

如果ETag值获取是undefined，则需要配置CORS规则，将ETag添加到附加头域中即可，参考•ETag。

  • 使用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的桶上执行分段上传操作。
父主题： 多段操作

相关文档