文档首页/ 对象存储服务 OBS/ SDK参考/ Node.js/ 多段相关接口/ 上传段
更新时间：2024-09-09 GMT+08:00
查看PDF
分享

上传段

功能说明

如果用户上传完所有的段，就可以调用合并段接口，系统将在服务端将用户指定的段合并成一个完整的对象。在执行“合并段”操作以前，用户不能下载已经上传的数据。在合并段时需要将多段上传任务初始化时记录的附加消息头信息拷贝到对象元数据中，其处理过程和普通上传对象带这些消息头的处理过程相同。在并发合并段的情况下，仍然遵循Last Write Win策略，但“Last Write”的时间定义为段任务的初始化时间。

已经上传的段，只要没有取消对应的多段上传任务，都要占用用户的容量配额；对应的多段上传任务“合并段”操作完成后，只有指定的多段数据占用容量配额，用户上传的其他此多段任务对应的段数据如果没有包含在“合并段”操作制定的段列表中，“合并段”完成后系统将删除多余的段数据，且同时释放容量配额。

合并段时，OBS通过按升序的段编号规范化多段来创建对象。如果在初始化上传段任务中提供了任何对象元数据，则OBS会将该元数据与对象相关联。成功完成请求后，段将不再存在。合并段请求必须包括上传ID以及段编号和相应的ETag值的列表。OBS响应包括可唯一地识别组合对象数据的ETag。此ETag无需成为对象数据的MD5哈希。

接口约束

  • 您必须是桶拥有者或拥有合并段的权限，才能合并段。建议使用IAM或桶策略进行授权，如果使用IAM则需授予obs:object:PutObject权限，如果使用桶策略则需授予PutObject权限。相关授权方式介绍可参见OBS权限控制概述，配置方式详见使用IAM自定义策略、配置对象策略。
  • OBS支持的Region与Endpoint的对应关系，详细信息请参见地区与终端节点。
  • 如果上传了10个段，但合并时只选择了9个段进行合并，那么未被合并的段将会被系统自动删除，未被合并的段删除后不能恢复。在进行合并之前请使用列出已上传的段接口进行查询，仔细核对所有段，确保没有段被遗漏。
  • 上传段接口要求除最后一段以外，其他的段大小都要大于100KB。但是上传段接口并不会立即校验上传段的大小（因为不知道是否为最后一块）；只有调用合并段接口时才会校验。
  • OBS 3.0的桶支持最小段的大小为100KB，OBS 2.0的桶支持最小段的大小为5MB。请在OBS 3.0的桶上执行分段上传操作。

方法定义

ObsClient.uploadPart(params)

请求参数

表1 请求参数列表

参数名称

参数类型

是否必选

描述

Bucket

string

必选

参数解释：

桶名。

约束限制：

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

取值范围：

长度为3～63个字符。

默认取值：

无

Key

string

必选

参数解释：

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

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

约束限制：

无

取值范围：

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

默认取值：

无

PartNumber

number

必选

参数解释：

段号。

约束限制：

无

取值范围：

取值范围是[1,10000]的非负整数。

默认取值：

无

UploadId

string

必选

参数解释：

分段上传任务的ID。任务ID可以通过初始化分段上传任务生成。

约束限制：

无

取值范围：

长度为32的字符串。

例如：000001648453845DBB78F2340DD460D8。

默认取值：

无

ContentMD5

string

可选

参数解释：

待上传对象数据的MD5值（经过Base64编码），提供给OBS服务端，校验数据完整性。

约束限制：

消息体128-bit MD5值经过base64编码后得到的字符串。

取值范围：

按照RFC 1864标准计算出消息体的MD5摘要字符串，即消息体128-bit MD5值经过base64编码后得到的字符串。

示例：n58IG6hfM7vqI4K0vnWpog==。

默认取值：

无

Body

string | stream.Readable

可选

参数解释：

待上传对象的数据流。

约束限制：

单次上传大小范围是[0, 5GB]。

取值范围：

无

默认取值：

无

SourceFile

string

可选

参数解释：

待上传对象的源文件路径。

约束限制：

  • 单次上传大小范围是[0, 5GB]。
  • Body与SourceFile不能同时使用。
  • 当Body与SourceFile都为空时，上传对象的大小为0字节。
  • Offset、PartSize和SourceFile配套使用，用于指定上传源文件中的某一分段数据。

取值范围：

无

默认取值：

无

Offset

number

可选

参数解释：

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

约束限制：

Offset、PartSize和SourceFile配套使用，用于指定上传源文件中的某一分段数据。

取值范围：

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

默认取值：

0

PartSize

number

可选

参数解释：

当前段的长度。

约束限制：

Offset、PartSize和SourceFile配套使用，用于指定上传源文件中的某一分段数据。

取值范围：

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

默认取值：

102400字节

SseKms

string

当使用SSE-KMS方式时，必选

参数解释：

表示服务端加密是SSE-KMS方式。对象使用SSE-KMS方式加密。

约束限制：

当前仅支持kms。

取值范围：

