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

# SDK Blob: cliente do gateway S3

> Obtenha credenciais S3 com s3Credentials() e um S3Client pronto para uso com s3() para acessar o Blob Storage pelo gateway compatível com S3.

O Blob Storage tem um [gateway compatível com S3](/pt-br/blob-reference/s3-compatibility) 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](/pt-br/sdks/blob/client#criando-o-cliente).

<Note>
  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`.
</Note>

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

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

### 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](/pt-br/blob-reference/s3-compatibility#buckets) e [Chaves](/pt-br/blob-reference/s3-compatibility#chaves) para saber como as chaves S3 correspondem aos objetos, e [Operações suportadas](/pt-br/blob-reference/s3-compatibility#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:

```typescript theme={"system"}
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.

<Warning>
  `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.
</Warning>

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

<Tip>
  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.
</Tip>

Referência da API: [Credenciais S3](/pt-br/blob-reference/endpoint/s3-credentials).

## Próximos passos

<CardGroup cols={2}>
  <Card title="Erros" icon="triangle-exclamation" href="/pt-br/sdks/blob/errors">
    Códigos de erro e a política de novas tentativas.
  </Card>

  <Card title="Compatibilidade com S3" icon="code" href="/pt-br/blob-reference/s3-compatibility">
    O que o gateway S3 suporta.
  </Card>
</CardGroup>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.