tigris-object-operations

Tigris 对象操作

前置条件

在进行任何操作之前，如果尚未安装 Tigris CLI，请先安装：

tigris help || npm install -g @tigrisdata/cli

如果需要安装，请告诉用户：“我正在安装 Tigris CLI（@tigrisdata/cli），以便我们使用 Tigris 对象存储。”

概览

Tigris Storage 提供对象操作：上传（put）、下载（get）、删除（remove）、列出、元数据（head）和预签名 URL。

所有方法都返回 TigrisStorageResponse<T, E>——请先检查 error 属性。

快速参考

操作	函数	关键参数
上传	put(path, body, options)	path、body、access、contentType
下载	get(path, format, options)	path、format（string/file/stream）
删除	remove(path, options)	path
列出	list(options)	prefix、limit、paginationToken
元数据	head(path, options)	path
预签名 URL	getPresignedUrl(path, options)	path、operation（get/put）

上传（put）

import { put } from "@tigrisdata/storage";

// Simple upload
const result = await put("simple.txt", "Hello, World!");
if (result.error) {
  console.error("Error:", result.error);
} else {
  console.log("Uploaded:", result.data?.url);
}

// Large file with progress
const result = await put("large.mp4", fileStream, {
  multipart: true,
  onUploadProgress: ({ loaded, total, percentage }) => {
    console.log(`${loaded}/${total} bytes (${percentage}%)`);
  },
});

// Prevent overwrite
const result = await put("config.json", config, {
  allowOverwrite: false,
});

Put 选项

选项	值	默认值	用途
access	public/private	-	对象可见性
addRandomSuffix	boolean	false	避免名称冲突
allowOverwrite	boolean	true	允许替换现有对象
contentType	string	inferred	MIME 类型
contentDisposition	inline/attachment	inline	下载行为
multipart	boolean	false	为大文件启用
onUploadProgress	callback	-	跟踪上传进度

下载（get）

import { get } from "@tigrisdata/storage";

// Get as string
const result = await get("object.txt", "string");
if (result.error) {
  console.error("Error:", result.error);
} else {
  console.log("Content:", result.data);
}

// Get as file (triggers download in browser)
const result = await get("object.pdf", "file", {
  contentDisposition: "attachment",
});

// Get as stream
const result = await get("video.mp4", "stream");
const reader = result.data?.getReader();
// Process stream...

Get 选项

选项	值	默认值	用途
contentDisposition	inline/attachment	inline	下载行为
contentType	string	from upload	MIME 类型
encoding	string	utf-8	文本编码
snapshotVersion	string	-	从快照读取

删除（remove）

import { remove } from "@tigrisdata/storage";

const result = await remove("object.txt");
if (result.error) {
  console.error("Error:", result.error);
} else {
  console.log("Deleted successfully");
}

列出对象

import { list } from "@tigrisdata/storage";

// List all objects
const result = await list();
console.log("Objects:", result.data?.items);

// List with prefix (folders)
const result = await list({ prefix: "images/" });

// List with pagination
const allFiles = [];
let currentPage = await list({ limit: 10 });
allFiles.push(...currentPage.data?.items);

while (currentPage.data?.hasMore) {
  currentPage = await list({
    limit: 10,
    paginationToken: currentPage.data?.paginationToken,
  });
  allFiles.push(...currentPage.data?.items);
}

List 选项

选项	用途
prefix	筛选以此前缀开头的键
delimiter	对键分组（例如，用“/”表示文件夹）
limit	返回的对象数量上限（默认值：100）
paginationToken	从上一次列表继续
snapshotVersion	从快照列出

对象元数据（head）

import { head } from "@tigrisdata/storage";

const result = await head("object.txt");
if (result.error) {
  console.error("Error:", result.error);
} else {
  console.log("Metadata:", result.data);
  // { path, size, contentType, modified, url, contentDisposition }
}

预签名 URL

import { getPresignedUrl } from "@tigrisdata/storage";

// Presigned URL for GET (temporary access)
const result = await getPresignedUrl("object.txt", {
  operation: "get",
  expiresIn: 3600, // 1 hour
});
console.log("URL:", result.data?.url);

// Presigned URL for PUT (allow client upload)
const result = await getPresignedUrl("upload.txt", {
  operation: "put",
  expiresIn: 600, // 10 minutes
});

预签名 URL 选项

选项	值	默认值	用途
operation	get/put	-	URL 用途
expiresIn	秒	3600	URL 过期时间
contentType	string	-	PUT 时为必需项

常见错误

错误	修正
未先检查 error	在读取 result.data 之前，始终检查 if (result.error)
get() 中的格式错误	使用 'string'、'file' 或 'stream'
忘记设置 multipart: true	为 >100MB 的文件启用
忽略分页	使用 hasMore 和 paginationToken

客户端上传

对于浏览器上传，请使用客户端包直接上传到 Tigris：

import { upload } from "@tigrisdata/storage/client";

const result = await upload(file.name, file, {
  url: "/api/upload", // Your backend endpoint
  onUploadProgress: ({ percentage }) => {
    console.log(`${percentage}%`);
  },
});

有关初始设置，请参阅 file-storage。