对象 - Square Cloud

对象 ID 是不透明的（pub/...、prv/...）。请按返回的原样存储它们，切勿构建或解析它们，并且每当 update() 返回新 ID 时，替换你存储的 ID。参见对象 ID。

列出对象

list() 是一个异步生成器，会沿着游标遍历每一页。不保证顺序。

for await (const object of blob.list({ prefix: "avatars/" })) {
    console.log(object.id, object.size, object.url);
}

listPage() 获取单页数据。可用于手动分页或获取 folders：

const { objects, folders, continuationToken } = await blob.listPage({
    prefix: "avatars/",
    delimiter: "/",
});

// next page
if (continuationToken) {
    const next = await blob.listPage({ prefix: "avatars/", delimiter: "/", cursor: continuationToken });
}

选项	类型	说明
`prefix`	`string`	仅列出该前缀下的对象。
`delimiter`	`"/"`	按文件夹分组：该页还会返回 `folders`。
`private`	`boolean`	仅列出私有（`true`）或公开（`false`）对象。
`limit`	`number`	每页对象数，1 到 1000（默认 1000）。
`cursor`	`string`	仅限 `listPage()`：上一页的 `continuationToken`。

一页包含 objects、folders（仅在使用 delimiter 时）和 continuationToken（最后一页中不存在）。每个列出的对象都有 id、size、created_at、expires_at、private、url 和 etag。参见 Object List。

对象详情

const info = await blob.info(id);

返回 id、size、content_type、etag、created_at、expires_at、private、url、cache_control、content_disposition、original_name、metadata 和 legacy。参见 Object Info。

created_at 是存储的最后修改时间：复制对象的更新操作（可见性、过期时间、请求头）会重置它。

下载链接

const { url, expires_at } = await blob.downloadUrl(id, { expires: 3600 });

公开对象获得其永久 CDN URL，expires_at: null。
私有对象，或任何带有 disposition 或 filename 的调用，会获得一个有效期为 expires 秒（最长 24 小时）的临时链接。

临时链接无法撤销。如需可撤销、受密码保护或限制下载次数的链接，请使用分享。

选项	类型	说明
`expires`	`number`	链接有效期（秒），60 到 86400（默认 3600）。
`disposition`	`"inline"` \| `"attachment"`	为此链接覆盖 `Content-Disposition`。
`filename`	`string`	浏览器保存下载时使用的文件名。

结果包含 url、expires_at、private、size 和 content_type。参见 Object Download。

更新对象

update() 更改一个或最多 50 个对象的可见性、过期时间、缓存、disposition 或元数据。它始终返回一个数组，每个对象一个结果，每个结果在 ok 中报告自身是否成功。

const [result] = await blob.update(id, { private: true, expire: null });

if (result.ok) {
    id = result.id; // the id changed: store the new one
} else {
    console.error(result.code);
}

更改项	类型	说明
`private`	`boolean`	将对象设为私有或公开。会改变 ID。
`expire`	`string \| null`	新的过期时间；`null` 表示移除。会改变 ID。
`cache_control`	`string \| null`	`null` 表示移除。
`disposition`	`"inline"` \| `"attachment"` \| `null`	`null` 表示移除。
`metadata`	`Record<string, string \| null> \| null`	`{ key: null }` 移除单个键；`null` 移除全部。

成功的结果（ok: true）包含 object（你发送的 ID）、changed、id（更改后的 ID）、private、url、expires_at 和 size。失败的结果（ok: false）包含 object 和 code。批量操作不会因单个对象的失败而抛出异常。参见 Object Update。

删除

删除是立即且永久的：没有回收站。

// Single id: resolves to nothing, throws OBJECT_NOT_FOUND when missing
await blob.delete(id);

// Batch, up to 100 ids
const { deleted, not_found, failed } = await blob.delete([id1, id2]);

调用	返回值	对象不存在时
`delete(id)`	`void`	抛出 `SquareCloudBlobError`（`OBJECT_NOT_FOUND`）。
`delete([ids])`	`{ deleted, not_found, failed }`	在 `not_found` 中报告。`failed` 列出 `{ id, code }`。

对于放在数组中的单个 ID，SDK 仍然返回 { deleted, not_found, failed }：不存在的对象会进入 not_found，DELETE_FAILED 或 PREFIX_NOT_ALLOWED 会进入 failed，而不是抛出异常。其他任何错误（身份验证、速率限制、网络）仍会抛出。参见 Delete Objects。

复制、移动和重命名

两者都在服务器端执行，无需下载文件。

// Copy: counts toward your storage quota
await blob.copy(id, { name: "photo_copy", prefix: "backup" });

// Move or rename: does not count toward the quota
const moved = await blob.move(id, { name: "renamed" });
id = moved.id;

move(source, destination, options) 等同于带有 move: true 的 copy()。

目标字段	类型	说明
`name`	`string`	必填。不含扩展名的名称：目标会保留源对象的扩展名。
`prefix`	`string`	目标前缀。
`private`	`boolean`	目标可见性。
`security_hash`	`boolean`	在名称后追加 `_<hash>`。
`expire`	`string \| null`	省略时保留源对象的过期时间；`null` 表示移除。

选项	适用于	说明
`overwrite`	`copy()`, `move()`	`true` 会替换目标位置的现有对象。
`move`	`copy()`	`true` 会在复制成功后删除源对象（等同于调用 `move()`）。

结果包含 id、private、url、expires_at、size、source、moved 和 replaced。参见 Object Copy。

update()、delete()、copy() 和 move() 是写操作：它们只有一次尝试，永远不会被重试。参见重试策略。

服务

Runtimes

平台

故障排除

CLI

SDKs

Changelog

对象

列出对象

对象详情

下载链接

更新对象

删除

复制、移动和重命名

​列出对象

​对象详情

​下载链接

​更新对象

​删除

​复制、移动和重命名

列出对象

对象详情

下载链接

更新对象

删除

复制、移动和重命名