Cloud storage

uploadFile

1. API Description

API feature: upload files

API Declaration:

2.x version

uploadFile(options)

1.x version

uploadFile(localPath: string, cloudPath: string)

Note: v2.x is incompatible with v1.x.

2. Input Parameters

Field	Required	Type	Description
localPath	Yes	String	Local file path. It is recommended to pass an absolute path.
cloudPath	Required	String	Cloud file path: dir/data.txt
onProgress	Required	Function	Upload progress callback function

Note: When localPath is a folder, the SDK will attempt to find a file with the same name as the file in cloudPath within this folder (first-level directory, no deep traversal). For example, if cloudPath is dir/data.txt, it will look for 'data.txt'.

3. Return Results

N/A

4. Sample Code

import path from "path";

import CloudBase from "@cloudbase/manager-node";

const { storage } = new CloudBase({
  secretId: "Your SecretId",
  secretKey: "Your SecretKey",
  envId: "Your envId", // TCB environment ID, which can be obtained from the Tencent Cloud TCB console
});

async function test() {
  await storage.uploadFile({
    localPath: path.resolve("./data.txt"),
    cloudPath: "files/data.txt",
    onProgress: (data) => {},
  });
}

test();

uploadDirectory

1. API Description

API feature: Uploading folders

API Declaration:

2.x version

uploadDirectory(options)

1.x version

uploadDirectory(source: string, cloudPath: string)

Note: v2.x is incompatible with v1.x.

This API traverses all files in the target folder and uploads them while preserving the folder structure.

2. Input Parameters

Field	Required	Type	Description
localPath	Required	String	Local folder path
cloudPath	Required	String	Cloud folder path
onProgress	Required	Function	Upload progress callback function

3. Return Results

N/A

4. Sample Code

import path from "path";

import CloudBase from "@cloudbase/manager-node";

const { storage } = new CloudBase({
  secretId: "Your SecretId",
  secretKey: "Your SecretKey",
  envId: "Your envId", // TCB environment ID, which can be obtained from the Tencent Cloud TCB console
});

async function test() {
  await storage.uploadDirectory({
    localPath: path.resolve("./files"),
    cloudPath: "",
    onProgress: (data) => {},
  });
}

test();

downloadFile

1. API Description

API feature: download files

API Declaration:

2.x version

downloadFile(options)

1.x version

downloadFile(cloudPath: string, localPath)

Note: v2.x is incompatible with v1.x.

2. Input Parameters

Field	Required	Type	Description
cloudPath	Required	String	Cloud file path: dir/data.txt
localPath	Required	String	Local file storage path; the file name must be specified

3. Return Results

None (undefined)

4. Sample Code

import path from "path";

import CloudBase from "@cloudbase/manager-node";

const { storage } = new CloudBase({
  secretId: "Your SecretId",
  secretKey: "Your SecretKey",
  envId: "Your envId", // TCB environment ID, which can be obtained from the Tencent Cloud TCB console
});

async function test() {
  await storage.downloadFile({
    cloudPath: "files/data.txt",
    localPath: path.resolve("./data.txt"),
  });
}

test();

downloadDirectory

1. API Description

API feature: download folder

API Declaration:

2.x version

downloadDirectory(options)

1.x version

downloadDirectory(cloudPath: string, localPath: string)

Note: v2.x is incompatible with v1.x.

2. Input Parameters

Field	Required	Type	Description
cloudPath	Required	String	Cloud folder
localPath	Required	String	Local file storage path; the file name must be specified

3. Return Results

N/A

4. Sample Code

import path from "path";

import CloudBase from "@cloudbase/manager-node";

const { storage } = new CloudBase({
  secretId: "Your SecretId",
  secretKey: "Your SecretKey",
  envId: "Your envId", // TCB environment ID, which can be obtained from the Tencent Cloud TCB console
});

async function test() {
  await storage.downloadDirectory({
    cloudPath: "files/music",
    localPath: path.resolve("./music"),
  });
}

test();

NOTE:

• This operation traverses all files in the folder. If the number of files is too large, it may cause the execution to fail.
• When cloudPath does not exist, the SDK will not download the file and will not throw an error.

listDirectoryFiles

1. API Description

API feature: List all files in the folder

API declaration: listDirectoryFiles(cloudPath: string): Promise<IListFileInfo[]>

2. Input Parameters

