You need to enable JavaScript to run this app.
导航
对象存储
  • 文档首页
    • /对象存储/SDK 参考/Harmony/对象接口/上传对象/断点续传（Harmony SDK）
断点续传（Harmony SDK）
最近更新时间：2025.04.09 10:53:38首次发布时间：2025.04.09 10:53:38
我的收藏
有用
有用
无用
无用

使用断点续传上传的方式将文件上传到 TOS 时，您可以设置分片大小、上传分片的并发数、上传时客户端限速、事件回调函数等。上传过程中，如果出现网络异常或程序崩溃导致文件上传失败时，将从断点记录处继续上传未上传完成的部分。在上传的过程中可以通过调用传入的 CancelHook 中的 Cancel 方法取消对象上传。

注意事项

  • 上传对象前，您必须具有 tos:PutObject 权限，具体操作，请参见权限配置指南。
  • 上传对象时，对象名必须满足一定规范，详细信息，请参见对象命名规范。
  • TOS 是面向海量存储设计的分布式对象存储产品，内部分区存储了对象索引数据，为横向扩展您上传对象和下载对象时的最大吞吐量，和减小热点分区的概率，请您避免使用字典序递增的对象命名方式，详细信息，请参见性能优化。
  • 如果桶中已经存在同名对象，则新对象会覆盖已有的对象。如果您的桶开启了版本控制，则会保留原有对象，并生成一个新版本号用于标识新上传的对象。
  • SDK 会将上传的状态信息记录在 Checkpoint 文件中，所以程序需要对 Checkpoint 文件有写权限。
  • 使用断点续传上传时，文件上传的进度信息会记录在 Checkpoint 文件中，如果上传过程中某一分片上传失败，再次上传时会 Checkpoint 文件中记录的点继续上传。上传完成后， Checkpoint 文件会被删除。
  • 如果上传过程中本地文件发生了改变，则会重新上传所有分片。

示例代码

上传文件

以下代码用于断点续传的方式上传文件。

/*
 * Copyright (c) 2024 Beijing Volcano Engine Technology Ltd and/or its affiliates
 *  SPDX-License-Identifier: MIT
 */

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/example.txt';
    const filePath = './example_dir/multipartExample';
    const checkpointFile = './example_dir/example.checkpoint';
    // 上传对象
    await client.uploadFile({
      Bucket: bucketName,
      Key: objectName,
      // 待上传文件
      FilePath: filePath,
      // 并发任务数
      TaskNum: 1,
      // 分片大小
      PartSize: 10 * 1024 * 1024,
      // checkpoint 文件保存路径
      CheckpointFile: checkpointFile,
      // 开启断点续传
      EnableCheckpoint: true,
    });
  } catch (error) {
    handleError(error);
  }
}

main();

配置进度条

断点续传上传时可通过 DataTransferStatusChange 参数接收上传进度，代码示例如下。

import { DataTransferType, 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/example.txt';
    const filePath = './example_dir/multipartExample';
    const checkpointFile = './example_dir/example.checkpoint';
    // 上传对象
    await client.uploadFile({
      Bucket: bucketName,
      Key: objectName,
      FilePath: filePath,
      // checkpoint 文件保存路径
      CheckpointFile: checkpointFile,
      // 开启断点续传
      EnableCheckpoint: true,
      DataTransferListener:{
        DataTransferStatusChange(event){
          if (event.Type === DataTransferType.Started) {
            console.log('Data Transfer Started');
          } else if (event.Type === DataTransferType.RW) {
            const percent = ((event.ConsumedBytes / event.TotalBytes) * 100).toFixed(2);
            console.log(`Once Read:${event.RWOnceBytes},ConsumerBytes/TotalBytes: ${event.ConsumedBytes}/${event.TotalBytes},${percent}%`);
          } else if (event.Type === DataTransferType.Succeed) {
            const percent = ((event.ConsumedBytes / event.TotalBytes) * 100).toFixed(2);
            console.log(`Data Transfer Succeed, ConsumerBytes/TotalBytes:${event.ConsumedBytes}/${event.TotalBytes},${percent}%`);
          } else if (event.Type === DataTransferType.Failed) {
            console.log('Data Transfer Failed');
          }
        }
      }
    });
  } catch (error) {
    handleError(error);
  }
}

main();

处理事件回调

以下代码用于自定义断点续传上传回调函数。

import { TosClient, TosClientError, TosServerError, UploadEventType } 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/example.txt';
    const filePath = './example_dir/multipartExample';
    const checkpointFile = './example_dir/example.checkpoint';
    // 上传对象
    await client.uploadFile({
      Bucket: bucketName,
      Key: objectName,
      // 待上传文件
      FilePath: filePath,
      // checkpoint 文件保存路径
      CheckpointFile: checkpointFile,
      // 开启断点续传
      EnableCheckpoint: true,
      UploadEventListener:{
        EventChange(event){
          switch (event.Type) {
            case UploadEventType.CreateMultipartUploadSucceed: {
              console.log(`Upload to ${event.Bucket} ${event.Key} create multipart upload success, upload id:${event.UploadID}`);
              break;
            }
            case UploadEventType.CreateMultipartUploadFailed: {
              console.log(`Upload to ${event.Bucket} ${event.Key} create multipart upload fail, upload id:${event.UploadID}`);
              break;
            }
            case UploadEventType.UploadPartSucceed: {
              console.log(`Upload to${event.Bucket} ${event.Key} part success, UploadPartInfo:%o`, event.UploadPartInfo);
              break;
            }
            case UploadEventType.UploadPartAborted: {
              console.log(`Upload to ${event.Bucket} ${event.Key} part aborted, upload id:${event.UploadID}`);
              break;
            }
            case UploadEventType.UploadPartFailed: {
              console.log(`Upload to ${event.Bucket} ${event.Key} part fail, upload id:${event.UploadID}`);
              break;
            }
            case UploadEventType.CompleteMultipartUploadSucceed: {
              console.log(`Upload to ${event.Bucket} ${event.Key} success, upload id:${event.UploadID}`);
              break;
            }
            case UploadEventType.CompleteMultipartUploadFailed: {
              console.log(`Upload to ${event.Bucket} ${event.Key} fail, upload id:${event.UploadID}, err: %o`, event.Err);
              break;
            }
          }
        }
      }
    });
  } catch (error) {
    handleError(error);
  }
}

main();

取消机制

以下代码用于在运行时取消正在执行的断点续传上传任务。

import { TosClient, TosClientError, TosServerError, UploadEventType, CancelHook } 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() {
  const cancelHook = new CancelHook();
  try {
    const bucketName = 'harmony-sdk-test-bucket';
    const objectName = 'example_dir/example.txt';
    const filePath = './example_dir/multipartExample';
    const checkpointFile = './example_dir/example.checkpoint'
    // 上传对象
    client.uploadFile({
      Bucket: bucketName,
      Key: objectName,
      // 待上传文件
      FilePath: filePath,
      CancelHook: cancelHook,
      // checkpoint 文件保存路径
      CheckpointFile: checkpointFile,
      // 开启断点续传
      EnableCheckpoint: true,
    });

    // 1秒后取消任务
    setTimeout(() => {
      cancelHook.Cancel();
    }, 1000)

  } catch (error) {
    handleError(error);
  }
}

main();