断点续传上传（Browser.js SDK）--对象存储-火山引擎

文档中心

导航

对象存储

断点续传上传（Browser.js SDK）

最近更新时间：2024.02.04 18:30:57首次发布时间：2022.07.25 14:32:29

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

注意事项

为了避免在浏览器环境中暴露您的火山引擎账号密钥信息（即 AccessKey ID 和 AccessKey Secret），强烈建议您使用临时访问凭证的方式执行 TOS 相关操作，详细说明，请参见使用 STS 临时 AK/SK+Token 访问火山引擎 TOS。
Endpoint 为 TOS 对外服务的访问域名。TOS 支持的 Endpoint 信息，请参见访问域名 Endpoint。
上传对象前，您必须具有 tos:PutObject 权限，具体操作，请参见权限配置指南。
上传对象时，对象名必须满足一定规范，详细信息，请参见对象命名规范。
TOS 是面向海量存储设计的分布式对象存储产品，内部分区存储了对象索引数据，为横向扩展您上传对象和下载对象时的最大吞吐量，和减小热点分区的概率，请您避免使用字典序递增的对象命名方式，详细信息，请参见性能优化。
如果桶中已经存在同名对象，则新对象会覆盖已有的对象。如果您的桶开启了版本控制，则会保留原有对象，并生成一个新版本号用于标识新上传的对象。
SDK 会将上传的状态信息记录在 Checkpoint 文件中，所以程序需要对 Checkpoint 文件有写权限。
使用断点续传上传时，文件上传的进度信息会记录在 Checkpoint 文件中，如果上传过程中某一分片上传失败，再次上传时会 Checkpoint 文件中记录的点继续上传。上传完成后， Checkpoint 文件会被删除。
如果上传过程中本地文件发生了改变，则会重新上传所有分片。

示例代码

上传文件

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

<!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="UTF-8" />
    <title>Document</title>
  </head>
  <body>
    <button id="upload">上传</button>
    <input id="file" type="file" />
    <!-- 导入 SDK 文件 -->
    <script src="https://tos-public.volccdn.com/obj/volc-tos-public/@volcengine/tos-sdk@latest/browser/tos.umd.production.min.js"></script>
    <script type="text/javascript">
      const client = new TOS({
        // yourRegion 填写 Bucket 所在地域。以华北2（北京)为例，yourRegion 填写为 cn-beijing。
        region: yourRegion,
        // 填写 endpoint 名称。
        endpoint: yourEndpoint,
        // 从 STS 服务获取的临时访问密钥（AccessKey ID 和 AccessKey Secret）。
        accessKeyId: yourAccessKey,
        accessKeySecret: yourSecretKey,
        // 从 STS 服务获取的安全令牌（SecurityToken）。
        stsToken: yourSecurityToken,
        // 填写 Bucket 名称。
        bucket: examplebucket,
      });

      const upload = document.getElementById('upload');
      upload.addEventListener('click', async () => {
        // 从输入框获取 file 对象，例如 <input type="file" id="file" />。
        const data = document.getElementById('file').files[0];
        console.log('data', data);
        // 或者创建并填写 Blob 数据。
        // const data = new Blob(['Hello TOS']);

        try {
          // 分片大小最小为 5MB
          const partSize = 5 * 1024 * 1024;

          const result = await client.uploadFile({
            key: 'exampledir/putObjectobject.txt',
            file: data,
            // 上传时指定分片大小
            partSize,
            // 分片并发数，默认为1
            taskNum: 5,
            progress: (p, cpt) => {
              abortCheckpoint = cpt;
              // 获取上传进度。
              console.log(p * 100);
            },
          });
          console.log(result);
        } catch (e) {
          console.log(e);
        }
      });
    </script>
  </body>
</html>

取消续传机制

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

<!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="UTF-8" />
    <title>Document</title>
  </head>
  <body>
    <button id="upload">上传</button>
    <input id="file" type="file" />
    <!-- 导入 SDK 文件 -->
    <script src="https://tos-public.volccdn.com/obj/volc-tos-public/@volcengine/tos-sdk@latest/browser/tos.umd.production.min.js"></script>
    <script type="text/javascript">
      const client = new TOS({
        // yourRegion 填写 Bucket 所在地域。以华北2（北京)为例，yourRegion 填写为 cn-beijing。
        region: yourRegion,
        // 填写 endpoint 名称。
        endpoint: yourEndpoint,
        // 从 STS 服务获取的临时访问密钥（AccessKey ID 和 AccessKey Secret）。
        accessKeyId: yourAccessKey,
        accessKeySecret: yourSecretKey,
        // 从 STS 服务获取的安全令牌（SecurityToken）。
        stsToken: yourSecurityToken,
        // 填写 Bucket 名称。
        bucket: examplebucket,
      });

      const upload = document.getElementById('upload');
      upload.addEventListener('click', async () => {
        // 从输入框获取 file 对象，例如 <input type="file" id="file" />。
        const data = document.getElementById('file').files[0];
        console.log('data', data);

        // 分片大小最小为 5MB
        const partSize = 5 * 1024 * 1024;

        // 生成 cancelTokenSource
        let cancelTokenSource = TOS.CancelToken.source();
        let tosCheckpoint;

        client.uploadFile({
          key: 'exampledir/canclePutObjectobject.txt',
          file: data,
          // 上传时指定分片大小
          partSize,
          // 注入 axios 的 cancelToken
          cancelToken: cancelTokenSource.token,
          progress: (percent, checkpoint) => {
            tosCheckpoint = checkpoint;
            console.log(percent, checkpoint);
          },
        });

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

        // 5 秒后继续上传
        setTimeout(() => {
          cancelTokenSource = TOS.CancelToken.source();
          client.uploadFile({
            key: 'exampledir/canclePutObjectobject.txt',
            file: data,
            // 上传时指定分片大小
            partSize,
            // 注入断点信息，继续上传
            checkpoint: tosCheckpoint,
            cancelToken: cancelTokenSource.token,
            progress: (percent, checkpoint) => {
              tosCheckpoint = checkpoint;
              console.log(percent, checkpoint);
            },
          });
        }, 5000);
      });
    </script>
  </body>
</html>