Field	Required	Type	Description
cloudPath	Required	String	Cloud folder path: dir/data/

3. Return Results

Field	Required	Type	Description
-	Required	Array<FileItem>	File array

FileItem

Field	Type	Description
Key	String	Object Key
LastModified	String	Last modified time of the object, in ISO8601 format, such as 2019-05-24T10:56:40Z date
ETag	String	The entity tag (Entity Tag) of the object, which is an information tag that identifies the content of the object when it is created and can be used to check whether the content of the object has changed
Size	String	Object size, unit: bytes
Owner	String	Object owner information
StorageClass	String	COS storage type: Standard Storage STANDARD

4. Sample Code

import CloudBase from "@cloudbase/manager-node";

const { storage } = new CloudBase({
  secretId: "Your SecretId",
  secretKey: "Your SecretKey",
  envId: "Your envId", // TCB environment ID, which can be obtained from the Tencent Cloud TCB console
});

async function test() {
  const res1 = await storage.listDirectoryFiles("dir/data");

  const res2 = await storage.listDirectoryFiles("dir/data", 20);

  const res3 = await storage.listDirectoryFiles("dir/data", 20, "dir/dat");

  for (let item in res1) {
    console.log(item);
  }
}
test();

getFileInfo

1. API Description

API feature: Obtain file information

API declaration: getFileInfo(cloudPath: string): Promise<IFileInfo>

2. Input Parameters

Field	Required	Type	Description
cloudPath	Required	String	Cloud file path dir/data.txt

3. Return Results

Field	Required	Type	Description
Size	Required	String	File size, unit: KB
Type	Required	String	File type
Date	Required	String	Modification time
ETag	Yes	String	Entity tag of the object (Entity Tag)

4. Sample Code

import CloudBase from "@cloudbase/manager-node";

const { storage } = new CloudBase({
  secretId: "Your SecretId",
  secretKey: "Your SecretKey",
  envId: "Your envId", // TCB environment ID, which can be obtained from the Tencent Cloud TCB console
});

async function test() {
  const info = await storage.getFileInfo("files/data.txt");
  console.log(info);
}

test();

deleteFile

1. API Description

API feature: Batch delete files

API declaration: deleteFile(cloudPathList: string[])

2. Input Parameters

Field	Required	Type	Description
cloudPathList	Required	Array<String>	String array consisting of cloud file paths ['dir/data.txt']

3. Return Results

N/A

4. Sample Code

import CloudBase from "@cloudbase/manager-node";

const { storage } = new CloudBase({
  secretId: "Your SecretId",
  secretKey: "Your SecretKey",
  envId: "Your envId", // TCB environment ID, which can be obtained from the Tencent Cloud TCB console
});

async function test() {
  await storage.deleteFile(["files/data.txt"]);
}

test();

deleteDirectory

1. API Description

API feature: Delete a folder

API declaration: deleteDirectory(cloudPath: string)

2. Input Parameters

Field	Required	Type	Description
cloudPath	Required	String	Cloud folder path

Note: When cloudPath does not exist, the SDK will not throw an error.

3. Return Results

N/A

4. Sample Code

import CloudBase from "@cloudbase/manager-node";

const { storage } = new CloudBase({
  secretId: "Your SecretId",
  secretKey: "Your SecretKey",
  envId: "Your envId", // TCB environment ID, which can be obtained from the Tencent Cloud TCB console
});

async function test() {
  await storage.deleteDirectory("files/");
}

test();

getTemporaryUrl

1. API Description

API feature: Obtain a temporary download link for a file

API declaration: getTemporaryUrl(fileList: (string | TempUrlInfo)[]):Promise<Array.<FileUrlItem>>

2. Input Parameters

Field	Required	Type	Description
fileList	Required	String or Array.<TempUrlInfo>	Array of cloud file paths or Array of TempUrlInfo

TempUrlInfo

Field	Required	Type	Description
cloudPath	Required	String	Cloud file path
maxAge	Required	Number	Validity period of the temporary download link, unit: seconds

3. Return Results

Field	Required	Type	Description
-	Required	Array.<FileUrlItem>	List of file download URLs

FileUrlItem

Field	Required	Type	Description
fileId	Required	String	File Id
url	Required	String	download link

4. Sample Code

import CloudBase from "@cloudbase/manager-node";

