Oggetti

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() ne restituisce uno nuovo. Vedi Id degli oggetti.

Elencare

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

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:

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.

Dettagli dell’oggetto

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.

created_at è l’ora dell’ultima modifica nello storage: un aggiornamento che copia l’oggetto (visibilità, scadenza, header) la reimposta.

Link di download

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

Un link temporaneo non può essere revocato. Per link revocabili, protetti da password o con un limite di download, usa una condivisione.

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.

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.

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.

Eliminare

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

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

Copiare, spostare e rinominare

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

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

update(), delete(), copy() e move() sono scritture: hanno un solo tentativo e non vengono mai ripetute. Vedi Politica di retry.

Servizi

Runtimes

Piattaforma

Risoluzione dei problemi

CLI

SDKs

Changelog

Elencare

Dettagli dell’oggetto

Link di download

Aggiornare gli oggetti

Eliminare

Copiare, spostare e rinominare

​Elencare

​Dettagli dell’oggetto

​Link di download

​Aggiornare gli oggetti

​Eliminare

​Copiare, spostare e rinominare

Elencare

Dettagli dell’oggetto

Link di download

Aggiornare gli oggetti

Eliminare

Copiare, spostare e rinominare