You need to enable JavaScript to run this app.
导航

断点续传(Node.js SDK)

最近更新时间2024.02.04 18:30:57

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

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

注意事项

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

示例代码

上传文件

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

// 导入 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 = 'example_dir/multipartExample';
    // 本地 example_dir 文件夹下的 multipartExample 文件.请确保该文件大小大于 10M
    const filePath = './example_dir/multipartExample';
    // 分片大小最小为 5MB
    const partSize = 6 * 1024 * 1024;

    // 获取上传任务 ID
    const { data } = await client.uploadFile({
      bucket: bucketName,
      key: objectName,
      // 上传的文件路径
      file: filePath,
      // 上传时指定分片大小
      partSize,
    });
    console.log('UploadFileInPart result', data);
  } catch (error) {
    handleError(error);
  }
}

main();

取消机制

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

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

import axios from 'axios';

// 创建客户端
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 文件.请确保该文件大小大于 10M
    const filePath = './example_dir/multipartExample';
    // 分片大小最小为 5MB
    const partSize = 5 * 1024 * 1024;
    // 生成cancelTokenSource
    let cancelTokenSource = axios.CancelToken.source();

    // 获取上传任务 ID
    client.uploadFile({
      bucket: bucketName,
      key: objectName,
      // 上传的文件路径
      file: filePath,
      // 上传时指定分片大小
      partSize,
      // 注入axios的cancelToken
      cancelToken: cancelTokenSource.token,
    });

    // 1秒后取消任务
    setTimeout(() => {
      cancelTokenSource.cancel('manual cancel');
      console.log('cancel request');
    }, 1000);
  } catch (error) {
    handleError(error);
  }
}

main();