限定条件下载（Browser.js SDK）--对象存储-火山引擎

文档中心

立即注册

导航

对象存储

限定条件下载（Browser.js SDK）

最近更新时间：2024.02.04 18:31:06首次发布时间：2023.07.08 17:33:01

下载文件（Object）时，可以指定一个或多个限定条件。满足限定条件则下载，条件不满足则返回错误且不会触发下载行为。

注意事项

为了避免在浏览器环境中暴露您的火山引擎账号密钥信息（即 AccessKey ID 和 AccessKey Secret），强烈建议您使用临时访问凭证的方式执行 TOS 相关操作，详细说明，请参见使用 STS 临时 AK/SK+Token 访问火山引擎 TOS。
Endpoint 为 TOS 对外服务的访问域名。TOS 支持的 Endpoint 信息，请参见访问域名 Endpoint。
下载对象前，您必须具有 tos:GetObject 权限，详细信息，请参见权限配置指南。
对于开启多版本的桶，下载指定版本对象时，您必须具有 tos:GetObjectVersion 权限，详细信息，请见权限配置指南。
如果应用程序会在同一时刻大量下载同一个对象，您的访问速度会受到 TOS 带宽及地域的限制。建议您使用 CDN 产品，提升性能的同时也能降低您的成本。通过 CDN 访问 TOS 的详细信息，请参见使用 CDN 加速访问 TOS 资源。
不同条件可以进行组合，例如：If-Modified-Since 和 If-Unmodified-Since 可以同时存在，If-Match 和 If-None-Match 也可以同时存在。
支持使用 TOS Browser SDK 的 headObject 接口获取对象 Etag 信息。

限定条件说明

下载对象时可以指定下载对象条件，当满足条件时进行下载对象。限定条件如下：

参数	描述
If-Match	只有当传入的 `ETag` 与对象的 `ETag` 相等才返回对象，否则返回 `412 Precondition Failed`。
If-None-Match	只有当传入的 `ETag` 与对象的 `ETag` 不相等才返回对象，否则返回 `304 Not Modified`。
If-Modified-Since	只有在对象自指定时间以来被修改过时才返回该对象，否则返回 `304 Not Modified`。
If-Unmodified-Since	只有在对象自指定时间以来未被修改过时才返回该对象，否则返回 `412 Precondition Failed`。

示例代码

以下示例代码用于指定条件下载文件。

<!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="UTF-8" />
    <title>Document</title>
  </head>
  <body>
    <button id="upload">上传</button>
    <button id="download">下载</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 name = 'exampledir/getobjectv2.txt';
      let targetObjectETag = '';

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

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

          await client.uploadFile({
            key: name,
            file: data,
            // 上传时指定分片大小
            partSize,
          });

          // 获取文件的 etag
          const result = await client.headObject({ key: name });
          targetObjectETag = result.headers.etag;
          console.log('targetObjectETag', targetObjectETag);
        } catch (e) {
          console.log(e);
        }
      });

      const download = document.getElementById('download');
      download.addEventListener('click', async () => {
        try {
          const result = await client.getObjectV2({
            key: name,
            // 指定下载条件
            ifMatch: targetObjectETag,
            dataType: 'blob',
          });
          const blob = result.data.content;
          // 创建标签。
          const link = document.createElement('a');
          // 将标签绑定 href 属性。
          link.href = window.URL.createObjectURL(blob);
          // 指定下载后的本地文件名称。
          link.download = 'getobjectv2.txt';
          // 下载 Object。
          link.click();
          // 移除绑定的 URL。
          window.URL.revokeObjectURL(link.href);
        } catch (e) {
          console.log(e);
        }
      });
    </script>
  </body>
</html>