SDK de Blob: cliente del gateway S3

Blob Storage tiene un gateway compatible con S3 que funciona con cualquier cliente S3. El SDK te da sus credenciales, o un S3Client del AWS SDK ya preparado. Los ejemplos usan el cliente blob de Crear el cliente.

Ambos métodos necesitan una clave de API. Un cliente creado con un token de subida recibe 403 UPLOAD_TOKEN_NOT_ALLOWED, y una clave en un formato antiguo recibe LEGACY_API_KEY.

`s3()`

s3() devuelve un S3Client de @aws-sdk/client-s3, ya configurado con el endpoint, la región y las credenciales del gateway, y con forcePathStyle: true. @aws-sdk/client-s3 es una peer dependency opcional: instálala solo si usas s3(). Se carga de forma diferida, así que el propio SDK sigue sin dependencias.

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

Buckets

Bucket	Contenido	Acceso
`public`	Objetos públicos	Lectura y escritura
`private`	Objetos privados	Lectura y escritura
`legacy`	Objetos subidos antes del almacenamiento actual	Solo lectura, listado y eliminación

Consulta Buckets y Keys para ver cómo se corresponden las keys de S3 con los objetos, y Operaciones compatibles para ver qué acepta el gateway.

`s3Credentials()`

Para otros clientes S3 (aws-cli, rclone, boto3, …), s3Credentials() devuelve el par de claves sin procesar:

const credentials = await blob.s3Credentials();

Campo	Tipo	Descripción
`access_key_id`	`string`	Id de la clave de acceso.
`secret_access_key`	`string`	Clave de acceso secreta.
`endpoint`	`string`	Endpoint del gateway.
`region`	`string`	Región (`auto`).
`buckets`	`string[]`	`public`, `private` y `legacy`.
`access`	`{ read, write }`	Lo que puede hacer el par, según los scopes de la clave de API (tipado como `boolean \| string[]`).
`expires_at`	`string \| null`	Cuándo caduca la clave de API, y por tanto el par; `null` cuando no caduca.

Usa direccionamiento de tipo path (path-style) con cualquier otro cliente.

secret_access_key da el mismo acceso que la clave de API. Mantenlo en el servidor y guárdalo igual que la propia clave. Revocar o rotar la clave de API también invalida el par.

Caché

El par es determinista para cada clave de API, así que el SDK lo guarda en caché por instancia de cliente: s3Credentials() y s3() llaman a la API una sola vez, y las llamadas posteriores reutilizan el resultado. Una llamada fallida no se guarda en caché, así que la siguiente vuelve a intentarlo.

La ruta de credenciales solo acepta 10 peticiones por hora. Crea un único cliente SquareCloudBlob y reutilízalo en lugar de crear uno por petición.

Referencia de la API: S3 Credentials.

Próximos pasos

Errores

Códigos de error y política de reintentos.

Compatibilidad con S3

Lo que admite el gateway S3.

CLI

VS Code

SDKs

SDK de Blob: cliente del gateway S3

`s3()`

Buckets

`s3Credentials()`

Caché

Próximos pasos

Errores

Compatibilidad con S3

​s3()

​Buckets

​s3Credentials()

​Caché

​Próximos pasos

Errores

Compatibilidad con S3

`s3()`

Buckets

`s3Credentials()`

Caché

Próximos pasos