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

初始化分段上传任务

功能说明

使用分段上传方式传输数据前，必须先通知OBS初始化一个分段上传任务。该操作会返回一个OBS服务端创建的全局唯一标识（Upload ID），用于标识本次分段上传任务。您可以根据这个唯一标识来发起相关的操作，如取消分段上传任务、列举分段上传任务、列举已上传的段等。

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

接口约束

  • 您必须是桶拥有者或拥有初始化分段上传任务的权限，才能初始化分段上传任务。建议使用IAM或桶策略进行授权，如果使用IAM则需授予obs:object:PutObject权限，如果使用桶策略则需授予PutObject权限。相关授权方式介绍可参见OBS权限控制概述，配置方式详见使用IAM自定义策略、配置对象策略。
  • OBS支持的region以及region与endPoint的对应关系，详细信息请参见地区与终端节点。
  • 初始化上传段任务并上传一个或多个段之后，您必须合并段或取消多段上传任务，否则碎片会占用您的存储空间并产生一定的存储费用。

您也可以直接使用SDK提供的断点续传上传接口（对分段上传的封装和加强）实现分段上传。

方法定义

ObsClient.initiateMultipartUpload(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的字符串。

默认取值：

无

ACL

String

可选

参数解释：

创桶时可指定的预定义ACL，有关访问控制列表（Access Control List，ACL）功能的详细信息可参见ACL功能介绍。

取值范围：

private：私有读写。桶或对象的所有者拥有完全控制的权限，其他任何人都没有访问权限。

public-read：公共读私有写。所有人可以获取该对象内容和元数据。

public-read-write：公共读写。所有人可以获取该对象内容和元数据，等同于public-read。

bucket-owner-full-control：桶和对象的所有者拥有对象的完全控制权限，其他任何人都没有访问权限。默认情况下，上传对象至其他用户的桶中，桶拥有者没有对象的控制权限。对象拥有者为桶拥有者添加此权限控制策略后，桶所有者可以完全控制对象。

默认取值：

无

GrantRead

String

可选

参数解释：

创建对象时，使用此头域授权租户下所有用户有读对象和获取对象元数据的权限。

示例：id=domainID。

约束限制：

如果授权给多个租户，需要通过“,”分隔。

取值范围：

需要为正确的租户ID，获取方式请参考获取账号、IAM用户、项目、用户组、区域、委托的名称和ID。

默认取值：

无

GrantReadAcp

String

可选

参数解释：

创建对象时，使用此头域授权租户下所有用户有获取对象ACL的权限。

示例：id=domainID。

约束限制：

如果授权给多个租户，需要通过“,”分隔。

取值范围：

需要为正确的租户ID，获取方式请参考获取账号、IAM用户、项目、用户组、区域、委托的名称和ID。

默认取值：

无

GrantWriteAcp

String

可选

参数解释：

创建对象时，使用此头域授权domain下所有用户有写对象ACL的权限。

示例：id=domainID。

约束限制：

如果授权给多个租户，需要通过“,”分隔。

取值范围：

需要为正确的租户ID，获取方式请参考获取账号、IAM用户、项目、用户组、区域、委托的名称和ID。

默认取值：

无

GrantFullControl

String

可选

参数解释：

创建对象时，使用此头域授权租户下所有用户有读对象和获取对象元数据的权限。

示例：id=domainID。

约束限制：

如果授权给多个租户，需要通过“,”分隔。

取值范围：

需要为正确的租户ID，获取方式请参考获取账号、IAM用户、项目、用户组、区域、委托的名称和ID。

默认取值：

无

StorageClass

String

可选

参数解释：

对象的存储类型。如果未设置，则为桶的存储类型。

取值范围：

STANDARD：标准存储

WARM：低频访问存储

COLD：归档存储

DEEP_ARCHIVE：深度归档存储

默认取值：

无

Metadata

dict

可选

参数解释：

待上传对象的自定义元数据。OBS支持用户使用以“x-obs-meta-”开头的消息头来加入自定义的元数据，以便对对象进行自定义管理。当用户获取此对象或查询此对象元数据时，加入的自定义元数据将会在返回的消息头中出现。

约束限制：

  • 所有自定义元数据大小的总和不超过8K。单个自定义元数据大小的计算方式为：每个键和值的UTF-8 编码中的字节总数。
  • 自定义元数据的key值不区分大小写，OBS统一转为小写进行存储。value值区分大小写。
  • 自定义元数据key-value对都必须符合US-ASCII。如果一定要使用非ASCII码或不可识别字符，需要客户端自行做编解码处理，可以采用URL编码或者Base64编码，服务端不会做解码处理。例如x-obs-meta-中文：中文 经URL编码后发送，“中文”的URL编码为：%E4%B8%AD%E6%96%87，则响应为x-obs-meta-%E4%B8%AD%E6%96%87: %E4%B8%AD%E6%96%87

默认取值：

无

WebsiteRedirectLocation

String

可选

参数解释：

当桶设置了Website配置，可以将获取这个对象的请求重定向到桶内另一个对象或一个外部的URL。

例如，重定向请求到桶内另一对象：

WebsiteRedirectLocation:/anotherPage.html

或重定向请求到一个外部URL：

WebsiteRedirectLocation:http://www.example.com/

OBS将这个值从头域中取出，保存在对象的元数据“WebsiteRedirectLocation”中。

约束限制：

  • 必须以“/”、“http://”或“https://”开头，长度不超过2KB。
  • OBS仅支持为桶根目录下的对象设置重定向，不支持为桶中文件夹下的对象设置重定向。

默认取值：

无

Expires

Number

可选

参数解释：

表示对象的过期时间（从对象最后修改时间开始计算），过期之后对象会被自动删除。

约束限制：

此字段对于每个对象仅支持上传时配置，不支持后期通过修改元数据接口修改。

取值范围：

大于等于0的整型数，单位：天。

默认取值：

无

ContentType

String

可选

参数解释：

待上传对象的文件类型（MIME类型）。Content-Type（MIME）用于标识发送或接收数据的类型，浏览器根据该参数来决定数据的打开方式。

取值范围：

常见的Content-Type（MIME）列表参

默认取值：

如果您在上传Object时未指定Content-Type，SDK会根据指定Object名称的后缀名来判定文件类型并自动填充Content-Type。

CacheControl

String

可选

参数解释：

响应中的Cache-Control头。指定对象被下载时的网页的缓存行为。

默认取值：

无

ContentDisposition

String

可选

参数解释：

为请求的对象提供一个默认的文件名赋值给该对象，当下载对象或者访问对象时，以默认文件名命名的文件将直接在浏览器上显示，或在弹出文件下载对话框时显示。

默认取值：

无

ContentLanguage

String

可选

参数解释：

说明访问者希望采用的语言或语言组合，以根据自己偏好的语言来定制。详情请参见HTTP协议中关于ContentLanguage的定义。

默认取值：

无

ContentEncoding

String

可选

参数解释：

响应中的Content-Encoding头。指定对象内容编码格式。

默认取值：

无

SseMode

String

可选

参数解释：

指定加密方式

取值范围：

kms：使用SSE-KMS加密方式

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

默认取值：

无。

SseAlgorithm

String

可选

参数解释：

指定加密方式

取值范围：

不携带：使用AES256算法

SM4：使用SM4算法

默认取值：

无。

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编码得到。

默认取值：

无

SseCKeyMd5

String

可选

参数解释：

SseCKey密钥MD5值的base64值。

默认取值：

无

EncodingType

String

可选

参数解释：

用于指定对响应中的Key进行指定类型的编码。如果Key包含xml 1.0标准不支持的控制字符，可通过设置该参数对响应中的Key进行编码。

取值范围：

可选值为url。

默认取值：

无，不设置则不编码。

返回结果说明

表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

参数名称

参数类型

描述

UploadId

str

参数解释：

分段上传任务的ID，例如：000001648453845DBB78F2340DD460D8

取值范围：

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

默认取值：

无

代码示例

您可以通过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);
              }
       }
});
  • 初始化分段上传任务时，除了指定上传对象的名称和所属桶外，您还可以使用ContentType参数和Metadata参数分别指定对象MIME类型和对象自定义元数据。
  • 调用初始化分段上传任务接口成功后，会返回分段上传任务的全局唯一标识（Upload ID），在后面的操作中将用到它。
父主题： 多段操作

相关文档