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

# Oggetti

> Elenca, ispeziona, collega, aggiorna, elimina, copia e sposta gli oggetti di Blob Storage con @squarecloud/blob.

<Note>
  Gli id degli oggetti sono opachi (`pub/...`, `prv/...`). Memorizzali come vengono restituiti, non costruirli né analizzarli mai, e sostituisci l'id memorizzato ogni volta che [`update()`](#aggiornare-gli-oggetti) ne restituisce uno nuovo. Vedi [Id degli oggetti](/it/sdks/blob/client#id-degli-oggetti).
</Note>

## Elencare

`list()` è un **async generator** che segue il cursore attraverso tutte le pagine. L'ordine non è garantito.

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

`listPage()` recupera **una pagina**. Usalo per la paginazione manuale o per ottenere `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 });
}
```

| Opzione     | Tipo      | Descrizione                                                        |
| ----------- | --------- | ------------------------------------------------------------------ |
| `prefix`    | `string`  | Solo gli oggetti sotto questo prefisso.                            |
| `delimiter` | `"/"`     | Raggruppa per cartella: la pagina restituisce anche `folders`.     |
| `private`   | `boolean` | Solo oggetti privati (`true`) o pubblici (`false`).                |
| `limit`     | `number`  | Oggetti per pagina, da 1 a 1000 (predefinito 1000).                |
| `cursor`    | `string`  | Solo `listPage()`: il `continuationToken` della pagina precedente. |

Una pagina ha `objects`, `folders` (solo con `delimiter`) e `continuationToken` (**assente nell'ultima pagina**). Ogni oggetto elencato ha `id`, `size`, `created_at`, `expires_at`, `private`, `url` ed `etag`. Vedi [Object List](/it/blob-reference/endpoint/list).

## Dettagli dell'oggetto

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

Restituisce `id`, `size`, `content_type`, `etag`, `created_at`, `expires_at`, `private`, `url`, `cache_control`, `content_disposition`, `original_name`, `metadata` e `legacy`. Vedi [Object Info](/it/blob-reference/endpoint/info).

<Note>
  `created_at` è l'ora dell'ultima modifica nello storage: un aggiornamento che copia l'oggetto (visibilità, scadenza, header) la reimposta.
</Note>

## Link di download

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

* Un oggetto **pubblico** riceve il suo **URL CDN permanente**, con `expires_at: null`.
* Un oggetto **privato**, o qualsiasi chiamata con `disposition` o `filename`, riceve un **link temporaneo** che dura `expires` secondi (fino a 24 ore).

<Warning>
  Un link temporaneo **non può essere revocato**. Per link revocabili, protetti da password o con un limite di download, usa una [condivisione](/it/sdks/blob/sharing).
</Warning>

| Opzione       | Tipo                         | Descrizione                                                   |
| ------------- | ---------------------------- | ------------------------------------------------------------- |
| `expires`     | `number`                     | Durata del link in secondi, da 60 a 86400 (predefinito 3600). |
| `disposition` | `"inline"` \| `"attachment"` | Sovrascrive `Content-Disposition` per questo link.            |
| `filename`    | `string`                     | Nome con cui il browser salva il file scaricato.              |

Il risultato ha `url`, `expires_at`, `private`, `size` e `content_type`. Vedi [Object Download](/it/blob-reference/endpoint/download).

## Aggiornare gli oggetti

`update()` modifica visibilità, scadenza, cache, disposition o metadati di **un oggetto o fino a 50**. **Restituisce sempre un array**, un risultato per oggetto, e ogni risultato riporta il proprio esito in `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);
}
```

| Modifica        | Tipo                                     | Descrizione                                                  |
| --------------- | ---------------------------------------- | ------------------------------------------------------------ |
| `private`       | `boolean`                                | Rende l'oggetto privato o pubblico. **Cambia l'id.**         |
| `expire`        | `string \| null`                         | Nuova scadenza; `null` la rimuove. **Cambia l'id.**          |
| `cache_control` | `string \| null`                         | `null` lo rimuove.                                           |
| `disposition`   | `"inline"` \| `"attachment"` \| `null`   | `null` la rimuove.                                           |
| `metadata`      | `Record<string, string \| null> \| null` | `{ key: null }` rimuove una chiave; `null` le rimuove tutte. |

Un risultato riuscito (`ok: true`) ha `object` (l'id che hai inviato), `changed`, `id` (**l'id dopo la modifica**), `private`, `url`, `expires_at` e `size`. Un risultato fallito (`ok: false`) ha `object` e `code`. Un batch non lancia errori per i fallimenti dei singoli oggetti. Vedi [Object Update](/it/blob-reference/endpoint/update).

## Eliminare

L'eliminazione è **immediata e permanente**: non c'è un cestino.

```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]);
```

| Chiamata        | Restituisce                      | Su un oggetto mancante                                    |
| --------------- | -------------------------------- | --------------------------------------------------------- |
| `delete(id)`    | `void`                           | Lancia `SquareCloudBlobError` (`OBJECT_NOT_FOUND`).       |
| `delete([ids])` | `{ deleted, not_found, failed }` | Riportato in `not_found`. `failed` elenca `{ id, code }`. |

Con **un singolo id in un array**, l'SDK restituisce comunque `{ deleted, not_found, failed }`: un oggetto mancante finisce in `not_found`, e `DELETE_FAILED` o `PREFIX_NOT_ALLOWED` finiscono in `failed` invece di lanciare un errore. Qualsiasi altro errore (autenticazione, rate limit, rete) viene comunque lanciato. Vedi [Delete Objects](/it/blob-reference/endpoint/delete).

## Copiare, spostare e rinominare

Entrambe le operazioni vengono eseguite sul server, senza scaricare il file.

```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()` con `move: true`.

| Campo di destinazione | Tipo             | Descrizione                                                                                    |
| --------------------- | ---------------- | ---------------------------------------------------------------------------------------------- |
| `name`                | `string`         | Obbligatorio. Nome **senza estensione**: la destinazione mantiene l'estensione della sorgente. |
| `prefix`              | `string`         | Prefisso di destinazione.                                                                      |
| `private`             | `boolean`        | Visibilità della destinazione.                                                                 |
| `security_hash`       | `boolean`        | Aggiunge `_<hash>` al nome.                                                                    |
| `expire`              | `string \| null` | Se omesso mantiene la scadenza della sorgente; `null` la rimuove.                              |

| Opzione     | Accettata da       | Descrizione                                                                      |
| ----------- | ------------------ | -------------------------------------------------------------------------------- |
| `overwrite` | `copy()`, `move()` | `true` sostituisce un oggetto esistente nella destinazione.                      |
| `move`      | `copy()`           | `true` rimuove la sorgente una volta riuscita la copia (come chiamare `move()`). |

Il risultato ha `id`, `private`, `url`, `expires_at`, `size`, `source`, `moved` e `replaced`. Vedi [Object Copy](/it/blob-reference/endpoint/copy).

<Note>
  `update()`, `delete()`, `copy()` e `move()` sono scritture: hanno un **solo tentativo** e non vengono mai ripetute. Vedi [Politica di retry](/it/sdks/blob/errors#politica-di-retry).
</Note>