S3 - Square Cloud

Blob Storage 提供一个兼容 S3 的网关，可与任何 S3 客户端配合使用。SDK 可以为你提供其凭据，或者提供一个来自 AWS SDK 的现成 S3Client。

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

`s3()`

s3() 返回一个来自 @aws-sdk/client-s3 的 S3Client，它已配置好网关的 endpoint、区域和凭据，并设置了 forcePathStyle: true。 @aws-sdk/client-s3 是一个可选的对等依赖：仅在使用 s3() 时安装。它会被延迟加载，因此 SDK 本身保持无依赖。

npm
yarn
pnpm
bun

npm install @aws-sdk/client-s3

yarn add @aws-sdk/client-s3

pnpm add @aws-sdk/client-s3

bun add @aws-sdk/client-s3

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 和 Key；网关接受哪些操作，请参见支持的操作。

`s3Credentials()`

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

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`。

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

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

缓存

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

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

API 参考：S3 Credentials。

服务

Runtimes

平台

故障排除

CLI

SDKs

Changelog

S3

`s3()`

Bucket

`s3Credentials()`

缓存

​s3()

​Bucket

​s3Credentials()

​缓存

`s3()`

Bucket

`s3Credentials()`

缓存