const { storage } = new CloudBase({
  secretId: "Your SecretId",
  secretKey: "Your SecretKey",
  envId: "Your envId", // TCB environment ID, which can be obtained from the Tencent Cloud TCB console
});

async function test() {
  const urls = await storage.getTemporaryUrl(["files/data.txt"]);

  const urls2 = await storage.getTemporaryUrl([
    {
      cloudPath: "files/data.txt",
      maxAge: 86400,
    },
  ]);

  for (let item in urls) {
    console.log(item.url);
  }
}

test();

getStorageAcl

1. API Description

API feature: Obtain file storage permissions

API declaration: getStorageAcl(): Promise<string>

2. Input Parameters

Empty

3. Return Results

Field	Required	Type	Description
-	Required	String	Permission type

All permission types:

• READONLY: Readable by all users, writable only by the creator and administrators.
• PRIVATE: Readable and writable only by the creator and administrators.
• ADMINWRITE: Readable by all users, writable only by administrators.
• ADMINONLY: Readable and writable only by administrators

4. Sample Code

import CloudBase from "@cloudbase/manager-node";

const { storage } = new CloudBase({
  secretId: "Your SecretId",
  secretKey: "Your SecretKey",
  envId: "Your envId", // TCB environment ID, which can be obtained from the Tencent Cloud TCB console
});

async function test() {
  const acl = await storage.getStorageAcl();
  console.log(acl);
}

test();

setStorageAcl

1. API Description

API feature: Set file storage permissions

API declaration: setStorageAcl(acl: string):Promise<Object>

2. Input Parameters

Field	Required	Type	Description
acl	Yes	String	File storage permission description

Supported options for acl:

• READONLY: Readable by all users, writable only by the creator and administrators.
• PRIVATE: Readable and writable only by the creator and administrators.
• ADMINWRITE: Readable by all users, writable only by administrators.
• ADMINONLY: Readable and writable only by administrators

3. Return Results

Field	Required	Type	Description
RequestId	Required	String	Request ID

4. Sample Code

import CloudBase from "@cloudbase/manager-node";

const { storage } = new CloudBase({
  secretId: "Your SecretId",
  secretKey: "Your SecretKey",
  envId: "Your envId", // TCB environment ID, which can be obtained from the Tencent Cloud TCB console
});

async function test() {
  await storage.setStorageAcl("READONLY");
}

test();

---

listCurrentDirectory

1. API Description

API feature: List files and subdirectories in the specified directory (non-recursive, current level only)

API declaration: app.storage.listCurrentDirectory(dirPath?: string): Promise<Object>

version tip

This API has been supported since v5.0.0.

2. Input Parameters

Field	Required	Type	Description
dirPath	Optional	String	Cloud directory path. If not provided, the root directory is listed; no trailing / required.

3. Return Results

Field	Type	Description
files	IListFileInfo[]	File list at the current level
directories	String[]	List of subdirectory names at the current level

4. Sample Code

const CloudBase = require('@cloudbase/manager-node')
const app = new CloudBase({ secretId: 'Your SecretId', secretKey: 'Your SecretKey', envId: 'your-env-id' })

async function test() {
  const { files, directories } = await app.storage.listCurrentDirectory('images')
  console.log('File:', files)
  console.log('Subdirectory:', directories)
}

test()

copyFile

1. API Description

API feature: copies a single cloud file to a new path

API declaration: app.storage.copyFile(options: ICopyOptions): Promise<ICopyResult>

version tip

This API has been supported since v5.0.0.

2. Input Parameters

ICopyOptions

Field	Required	Type	Description
sourcePath	Required	String	Source file cloud path, for example images/a.jpg
destPath	Required	String	Target file cloud path, for example backup/a.jpg
force	No	Boolean	whether to forcibly overwrite existing target files, defaults to false
skipExisting	No	Boolean	Skip if target already exists (without error), default false

3. Return Results

ICopyResult

Field	Type	Description
success	Boolean	whether the operation was successful
sourcePath	String	Source path
destPath	String	Target path
size	Number	File size (bytes)
status	String	Status: copied / skipped / failed
error	String	Error message when the operation fails

4. Sample Code

async function test() {
  const result = await app.storage.copyFile({
    sourcePath: 'images/logo.png',
    destPath: 'backup/logo.png',
    force: true
  })
  console.log('Copy result:', result)
}

test()

copyDirectory

