断点续传下载（Harmony SDK）--对象存储-火山引擎

文档中心

导航

对象存储

断点续传下载（Harmony SDK）

最近更新时间：2025.04.09 10:53:38首次发布时间：2025.04.09 10:53:38

下载大文件时，可以使用 downloadFile 断点续传下载接口。断点续传下载使用了分片下载将内容写入到临时文件中，如果出现部分分片成功部分失败，可以记录下载成功和失败分片的信息，保存到 Checkpoint 文件中。再次下载相同对象时，只下载失败的分片。当分片全部成功时将临时文件重命名为正式文件，并删除 Checkpoint 文件。

注意事项

下载对象前，您必须具有 tos:GetObject 权限，具体操作，请参见权限配置指南。
对于开启多版本的桶，下载指定版本对象时，您必须具有 tos:GetObjectVersion 权限，具体操作，请参见权限配置指南。
如果应用程序会在同一时刻大量下载同一个对象，您的访问速度会受到 TOS 带宽及地域的限制。建议您使用 CDN 产品，提升性能的同时也能降低您的成本。通过 CDN 访问 TOS 的详细信息，请参见使用 CDN 加速访问 TOS 资源。
SDK 会将上传的状态信息记录在 Checkpoint 文件中，所以程序需要对 Checkpoint 文件有写权限。
使用断点续传下载时，文件下载的进度信息会记录在 Checkpoint 文件中，如果下载过程中某一分片下载失败，再次下载时会从 Checkpoint 文件中记录的点继续下载，从而达到断点续传的效果。下载完成后， Checkpoint 文件会被删除。
如果下载过程中文件的 ETag 发生变化、Part 丢失或被修改，则重新下载文件。

示例代码

断点续传下载

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

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/example.txt';
    const checkpointFile = './example_dir/example.checkpoint'
    // 上传对象
    client.downloadFile({
      Bucket: bucketName,
      Key: objectName,
      // 待上传文件
      FilePath: filePath,
      // 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.downloadFile({
      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, 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.downloadFile({
      Bucket: bucketName,
      Key: objectName,
      // 待上传文件
      FilePath: filePath,
      CancelHook: cancelHook,
      // checkpoint 文件保存路径
      CheckpointFile: checkpointFile,
      // 开启断点续传
      EnableCheckpoint: true,
    });

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

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

main();