分片上传（Harmony SDK）--对象存储-火山引擎

文档中心

立即注册

导航

对象存储

分片上传（Harmony SDK）

最近更新时间：2024.12.23 17:29:48首次发布时间：2024.12.23 17:29:48

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

注意事项

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

分片上传步骤

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

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

示例代码

分片上传完整过程

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

import { TosClient, TosClientError, TosServerError } from '@volcengine/tos_harmonyos_sdk';

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

function handleError(error: 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 = 'harmony-sdk-test-bucket';
    const objectName = 'example_dir/multipartExample';
    // 本地 example_dir 文件夹下的 multipartExample 文件
    const filePath = './example_dir/multipartExample';
    // 初始化分片，指定对象权限为私有，存储类型为低频并设置元数据信息
    const res = await client.createMultipartUpload({
      Bucket: bucketName,
      Key: objectName,
      ACL: ACLType.ACLPrivate,
      StorageClass: StorageClassType.StorageClassIa,
    });
    console.log('CreateMultipartUploadV2 Upload ID:', res.UploadId);

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

    // 完成分片上传
    const completeRes = await client.completeMultipartUpload({
      Bucket: bucketName,
      Key: objectName,
      UploadID: res.UploadId,
      Parts: partsInfo,
    });

    console.log('result status:', completeRes.StatusCode);
  } catch (error) {
    handleError(error);
  }
}

main();

列举已上传分片

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

import { TosClient, TosClientError, TosServerError } from '@volcengine/tos_harmonyos_sdk';

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

function handleError(error: 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 已上传分片信息
    let marker = 0;
    while (true) {
      const res= await client.listParts({
        Bucket: bucketName,
        Key: objectName,
        UploadId: uploadId,
        PartNumberMarker: marker,
      });
      
      if (!res.IsTruncated || res.NextPartNumberMarker === undefined) {
        break;
      }
      marker = res.NextPartNumberMarker;

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

取消分片上传任务

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

import { TosClient, TosClientError, TosServerError } from '@volcengine/tos_harmonyos_sdk';

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

function handleError(error: 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 = 'harmony-sdk-test-bucket';
    const objectName = '*** Provide your object name ***';
    // 分片上传任务 ID,可以从 createMultipartUpload 接口获取
    const uploadId = `*** Provide upload ID ***`;

    // 取消分片上传任务
    const res = await client.abortMultipartUpload({
      Bucket: bucketName,
      Key: objectName,
      UploadID: uploadId,
    });

    console.log('result status:', res.StatusCode);
  } catch (error) {
    handleError(error);
  }
}
main();