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

上传段(Node.js SDK)

功能说明

初始化分段上传任务后，通过分段上传任务的ID，上传段到指定桶中。

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

接口约束

  • 您必须是桶拥有者或拥有合并段的权限，才能合并段。建议使用IAM或桶策略进行授权，如果使用IAM则需授予obs:object:PutObject权限，如果使用桶策略则需授予PutObject权限。相关授权方式介绍可参见OBS权限控制概述，配置方式详见使用IAM自定义策略、配置对象策略。
  • OBS支持的Region与Endpoint的对应关系，详细信息请参见地区与终端节点。
  • 上传段接口要求除最后一段以外，其他段的大小范围是100KB~5GB，最后一段的大小范围是0~5GB。但是上传段接口并不会立即校验上传段的大小（因为不知道是否为最后一块）；只有调用合并段接口时才会校验。
  • 上传的段的编号有范围限制，其范围是1~10000。
  • 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();

相关文档