1. API Description

API feature: recursively copies cloud directories to a new path, supports glob filtering and concurrency control

API declaration: app.storage.copyDirectory(options: ICopyDirectoryOptions): Promise<ICopyResult[]>

version tip

This API has been supported since v5.0.0.

2. Input Parameters

ICopyDirectoryOptions (extends ICopyOptions)

Field	Required	Type	Description
sourcePath	Required	String	Cloud path of the source directory
destPath	Required	String	Cloud path of the target directory
force	No	Boolean	whether to forcibly overwrite existing files, defaults to false
skipExisting	No	Boolean	Skip if target already exists, default false
include	No	String | String[]	Include pattern (glob format)
exclude	No	String | String[]	Exclude pattern (glob format)
parallel	No	Number	Concurrency, default 20
onProgress	No	Function	Progress callback (info: ICopyProgress) => void

ICopyProgress

Field	Type	Description
copied	Number	Copied count
skipped	Number	Skipped count
total	Number	Total file count
currentFile	String	File being processed

3. Return Results

Promise<ICopyResult[]> — An array of copy results for each file, with the same structure as the return value of copyFile.

4. Sample Code

async function test() {
  const results = await app.storage.copyDirectory({
    sourcePath: 'src-dir/',
    destPath: 'dest-dir/',
    include: ['**/*.jpg', '**/*.png'],
    force: true,
    onProgress: ({ copied, total }) => console.log(`${copied}/${total}`)
  })
  console.log('Directory copy completed, total:', results.length, 'files')
}

test()

moveFile

1. API Description

API feature: moves a single cloud file to a new path (copies and then deletes the source file)

API declaration: app.storage.moveFile(options: ICopyOptions): Promise<ICopyResult>

version tip

This API has been supported since v5.0.0.

2. Input Parameters

Same as copyFile, with exactly the same parameter structure.

ICopyOptions

Field	Required	Type	Description
sourcePath	Required	String	Cloud path of the source file
destPath	Required	String	Cloud path of the target file
force	No	Boolean	whether to forcibly overwrite existing target files, defaults to false
skipExisting	No	Boolean	Skip if target already exists, default false

3. Return Results

Same as copyFile, returns ICopyResult.

4. Sample Code

async function test() {
  const result = await app.storage.moveFile({
    sourcePath: 'temp/upload.jpg',
    destPath: 'images/upload.jpg',
    force: true
  })
  console.log('Move result:', result.status)
}

test()

moveDirectory

1. API Description

API feature: recursively move a cloud directory to a new path (copy and then delete the source directory)

API declaration: app.storage.moveDirectory(options: ICopyDirectoryOptions): Promise<ICopyResult[]>

version tip

This API has been supported since v5.0.0.

2. Input Parameters

Same as copyDirectory, with exactly the same parameter structure.

3. Return Results

Same as copyDirectory, returns ICopyResult[].

4. Sample Code

async function test() {
  const results = await app.storage.moveDirectory({
    sourcePath: 'old-dir/',
    destPath: 'new-dir/',
    force: true
  })
  console.log('Directory move completed, total:', results.length, 'files')
}

test()

searchFiles

1. API Description

API feature: Search for files in a specified directory using a glob pattern or regular expression.

API declaration: app.storage.searchFiles(options: ISearchOptions): Promise<ISearchResult[]>

version tip

This API has been supported since v5.0.0.

2. Input Parameters

ISearchOptions

Field	Required	Type	Description
pattern	Required	String	Search pattern, supporting glob or regular expression strings
path	Optional	String	Search directory path. If not specified, the root directory is searched.
isRegex	No	Boolean	When true, parses pattern as a regular expression; default false
fileType	Optional	String	File type filtering, e.g., jpg, png
limit	Optional	Number	Maximum number of results to return, default 100
includeDetails	No	Boolean	whether to include file size and modification time, default false

3. Return Results

ISearchResult[]

Field	Type	Description
key	String	Cloud file path
type	String	Type: file / directory
size	Number	File size (bytes), only valid for files
lastModified	String	Last modified time (in ISO format), only valid for files

4. Sample Code

async function test() {
  const results = await app.storage.searchFiles({
    pattern: '**/*.jpg',
    path: 'images',
    limit: 50,
    includeDetails: true
  })
  results.forEach(f => console.log(f.key, f.size))
}

test()