可选值：kms，即选择SSE-KMS方式加密对象。

默认取值：

无

SseKmsKey

string

可选

参数解释：

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

约束限制：

有效值支持两种格式：

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

其中：

取值范围：

无

默认取值：

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

SseC

string

当使用SSE-C方式时，必选

参数解释：

表示服务端加密是SSE-C方式。对象使用SSE-C加密方式。

约束限制：

仅支持AES256。

取值范围：

可选值：AES256，即选择SSE-C方式加密对象。

默认取值：

无

SseCKey

string

当使用SSE-C方式时，必选

参数解释：

SSE-C方式下加密使用的密钥，该密钥用于加密对象。

约束限制：

该头域由256bit的密钥经过Base64编码得到，示例：K7QkYpBkM5+hca27fsNkUnNVaobncnLht/rCB2o/9Cw=

取值范围：

无

默认取值：

无

返回结果

表2 返回结果

参数类型

描述

表3

说明：

该接口返回是一个Promise类型，需要使用Promise、async/await语法处理。

参数解释：

接口返回信息，详见表3。
表3 Response

参数名称

参数类型

描述

CommonMsg

ICommonMsg

参数解释：

接口调用完成后的公共信息，包含HTTP状态码，操作失败的错误码等，详见ICommonMsg。

InterfaceResult

表5

参数解释：

操作成功后的结果数据，详见表5。

约束限制：

当Status大于300时为空。
表4 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服务端返回的详细错误码。
表5 UploadPartOutput

字段名

类型

说明

RequestId

string

参数解释：

OBS服务端返回的请求ID。

ETag

string

参数解释：

对象的base64编码的128位MD5摘要。ETag是对象内容的唯一标识，可以通过该值识别对象内容是否有变化。比如上传对象时ETag为A，下载对象时ETag为B，则说明对象内容发生了变化。ETag只反映变化的内容，而不是其元数据。上传的对象或拷贝操作创建的对象，都有唯一的ETag。

约束限制：

当对象是服务端加密的对象时，ETag值不是对象的MD5值。

代码示例

本示例用于通过指定多段上传任务号（uploadId），上传段到examplebucket桶中，并且指定对象名为example/objectname。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
 
// 引入obs库
// 使用npm安装
const ObsClient = require("esdk-obs-nodejs");
// 使用源码安装
// var ObsClient = require('./lib/obs');

// 创建ObsClient实例
const obsClient = new ObsClient({
  // 推荐通过环境变量获取AKSK，这里也可以使用其他外部引入方式传入，如果使用硬编码可能会存在泄露风险
  // 您可以登录访问管理控制台获取访问密钥AK/SK，获取方式请参见https://support.huaweicloud.com/usermanual-ca/ca_01_0003.html
  access_key_id: process.env.ACCESS_KEY_ID,
  secret_access_key: process.env.SECRET_ACCESS_KEY,
  // 【可选】如果使用临时AK/SK和SecurityToken访问OBS，同样建议您尽量避免使用硬编码，以降低信息泄露风险。您可以通过环境变量获取访问密钥AK/SK，也可以使用其他外部引入方式传入
  // security_token: process.env.SECURITY_TOKEN,
  // endpoint填写Bucket对应的Endpoint, 这里以华北-北京四为例，其他地区请按实际情况填写
  server: "https://obs.cn-north-4.myhuaweicloud.com",
});

async function uploadPart() {
  try {
    const params = {
      // 指定存储桶名称
      Bucket: "examplebucket",
      // 指定对象，此处以 example/objectname 为例
      Key: "example/objectname",
      // 指定分段上传任务的ID
      UploadId: "0000000xxxxxxxx",
      // 指定上传段的段号，取值为从1到10000的整数。这次以1为例
      PartNumber: 1,
      // 指定待上传段的源文件路径，这里以localfile为例
      SourceFile: "localfile",
      // 指定分段大小，这里以5MB为例，单位是字节
      PartSize: 5 * 1024 * 1024,
      // 指定该分段的起始偏移大小，这里以0为例
      Offset: 0
    };
    // 上传段
    const result = await obsClient.uploadPart(params);
    if (result.CommonMsg.Status <= 300) {
      console.log("Upload part(%d) successful with bucket(%s) and object(%s)!", params.PartNumber, params.Bucket, params.Key);
      console.log("RequestId: %s", result.CommonMsg.RequestId);
      console.log("ETag: %s", result.InterfaceResult.ETag);
      return;
    };
    console.log("An ObsError was found, which means your request sent to OBS was rejected with an error response.");
    console.log("Status: %d", result.CommonMsg.Status);
    console.log("Code: %s", result.CommonMsg.Code);
    console.log("Message: %s", result.CommonMsg.Message);
    console.log("RequestId: %s", result.CommonMsg.RequestId);
  } catch (error) {
    console.log("An Exception was found, which means the client encountered an internal problem when attempting to communicate with OBS, for example, the client was unable to access the network.");
    console.log(error);
  };
};

uploadPart();
父主题： 多段相关接口

相关文档