tigris-object-operations

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Tigris Object Operations

Tigris 对象操作

Overview

概述

Tigris Storage provides object operations: upload (put), download (get), delete (remove), list, metadata (head), and presigned URLs.

All methods return

TigrisStorageResponse<T, E>

- check

error

property first.

Tigris Storage 提供对象操作功能：上传（put）、下载（get）、删除（remove）、列出对象、获取元数据（head）以及生成预签名URL。

所有方法都会返回

TigrisStorageResponse<T, E>

- 请先检查

error

属性。

Quick Reference

快速参考

Operation	Function	Key Parameters
Upload	`put(path, body, options)`	path, body, access, contentType
Download	`get(path, format, options)`	path, format (string/file/stream)
Delete	`remove(path, options)`	path
List	`list(options)`	prefix, limit, paginationToken
Metadata	`head(path, options)`	path
Presigned URL	`getPresignedUrl(path, options)`	path, operation (get/put)

操作	函数	关键参数
上传	`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)

Upload (put)

上传（put）

typescript

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,
});

typescript

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

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

// 带进度跟踪的大文件上传
const result = await put("large.mp4", fileStream, {
  multipart: true,
  onUploadProgress: ({ loaded, total, percentage }) => {
    console.log(`${loaded}/${total} bytes (${percentage}%)`);
  },
});

// 禁止覆盖已有对象
const result = await put("config.json", config, {
  allowOverwrite: false,
});

Put Options

Put 配置项

Option	Values	Default	Purpose
access	public/private	-	Object visibility
addRandomSuffix	boolean	false	Avoid naming collisions
allowOverwrite	boolean	true	Allow replacing existing
contentType	string	inferred	MIME type
contentDisposition	inline/attachment	inline	Download behavior
multipart	boolean	false	Enable for large files
onUploadProgress	callback	-	Track upload progress

配置项	可选值	默认值	用途
access	public/private	-	对象可见性
addRandomSuffix	boolean	false	避免命名冲突
allowOverwrite	boolean	true	是否允许覆盖已有对象
contentType	string	自动推断	MIME类型
contentDisposition	inline/attachment	inline	下载行为控制
multipart	boolean	false	大文件上传启用该选项
onUploadProgress	回调函数	-	跟踪上传进度

Download (get)

下载（get）

typescript

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...

typescript

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

// 以字符串形式获取内容
const result = await get("object.txt", "string");
if (result.error) {
  console.error("Error:", result.error);
} else {
  console.log("Content:", result.data);
}

// 以文件形式获取（在浏览器中触发下载）
const result = await get("object.pdf", "file", {
  contentDisposition: "attachment",
});

// 以流形式获取
const result = await get("video.mp4", "stream");
const reader = result.data?.getReader();
// 处理流数据...

Get Options

Get 配置项

Option	Values	Default	Purpose
contentDisposition	inline/attachment	inline	Download behavior
contentType	string	from upload	MIME type
encoding	string	utf-8	Text encoding
snapshotVersion	string	-	Read from snapshot

配置项	可选值	默认值	用途
contentDisposition	inline/attachment	inline	下载行为控制
contentType	string	上传时的值	MIME类型
encoding	string	utf-8	文本编码格式
snapshotVersion	string	-	从快照版本读取内容

Delete (remove)

删除（remove）

typescript

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

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

typescript

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

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

List Objects

列出对象

typescript

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);
}

typescript

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

// 列出所有对象
const result = await list();
console.log("Objects:", result.data?.items);

// 按前缀过滤列出对象（模拟文件夹）
const result = await list({ prefix: "images/" });

// 分页列出对象
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 Options

List 配置项

Option	Purpose
prefix	Filter keys starting with prefix
delimiter	Group keys (e.g., '/' for folders)
limit	Max objects to return (default: 100)
paginationToken	Continue from previous list
snapshotVersion	List from snapshot

配置项	用途
prefix	过滤以指定前缀开头的对象键
delimiter	对对象键进行分组（例如用'/'模拟文件夹）
limit	单次返回的最大对象数（默认：100）
paginationToken	从上次列出的位置继续查询
snapshotVersion	从快照版本中列出对象

Object Metadata (head)

对象元数据（head）

typescript

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 }
}

typescript

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 }
}

Presigned URLs

预签名URL

typescript

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
});

typescript

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

// 用于GET操作的预签名URL（临时访问权限）
const result = await getPresignedUrl("object.txt", {
  operation: "get",
  expiresIn: 3600, // 1小时
});
console.log("URL:", result.data?.url);

// 用于PUT操作的预签名URL（允许客户端直接上传）
const result = await getPresignedUrl("upload.txt", {
  operation: "put",
  expiresIn: 600, // 10分钟
});

Presigned URL Options

预签名URL配置项

Option	Values	Default	Purpose
operation	get/put	-	URL purpose
expiresIn	seconds	3600	URL expiration
contentType	string	-	Require for PUT

配置项	可选值	默认值	用途
operation	get/put	-	URL的用途类型
expiresIn	秒数	3600	URL的过期时间
contentType	string	-	PUT操作时必填

Common Mistakes

常见错误

Mistake	Fix
Not checking `error` first	Always check `if (result.error)` before `result.data`
Wrong format in `get()`	Use 'string', 'file', or 'stream'
Forgetting `multipart: true`	Enable for files >100MB
Ignoring pagination	Use `hasMore` and `paginationToken`

错误操作	修复方案
未优先检查 `error` 属性	在访问 `result.data` 之前，务必先检查 `if (result.error)`
`get()` 中使用了错误的format值	只能使用'string'、'file'或'stream'
忘记设置 `multipart: true`	对于大于100MB的文件，必须启用该选项
忽略分页处理	使用 `hasMore` 和 `paginationToken` 进行分页查询

Client-Side Uploads

客户端上传

For browser uploads, use the client package to upload directly to Tigris:

typescript

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

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

For initial setup, see installing-tigris-storage.

在浏览器中上传文件时，使用客户端包直接上传到Tigris：

typescript

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

const result = await upload(file.name, file, {
  url: "/api/upload", // 你的后端接口地址
  onUploadProgress: ({ percentage }) => {
    console.log(`${percentage}%`);
  },
});

关于初始设置，请查看installing-tigris-storage文档。