SDK Blob: cliente do gateway S3

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. Os exemplos usam o cliente blob de Criando o cliente.

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.

Próximos passos

Erros

Códigos de erro e a política de novas tentativas.

Compatibilidade com S3

O que o gateway S3 suporta.

CLI

VS Code

SDKs

SDK Blob: cliente do gateway S3

`s3()`

Buckets

`s3Credentials()`

Cache

Próximos passos

Erros

Compatibilidade com S3

​s3()

​Buckets

​s3Credentials()

​Cache

​Próximos passos

Erros

Compatibilidade com S3

`s3()`

Buckets

`s3Credentials()`

Cache

Próximos passos