> ## Documentation Index
> Fetch the complete documentation index at: https://docs.squarecloud.app/llms.txt
> Use this file to discover all available pages before exploring further.

# 对象

> 使用 @squarecloud/blob 列出、查看、链接、更新、删除、复制和移动 Blob Storage 对象。

<Note>
  对象 ID 是不透明的（`pub/...`、`prv/...`）。请按返回的原样存储它们，切勿构建或解析它们，并且每当 [`update()`](#更新对象) 返回新 ID 时，替换你存储的 ID。参见[对象 ID](/zh/sdks/blob/client#对象-id)。
</Note>

## 列出对象

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

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

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

```typescript theme={"system"}
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](/zh/blob-reference/endpoint/list)。

## 对象详情

```typescript theme={"system"}
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](/zh/blob-reference/endpoint/info)。

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

## 下载链接

```typescript theme={"system"}
const { url, expires_at } = await blob.downloadUrl(id, { expires: 3600 });
```

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

<Warning>
  临时链接**无法撤销**。如需可撤销、受密码保护或限制下载次数的链接，请使用[分享](/zh/sdks/blob/sharing)。
</Warning>

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

结果包含 `url`、`expires_at`、`private`、`size` 和 `content_type`。参见 [Object Download](/zh/blob-reference/endpoint/download)。

## 更新对象

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

```typescript theme={"system"}
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](/zh/blob-reference/endpoint/update)。

## 删除

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

```typescript theme={"system"}
// 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](/zh/blob-reference/endpoint/delete)。

## 复制、移动和重命名

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

```typescript theme={"system"}
// 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](/zh/blob-reference/endpoint/copy)。

<Note>
  `update()`、`delete()`、`copy()` 和 `move()` 是写操作：它们只有**一次尝试**，永远不会被重试。参见[重试策略](/zh/sdks/blob/errors#重试策略)。
</Note>