文档中心

分片上传（Node.js SDK）

最近更新时间：2024.03.21 15:13:15

首次发布时间：2022.05.13 18:28:15

上传大对象时可以分成多个数据块（part）来分别上传，最后调用合并分片将上传的数据块合并为一个对象。

注意事项

分片上传前，您必须具有 tos:PutObject 权限，具体操作，请参见权限配置指南。
取消分片上传任务前，您必须具有 tos:AbortMultipartUpload 权限，具体操作，请参见权限配置指南。
分片编号从 1 开始，最大为 10000。除最后一个分片以外，其他分片大小最小为 4MiB。
上传对象时，对象名必须满足一定规范，详细信息，请参见对象命名规范。
TOS 是面向海量存储设计的分布式对象存储产品，内部分区存储了对象索引数据，为横向扩展您上传对象和下载对象时的最大吞吐量，和减小热点分区的概率，请您避免使用字典序递增的对象命名方式，详细信息，请参见性能优化。
如果桶中已经存在同名对象，则新对象会覆盖已有的对象。如果您的桶开启了版本控制，则会保留原有对象，并生成一个新版本号用于标识新上传的对象。

分片上传步骤

分片上传一般包含以下三个步骤：

初始化分片上传任务：调用 createMultipartUpload 方法返回 TOS 创建的全局唯一 UploadID。
上传分片
调用 uploadPart 方法上传分片数据。
说明
- 对于同一个分片上传任务(通过 UploadID 标识)，分片编号(PartNumber)标识了该分片在整个对象中的相对位置。若通过同一分片编号上多次上传数据，TOS 中会覆盖原始数据，并以最后一次上传数据为准。
- 响应头中包含了数据的 MD5 值，可通过 Etag 获取。合并分片时，您需指定当前分片上传任务中的所有分片信息(分片编号、ETag 值)。
完成分片上传：所有分片上传完成后，调用 completeMultipartUpload 方法将所有分片合并成一个完整的对象。

示例代码

分片上传完整过程

下面代码展示将本地文件通过分片的方式上传完整过程，并在上传时指定 ACL 为 Private，存储类型为低频存储以及添加自定义元数据。

// 导入 SDK, 当 TOS Node.JS SDK 版本小于 2.5.2 请把下方 TosClient 改成 TOS 导入
import { ACLType, StorageClassType, TosClient, TosClientError, TosServerError } from '@volcengine/tos-sdk';
import fs from 'fs';
import fsp from 'fs/promises';

// 创建客户端
const client = new TosClient({
  accessKeyId: process.env['TOS_ACCESS_KEY'],
  accessKeySecret: process.env['TOS_SECRET_KEY'],
  region: "Provide your region", // 填写 Bucket 所在地域。以华北2（北京)为例，则 "Provide your region" 填写为 cn-beijing。
  endpoint: "Provide your endpoint", // 填写域名地址
});

function handleError(error) {
  if (error instanceof TosClientError) {
    console.log('Client Err Msg:', error.message);
    console.log('Client Err Stack:', error.stack);
  } else if (error instanceof TosServerError) {
    console.log('Request ID:', error.requestId);
    console.log('Response Status Code:', error.statusCode);
    console.log('Response Header:', error.headers);
    console.log('Response Err Code:', error.code);
    console.log('Response Err Msg:', error.message);
  } else {
    console.log('unexpected exception, message: ', error);
  }
}

async function main() {
  try {
    const bucketName = 'node-sdk-test-bucket';
    const objectName = 'example_dir/multipartExample';
    // 本地 example_dir 文件夹下的 multipartExample 文件
    const filePath = './example_dir/multipartExample';
    // 初始化分片，指定对象权限为私有，存储类型为低频并设置元数据信息
    const {
      // 获取上传任务 ID
      data: { UploadId },
    } = await client.createMultipartUpload({
      bucket: bucketName,
      key: objectName,
      acl: ACLType.ACLPrivate,
      storageClass: StorageClassType.StorageClassIa,
      meta: { key: 'value ' },
    });
    console.log('CreateMultipartUploadV2 Upload ID:', UploadId);

    // 获取本地文件信息并准备进行分片
    const stats = await fsp.stat(filePath);
    // 文件总大小
    const totalSize = stats.size;
    // part size 大小设置为 5M
    const partSize = 5 * 1024 * 1024;
    let offset = 0;
    // partNumber 编号从 1 开始
    let partNumber = 1;
    const partsInfo = [];
    while (offset < totalSize) {
      const uploadResult = await client.uploadPart({
        bucket: bucketName,
        key: objectName,
        partNumber,
        uploadId: UploadId,
        body: fs.createReadStream(filePath, {
          start: offset,
          end: offset + partSize - 1,
        }),
      });
      const eTag = uploadResult.data.ETag;
      console.log(`partNumber${partNumber} Etag:`, eTag);
      partsInfo.push({
        partNumber,
        eTag,
      });
      partNumber++;
      offset += partSize;
    }
    console.log('parts information', partsInfo);

    // 完成分片上传
    const { data } = await client.completeMultipartUpload({
      bucket: bucketName,
      key: objectName,
      uploadId: UploadId,
      parts: partsInfo,
    });

    console.log('result data:', data);
  } catch (error) {
    handleError(error);
  }
}

