跳到主要内容

SDK 管理文件

CloudBase 云存储提供了完整的文件管理功能，包括上传、下载、删除、复制文件以及获取临时链接等操作。本文将详细介绍如何使用这些功能

PG 模式

SDK 调用方式与传统模式完全一致，但底层链路改走 Storage API（不再客户端直传 COS），权限由 RLS 控制。如需了解差异，参见 PG 模式云存储 - 概述；服务端 / 跨语言调用见 HTTP API。

SDK 类型适用平台
小程序 SDK小程序
JS SDKWeb 浏览器
Node SDKNode.js 环境
HTTP API（传统模式）通用
HTTP API（PG 模式）通用

上传文件​

您可以上传任意数量、格式的文件至 CloudBase 云存储，也可以自定义文件、目录的路径和名字。

默认情况下，只有通过了 CloudBase 身份验证 的用户才可以向云存储空间上传/删除文件，因此在用户端上传文件时需先进行登录认证。

提示

您也可以使用 自定义安全规则，为云存储设置更宽松或更严格的读写权限。

使用 SDK 可以向云存储空间上传文件，并返回该文件全局唯一标识 fileID。

import tcb from "@cloudbase/js-sdk";

const app = tcb.init({
  env: "your-env-id",
});

app
  .uploadFile({
    // 云存储的路径
    cloudPath: "dirname/filename",
    // 需要上传的文件，File 类型
    filePath: document.getElementById("file").files[0],
  })
  .then((res) => {
    // 返回文件 ID
    console.log(res.fileID);
  });
提示
  • 上传时文件名需要符合 文件名规范；
  • cloudPath 为云存储文件或文件夹的相对根目录的路径，为 目录/文件名 的形式，cloudPath 不需要以 / 开头；
  • 如果将文件上传至同一路径则是覆盖写，默认情况下，不允许 A 用户覆盖写 B 用户的文件。

下载文件​

默认情况下，CloudBase 云存储内的文件对所有用户公开可读。

提示

您也可以使用 自定义安全规则，为云存储设置更宽松或更严格的读写权限。

使用 SDK 可以下载云存储空间里的文件，调用时只需传入云存储文件全网唯一的 fileID 。

import tcb from "@cloudbase/js-sdk";

const app = tcb.init({
  env: "your-env-id",
});

app
  .downloadFile({
    fileID: "cloud://a/b/c",
  })
  .then((res) => {
    console.log(res);
  });
提示

如果您需要在浏览器中可以直接下载云存储里的文件，或将云存储作为图床，可以使用文件的下载地址或获取文件临时链接。

删除文件​

默认情况下，只有通过了 CloudBase 身份验证 的用户才可以向云存储空间上传/删除文件，因此在用户端删除文件时需先进行登录认证。

提示
  • 单次调用最多可以删除 50 个文件，更多需分批处理；
  • 默认情况下，只有该文件的上传创建者和管理员才有权删除相应的文件，不允许 A 用户删除 B 用户的文件；
  • 您也可以使用 自定义安全规则，为云存储设置更宽松或更严格的读写权限。

使用 SDK 调用 deleteFile 方法可以删除云存储空间单个或多个指定文件。

import tcb from "@cloudbase/js-sdk";

const app = tcb.init({
  env: "your-env-id",
});

const auth = app.auth({
  persistence: "local", //用户显式退出或更改密码之前的30天一直有效
});

app
  .deleteFile({
    fileList: ["cloud://a/b/c", "cloud://d/e/f"],
  })
  .then((res) => {
    console.log(res.fileList);
  });

复制文件​

您可以通过 Node SDK 和 Open API 将云存储空间中的文件复制到指定路径，并通过参数设置达到移动文件的效果，该 API 支持批量复制。API 文档参考：

说明
  • 目标文件路径不能和源文件路径一致
  • 不支持复制的过程中重命名，即复制前后文件名应保持一致
  • 复制操作的执行受到存储桶权限、源文件和路径权限、目标文件和路径权限影响，执行复制操作不会改变文件原有权限
  • 单次操作的文件数量不超过 50 个，更多需分批处理
const tcb = require("@cloudbase/node-sdk");
const app = tcb.init({
  env: "xxx", // 填入环境 ID
});

const path = "a.png"; // 填入源文件路径
const fileList = [
  {
    srcPath: path,
    dstPath: `dst/${path}`, // 填入目标文件路径
    removeOriginal: true, // 复制后删除源文件，等效为移动文件
  },
];
const result = await app.copyFile({
  fileList,
});

获取临时链接​

您可以使用 fileID 换取云存储空间指定文件的 https 链接（云存储提供免费的 CDN 域名）。

import tcb from "@cloudbase/js-sdk";

const app = tcb.init({
  env: "your-env-id",
});

const auth = app.auth({
  persistence: "local", //用户显式退出或更改密码之前的30天一直有效
});

app
  .getTempFileURL({
    fileList: ["cloud://a/b/c", "cloud://d/e/f"],
  })
  .then((res) => {
    console.log(res.fileList);
  });
提示
  • 公有读的文件获取的 https 链接不会过期，例如默认情况下的权限就是公有读，获取的链接永久有效；
  • 私有读的文件获取的 https 链接为临时链接，例如您可以结合用户身份认证和安全规则设置文件的权限为仅文件的上传创建者或管理员可读，此时只有通过了云开发身份验证的用户才有权限换取临时链接；
  • 有效期可以动态设置，超过有效期再请求临时链接时会被拒绝，保证了文件的安全；
  • 一次最多可以取 50 个，更多需分批处理。

设置公有读步骤​

  1. 前往云开发平台 - 云存储 - 权限设置

文件名命名限制​

在使用 CloudBase 云存储时，文件名需要遵循以下规则：

  • 不能为空
  • 不能以/开头
  • 不能出现连续/
  • 编码长度最大为 850 个字节
  • 推荐使用大小写英文字母、数字，即[a-z，A-Z，0-9]和符号 -，!，_，.，* 及其组合
  • 不支持 ASCII 控制字符中的字符上(↑)，字符下(↓)，字符右(→)，字符左(←)，分别对应 CAN(24)，EM(25)，SUB(26)，ESC(27)
  • 如果用户上传的文件或文件夹的名字带有中文，在访问和请求这个文件或文件夹时，中文部分将按照 URL Encode 规则转化为百分号编码。
  • 不建议使用的特殊字符: ` ^ " \ [ ] ~ % # \ > < 及 ASCII 128-255 十进制
  • 可能需特殊处理后再使用的特殊字符: ， : ; = & $ @ + ?（空格）及 ASCII 字符范围：00-1F 十六进制（0-31 十进制）以及 7F（127 十进制）