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

# S3

> 使用 s3Credentials() 获取 S3 凭据，使用 s3() 获取开箱即用的 S3Client，通过兼容 S3 的网关访问 Blob Storage。

Blob Storage 提供一个[兼容 S3 的网关](/zh/blob-reference/s3-compatibility)，可与任何 S3 客户端配合使用。SDK 可以为你提供其凭据，或者提供一个来自 AWS SDK 的现成 `S3Client`。

<Note>
  这两个方法都需要 **API 密钥**。使用上传令牌创建的客户端会收到 `403 UPLOAD_TOKEN_NOT_ALLOWED`，旧格式的密钥会收到 `LEGACY_API_KEY`。
</Note>

## `s3()`

`s3()` 返回一个来自 `@aws-sdk/client-s3` 的 `S3Client`，它已配置好网关的 endpoint、区域和凭据，并设置了 `forcePathStyle: true`。

`@aws-sdk/client-s3` 是一个**可选的对等依赖**：仅在使用 `s3()` 时安装。它会被延迟加载，因此 SDK 本身保持无依赖。

<Tabs>
  <Tab title="npm">
    ```bash theme={"system"}
    npm install @aws-sdk/client-s3
    ```
  </Tab>

  <Tab title="yarn">
    ```bash theme={"system"}
    yarn add @aws-sdk/client-s3
    ```
  </Tab>

  <Tab title="pnpm">
    ```bash theme={"system"}
    pnpm add @aws-sdk/client-s3
    ```
  </Tab>

  <Tab title="bun">
    ```bash theme={"system"}
    bun add @aws-sdk/client-s3
    ```
  </Tab>
</Tabs>

```typescript theme={"system"}
import { ListObjectsV2Command } from "@aws-sdk/client-s3";
import { SquareCloudBlob } from "@squarecloud/blob";

const blob = new SquareCloudBlob(process.env.SQUARECLOUD_API_KEY);
const s3 = await blob.s3();

const { Contents } = await s3.send(new ListObjectsV2Command({ Bucket: "public" }));
```

### Bucket

| Bucket    | 内容           | 访问权限      |
| --------- | ------------ | --------- |
| `public`  | 公开对象         | 读取和写入     |
| `private` | 私有对象         | 读取和写入     |
| `legacy`  | 在当前存储之前上传的对象 | 仅读取、列出和删除 |

S3 key 如何映射到对象，请参见 [Bucket](/zh/blob-reference/s3-compatibility#bucket) 和 [Key](/zh/blob-reference/s3-compatibility#key)；网关接受哪些操作，请参见[支持的操作](/zh/blob-reference/s3-compatibility#支持的操作)。

## `s3Credentials()`

对于其他 S3 客户端（aws-cli、rclone、boto3……），`s3Credentials()` 返回原始的密钥对：

```typescript theme={"system"}
const credentials = await blob.s3Credentials();
```

| 字段                  | 类型                | 说明                                                   |
| ------------------- | ----------------- | ---------------------------------------------------- |
| `access_key_id`     | `string`          | 访问密钥 ID。                                             |
| `secret_access_key` | `string`          | **秘密**访问密钥。                                          |
| `endpoint`          | `string`          | 网关 endpoint。                                         |
| `region`            | `string`          | 区域（`auto`）。                                          |
| `buckets`           | `string[]`        | `public`、`private` 和 `legacy`。                       |
| `access`            | `{ read, write }` | 该密钥对可执行的操作，遵循 API 密钥的作用域（类型为 `boolean \| string[]`）。 |
| `expires_at`        | `string \| null`  | API 密钥（也即该密钥对）的过期时间；不过期时为 `null`。                    |

对于其他任何客户端，请使用**路径风格寻址**。

<Warning>
  `secret_access_key` 提供与 API 密钥相同的访问权限。请将其保存在服务器端，并像保存密钥本身一样存储它。撤销或轮换 API 密钥也会使该密钥对失效。
</Warning>

### 缓存

该密钥对对于每个 API 密钥都是确定的，因此 SDK 会**按客户端实例缓存它**：`s3Credentials()` 和 `s3()` 只调用一次 API，之后的调用会复用该结果。失败的调用不会被缓存，因此下一次调用会重新尝试。

<Tip>
  凭据路由每小时只接受 10 个请求。请创建一个 `SquareCloudBlob` 客户端并复用它，而不是每个请求都创建一个。
</Tip>

API 参考：[S3 Credentials](/zh/blob-reference/endpoint/s3-credentials)。