main();

列举已上传分片

以下代码用于列举指定存储桶中指定对象已上传的分片信息。

// 导入 SDK, 当 TOS Node.JS SDK 版本小于 2.5.2 请把下方 TosClient 改成 TOS 导入
import { TosClient, TosClientError, TosServerError } from '@volcengine/tos-sdk';

// 创建客户端
const client = new TosClient({
  accessKeyId: process.env['TOS_ACCESS_KEY'],
  accessKeySecret: process.env['TOS_SECRET_KEY'],
  region: "Provide your region", // 填写 Bucket 所在地域。以华北2（北京)为例，则 "Provide your region" 填写为 cn-beijing。
  endpoint: "Provide your endpoint", // 填写域名地址
});

function handleError(error) {
  if (error instanceof TosClientError) {
    console.log('Client Err Msg:', error.message);
    console.log('Client Err Stack:', error.stack);
  } else if (error instanceof TosServerError) {
    console.log('Request ID:', error.requestId);
    console.log('Response Status Code:', error.statusCode);
    console.log('Response Header:', error.headers);
    console.log('Response Err Code:', error.code);
    console.log('Response Err Msg:', error.message);
  } else {
    console.log('unexpected exception, message: ', error);
  }
}

async function main() {
  try {
    const bucketName = 'node-sdk-test-bucket';
    const objectName = '*** Provide your object name ***';
    // 分片上传任务 ID，可以从 createMultipartUpload 接口获取
    const uploadId = '*** Provide upload ID ***';

    // 列举 uploadID 已上传分片信息
    for (let truncated = true, marker = 0; truncated; ) {
      const { data } = await client.listParts({
        bucket: bucketName,
        key: objectName,
        uploadId,
        partNumberMarker: marker,
      });

      truncated = data.IsTruncated;
      marker = data.NextPartNumberMarker;

      for (const part of data.Parts) {
        console.log(`Part Number: `, part.PartNumber);
        console.log(`ETag: `, part.ETag);
        console.log(`Size: `, part.Size);
      }
    }
  } catch (error) {
    handleError(error);
  }
}

main();

取消分片上传任务

您可以通过 abortMultipartUpload 方法来取消分片上传任务。当一个分片任务被取消后， TOS 会将已上传的分片数据删除，同时您无法再对此分片任务进行任何操作。

// 导入 SDK, 当 TOS Node.JS SDK 版本小于 2.5.2 请把下方 TosClient 改成 TOS 导入
import { TosClient, TosClientError, TosServerError } from '@volcengine/tos-sdk';

// 创建客户端
const client = new TosClient({
  accessKeyId: process.env['TOS_ACCESS_KEY'], 
  accessKeySecret: process.env['TOS_SECRET_KEY'], 
  region: "Provide your region", // 填写 Bucket 所在地域。以华北2（北京)为例，"Provide your region" 填写为 cn-beijing。
  endpoint: "Provide your endpoint", // 填写域名地址
});

async function main() {
  try {
    const bucketName = 'node-sdk-test-bucket';
    const objectName = '*** Provide your object name ***';
    // 分片上传任务 ID,可以从 createMultipartUpload 接口获取
    const uploadId = `*** Provide upload ID ***`;

    // 取消分片上传任务
    const { data } = await client.abortMultipartUpload({
      bucket: bucketName,
      key: objectName,
      uploadId,
    });

    console.log('result data:', data);
  } catch (error) {
    handleError(error);
  }
}

function handleError(error) {
  if (error instanceof TosClientError) {
    console.log('Client Err Msg:', error.message);
    console.log('Client Err Stack:', error.stack);
  } else if (error instanceof TosServerError) {
    console.log('Request ID:', error.requestId);
    console.log('Response Status Code:', error.statusCode);
    console.log('Response Header:', error.headers);
    console.log('Response Err Code:', error.code);
    console.log('Response Err Msg:', error.message);
  } else {
    console.log('unexpected exception, message: ', error);
  }
}

main();

对象存储