S3 - Square Cloud

O Blob Storage tem um gateway compatível com S3 que funciona com qualquer cliente S3. O SDK fornece as credenciais dele, ou um S3Client pronto do AWS SDK.

Ambos os métodos precisam de uma chave de API. Um cliente criado com um token de upload recebe 403 UPLOAD_TOKEN_NOT_ALLOWED, e uma chave em formato antigo recebe LEGACY_API_KEY.

`s3()`

s3() retorna um S3Client do @aws-sdk/client-s3, já configurado com o endpoint, a região e as credenciais do gateway, e com forcePathStyle: true. @aws-sdk/client-s3 é uma peer dependency opcional: instale-a apenas se você usar s3(). Ela é carregada sob demanda, então o SDK em si continua sem dependências.

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	Conteúdo	Acesso
`public`	Objetos públicos	Leitura e escrita
`private`	Objetos privados	Leitura e escrita
`legacy`	Objetos enviados antes do armazenamento atual	Apenas leitura, listagem e exclusão

Veja Buckets e Chaves para saber como as chaves S3 correspondem aos objetos, e Operações suportadas para o que o gateway aceita.

`s3Credentials()`

Para outros clientes S3 (aws-cli, rclone, boto3, …), s3Credentials() retorna o par de chaves bruto:

const credentials = await blob.s3Credentials();

Campo	Tipo	Descrição
`access_key_id`	`string`	Id da chave de acesso.
`secret_access_key`	`string`	Chave de acesso secreta.
`endpoint`	`string`	Endpoint do gateway.
`region`	`string`	Região (`auto`).
`buckets`	`string[]`	`public`, `private` e `legacy`.
`access`	`{ read, write }`	O que o par pode fazer, seguindo os escopos da chave de API (tipado como `boolean \| string[]`).
`expires_at`	`string \| null`	Quando a chave de API, e portanto o par, expira; `null` quando não expira.

Use endereçamento path-style com qualquer outro cliente.

secret_access_key dá o mesmo acesso que a chave de API. Mantenha-a no servidor e armazene-a como a própria chave. Revogar ou rotacionar a chave de API também invalida o par.

Cache

O par é determinístico por chave de API, então o SDK o armazena em cache por instância do cliente: s3Credentials() e s3() chamam a API uma vez, e as chamadas seguintes reutilizam o resultado. Uma chamada que falha não é armazenada em cache, então a próxima chamada tenta novamente.

A rota de credenciais aceita apenas 10 requisições por hora. Crie um único cliente SquareCloudBlob e reutilize-o, em vez de criar um por requisição.

Referência da API: Credenciais S3.

Serviços

Runtimes

Plataforma

Solução de Problemas

CLI

SDKs

Changelog

S3

`s3()`

Buckets

`s3Credentials()`

Cache

​s3()

​Buckets

​s3Credentials()

​Cache

`s3()`

Buckets

`s3Credentials()`

Cache