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

# Objetos

> Liste, inspecione, gere links, atualize, exclua, copie e mova objetos do Blob Storage com o @squarecloud/blob.

<Note>
  Os ids de objetos são opacos (`pub/...`, `prv/...`). Armazene-os como retornados, nunca os monte nem os interprete, e substitua o id armazenado sempre que [`update()`](#atualizando-objetos) retornar um novo. Veja [Ids de objetos](/pt-br/sdks/blob/client#ids-de-objetos).
</Note>

## Listagem

`list()` é um **async generator** que segue o cursor por todas as páginas. A ordem não é garantida.

```typescript theme={"system"}
for await (const object of blob.list({ prefix: "avatars/" })) {
    console.log(object.id, object.size, object.url);
}
```

`listPage()` busca **uma página**. Use-o para paginação manual ou para obter `folders`:

```typescript theme={"system"}
const { objects, folders, continuationToken } = await blob.listPage({
    prefix: "avatars/",
    delimiter: "/",
});

// next page
if (continuationToken) {
    const next = await blob.listPage({ prefix: "avatars/", delimiter: "/", cursor: continuationToken });
}
```

| Opção       | Tipo      | Descrição                                                         |
| ----------- | --------- | ----------------------------------------------------------------- |
| `prefix`    | `string`  | Apenas objetos sob este prefixo.                                  |
| `delimiter` | `"/"`     | Agrupa por pasta: a página também retorna `folders`.              |
| `private`   | `boolean` | Apenas objetos privados (`true`) ou públicos (`false`).           |
| `limit`     | `number`  | Objetos por página, de 1 a 1000 (padrão 1000).                    |
| `cursor`    | `string`  | Apenas em `listPage()`: o `continuationToken` da página anterior. |

Uma página tem `objects`, `folders` (apenas com `delimiter`) e `continuationToken` (**ausente na última página**). Cada objeto listado tem `id`, `size`, `created_at`, `expires_at`, `private`, `url` e `etag`. Veja [Listar objetos](/pt-br/blob-reference/endpoint/list).

## Detalhes do objeto

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

Retorna `id`, `size`, `content_type`, `etag`, `created_at`, `expires_at`, `private`, `url`, `cache_control`, `content_disposition`, `original_name`, `metadata` e `legacy`. Veja [Informações do objeto](/pt-br/blob-reference/endpoint/info).

<Note>
  `created_at` é o horário da última modificação no armazenamento: uma atualização que copia o objeto (visibilidade, expiração, headers) o redefine.
</Note>

## Links de download

```typescript theme={"system"}
const { url, expires_at } = await blob.downloadUrl(id, { expires: 3600 });
```

* Um objeto **público** recebe sua **URL permanente da CDN**, com `expires_at: null`.
* Um objeto **privado**, ou qualquer chamada com `disposition` ou `filename`, recebe um **link temporário** que dura `expires` segundos (até 24 horas).

<Warning>
  Um link temporário **não pode ser revogado**. Para links revogáveis, protegidos por senha ou com limite de downloads, use um [compartilhamento](/pt-br/sdks/blob/sharing).
</Warning>

| Opção         | Tipo                         | Descrição                                                 |
| ------------- | ---------------------------- | --------------------------------------------------------- |
| `expires`     | `number`                     | Duração do link em segundos, de 60 a 86400 (padrão 3600). |
| `disposition` | `"inline"` \| `"attachment"` | Sobrescreve o `Content-Disposition` para este link.       |
| `filename`    | `string`                     | Nome com que o navegador salva o download.                |

O resultado tem `url`, `expires_at`, `private`, `size` e `content_type`. Veja [Download do objeto](/pt-br/blob-reference/endpoint/download).

## Atualizando objetos

`update()` altera a visibilidade, a expiração, o cache, a disposition ou os metadados de **um objeto ou até 50**. Ele **sempre retorna um array**, um resultado por objeto, e cada resultado informa seu próprio sucesso em `ok`.

```typescript theme={"system"}
const [result] = await blob.update(id, { private: true, expire: null });

if (result.ok) {
    id = result.id; // the id changed: store the new one
} else {
    console.error(result.code);
}
```

| Alteração       | Tipo                                     | Descrição                                              |
| --------------- | ---------------------------------------- | ------------------------------------------------------ |
| `private`       | `boolean`                                | Torna o objeto privado ou público. **Altera o id.**    |
| `expire`        | `string \| null`                         | Nova expiração; `null` a remove. **Altera o id.**      |
| `cache_control` | `string \| null`                         | `null` o remove.                                       |
| `disposition`   | `"inline"` \| `"attachment"` \| `null`   | `null` a remove.                                       |
| `metadata`      | `Record<string, string \| null> \| null` | `{ key: null }` remove uma chave; `null` remove todas. |

Um resultado bem-sucedido (`ok: true`) tem `object` (o id que você enviou), `changed`, `id` (**o id após a alteração**), `private`, `url`, `expires_at` e `size`. Um resultado com falha (`ok: false`) tem `object` e `code`. Um lote não lança erro por falhas individuais de objetos. Veja [Atualizar objeto](/pt-br/blob-reference/endpoint/update).

## Excluindo

A exclusão é **imediata e permanente**: não há lixeira.

```typescript theme={"system"}
// Single id: resolves to nothing, throws OBJECT_NOT_FOUND when missing
await blob.delete(id);

// Batch, up to 100 ids
const { deleted, not_found, failed } = await blob.delete([id1, id2]);
```

| Chamada         | Retorna                          | Com um objeto inexistente                                |
| --------------- | -------------------------------- | -------------------------------------------------------- |
| `delete(id)`    | `void`                           | Lança `SquareCloudBlobError` (`OBJECT_NOT_FOUND`).       |
| `delete([ids])` | `{ deleted, not_found, failed }` | Informado em `not_found`. `failed` lista `{ id, code }`. |

Com **um único id dentro de um array**, o SDK ainda retorna `{ deleted, not_found, failed }`: um objeto inexistente vai para `not_found`, e `DELETE_FAILED` ou `PREFIX_NOT_ALLOWED` vão para `failed` em vez de lançar erro. Qualquer outro erro (autenticação, rate limit, rede) continua sendo lançado. Veja [Excluir objetos](/pt-br/blob-reference/endpoint/delete).

## Copiando, movendo e renomeando

Ambos rodam no servidor, sem baixar o arquivo.

```typescript theme={"system"}
// Copy: counts toward your storage quota
await blob.copy(id, { name: "photo_copy", prefix: "backup" });

// Move or rename: does not count toward the quota
const moved = await blob.move(id, { name: "renamed" });
id = moved.id;
```

`move(source, destination, options)` é `copy()` com `move: true`.

| Campo de destino | Tipo             | Descrição                                                                  |
| ---------------- | ---------------- | -------------------------------------------------------------------------- |
| `name`           | `string`         | Obrigatório. Nome **sem extensão**: o destino mantém a extensão da origem. |
| `prefix`         | `string`         | Prefixo de destino.                                                        |
| `private`        | `boolean`        | Visibilidade do destino.                                                   |
| `security_hash`  | `boolean`        | Acrescenta `_<hash>` ao nome.                                              |
| `expire`         | `string \| null` | Se omitido, mantém a expiração da origem; `null` a remove.                 |

| Opção       | Aceita por         | Descrição                                                                              |
| ----------- | ------------------ | -------------------------------------------------------------------------------------- |
| `overwrite` | `copy()`, `move()` | `true` substitui um objeto existente no destino.                                       |
| `move`      | `copy()`           | `true` remove a origem assim que a cópia é bem-sucedida (o mesmo que chamar `move()`). |

O resultado tem `id`, `private`, `url`, `expires_at`, `size`, `source`, `moved` e `replaced`. Veja [Copiar objeto](/pt-br/blob-reference/endpoint/copy).

<Note>
  `update()`, `delete()`, `copy()` e `move()` são escritas: elas têm uma **única tentativa** e nunca são repetidas. Veja [Política de novas tentativas](/pt-br/sdks/blob/errors#política-de-novas-tentativas).
</Note>