> ## 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: regras por prefixo e estatísticas de uso

> Leia e substitua regras por prefixo com o @squarecloud/blob (visibilidade, expiração, tamanho, extensões, exclusão automática) e veja o uso do Blob Storage.

Os exemplos usam o cliente `blob` de [Criando o cliente](/pt-br/sdks/blob/client#criando-o-cliente).

## Regras

As regras definem padrões e limites para todos os objetos sob um prefixo: visibilidade, expiração, tamanho máximo, extensões permitidas, cache e exclusão automática. Elas se aplicam a todo upload sob o prefixo, seja pelo SDK, por um token de upload ou pelo dashboard. Veja [Atualizar configurações](/pt-br/blob-reference/endpoint/settings-put) para os limites dos planos e a correspondência de prefixos.

### `rules.get()`

```typescript theme={"system"}
const rules = await blob.rules.get();
```

Retorna as regras salvas como um array. Cada regra tem os campos abaixo, além de `created_at`, e `active_from` quando tem `delete_after_days`.

<Note>
  `active_from` é **opcional**: a API só o envia para regras com `delete_after_days`. Em TypeScript, trate o caso de ele ser `undefined`.
</Note>

### `rules.set(rules)`

```typescript theme={"system"}
await blob.rules.set([
    { prefix: "tmp/", delete_after_days: 7 },
    { prefix: "avatars/", max_size: 5 * 1024 * 1024, extensions: ["png", "jpg"] },
]);
```

<Warning>
  `rules.set()` **substitui a lista inteira**. Envie todas as regras que você quer manter; `rules.set([])` remove todas. Para adicionar uma regra, leia a lista primeiro:

  ```typescript theme={"system"}
  const current = await blob.rules.get();
  await blob.rules.set([
      ...current.map(({ created_at, active_from, ...rule }) => rule),
      { prefix: "exports/", expire: "30d" },
  ]);
  ```
</Warning>

Retorna a lista salva, como `rules.get()`.

| Campo | Tipo | Descrição |
| - | - | - |
| `prefix` | `string` | Obrigatório. O prefixo ao qual a regra se aplica, por exemplo `"a/b/"`. |
| `private` | `boolean` | Visibilidade padrão. |
| `expire` | `string` | Expiração padrão (`"30d"`, `"168h"`, ...). |
| `max_size` | `number` | Tamanho máximo do arquivo em bytes, de 512 B a 10 GiB. |
| `extensions` | `string[]` | De 1 a 50 extensões permitidas, correspondendo a `^[a-z0-9]{1,16}(\.[a-z0-9]{1,16})?$`. |
| `cache_control` | `string` | `Cache-Control` padrão. |
| `delete_after_days` | `number` | Exclui os objetos esta quantidade de dias após serem gravados, de 7 a 3650 (Enterprise a partir de 1). |

<Warning>
  `delete_after_days` só entra em vigor **24 horas depois que a regra é salva** (veja `active_from`). Uma vez ativa, os objetos excluídos não podem ser recuperados.
</Warning>

Quando uma regra é rejeitada, o [`extra`](/pt-br/sdks/blob/errors#squarecloudbloberror) do erro traz o `prefix` problemático:

```typescript theme={"system"}
import { SquareCloudBlobError } from "@squarecloud/blob";

try {
    await blob.rules.set(rules);
} catch (error) {
    if (error instanceof SquareCloudBlobError) {
        console.error(error.code, error.extra.prefix);
    }
}
```

<Note>
  `rules.get()` é uma leitura e é [tentado novamente](/pt-br/sdks/blob/errors#política-de-novas-tentativas). `rules.set()` tem uma **única tentativa**.
</Note>

## Estatísticas

```typescript theme={"system"}
const stats = await blob.stats();

console.log(stats.usage.objects); // total objects
console.log(stats.usage.storage); // storage used, in bytes
```

| Campo | Descrição |
| - | - |
| `usage.objects` | Número de objetos. |
| `usage.storage` | Armazenamento usado, em bytes. |
| `plan.included` | Armazenamento incluído no seu plano, em bytes. |
| `billing` | `extraStorage`, `storagePrice`, `objectsPrice`, `totalEstimate`. |
| `month` | `days` e `average_storage` do mês atual. |

<Info>
  As estatísticas são uma **estimativa**, armazenada em cache pelo servidor por **60 segundos**. `billing` é apenas uma estimativa do armazenamento acima do seu plano, não uma fatura.
</Info>

Veja [Estatísticas da conta](/pt-br/blob-reference/endpoint/stats).

## Próximos passos

<CardGroup cols={2}>
  <Card title="S3" icon="bucket" href="/pt-br/sdks/blob/s3">
    Acesse o Blob Storage com qualquer cliente S3.
  </Card>

  <Card title="Referência da API de configurações" icon="code" href="/pt-br/blob-reference/endpoint/settings-put">
    Os endpoints REST por trás destes métodos.
  </Card>
</CardGroup>


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