Archiviazione e file

Panoramica

Il modulo client.storage fornisce metodi per la gestione dei file — caricamento, download, elenco ed eliminazione. Funziona sia con disco locale sia con backend di archiviazione compatibili con S3, a seconda della configurazione del server.

Tutti i metodi di archiviazione utilizzano il trasporto condiviso, quindi i token di autenticazione vengono iniettati automaticamente.

Caricare un file

Usa putObject() per caricare un file. Accetta un oggetto File o Blob insieme a una chiave di archiviazione e metadati opzionali:

const result = await client.storage.putObject({
    file: fileObject,                   // File or Blob
    key: "products/images/camera.jpg",  // Storage path (optional)
    bucket: "uploads",                  // Bucket name (optional)
    public: false,                      // Store public (permanent token-less URL) — optional, default false
    metadata: {                         // Custom metadata (optional)
        description: "Product photo",
        uploadedBy: "user-123"
    }
});

// result: { key: string, url: string, ... }

Da un campo file

const input = document.querySelector<HTMLInputElement>("#file-input");
const file = input?.files?.[0];

if (file) {
    const result = await client.storage.putObject({
        file,
        key: `avatars/${userId}/${file.name}`
    });
    console.log("Uploaded to:", result.key);
}

Ottenere un URL firmato

Recupera un URL di download e i metadati di un file archiviato:

const { url, metadata, fileNotFound } = await client.storage.getSignedUrl(
    "products/images/camera.jpg"
);

if (url) {
    console.log("Download URL:", url);
    console.log("Content type:", metadata?.contentType);
} else {
    console.log("File not found");
}

Con un bucket specifico:

const { url } = await client.storage.getSignedUrl(
    "camera.jpg",
    "product-images"   // bucket
);

L’SDK memorizza nella cache gli URL firmati per evitare chiamate ridondanti al server.

URL privati vs. pubblici

• I file privati ottengono un URL con un token di download a breve durata, limitato al percorso (?token=…, 5 min per impostazione predefinita) — mai il tuo token di accesso. Poiché scade, non conservare un URL privato; memorizza il percorso del file e richiama getSignedUrl() al momento del rendering.
• I file pubblici (archiviati sotto il prefisso public/ — imposta storage: { public: true } sulla proprietà, o passa public: true a putObject) ottengono un URL stabile, senza token, permanente e memorizzabile nella CDN, senza andata e ritorno al server. Sono sicuri da memorizzare in un database e da collegare direttamente.

Scaricare un file

Recupera un file come oggetto File:

const file = await client.storage.getObject("products/images/camera.jpg");

if (file) {
    console.log("File name:", file.name);
    console.log("File type:", file.type);
    console.log("File size:", file.size);

    // Create a download link
    const url = URL.createObjectURL(file);
    window.open(url);
} else {
    console.log("File not found");
}

Con un bucket specifico:

const file = await client.storage.getObject("camera.jpg", "product-images");

Eliminare un file

await client.storage.deleteObject("products/images/camera.jpg");

// With bucket
await client.storage.deleteObject("camera.jpg", "product-images");

L’eliminazione di un file inesistente non genera un errore.

Elencare i file

Elenca i file per prefisso, con paginazione opzionale:

const result = await client.storage.listObjects("products/images/", {
    bucket: "uploads",
    maxResults: 50,
    pageToken: undefined   // for pagination
});

for (const item of result.items) {
    console.log(item.fullPath, item.name);
}

// Paginate
if (result.nextPageToken) {
    const nextPage = await client.storage.listObjects("products/images/", {
        pageToken: result.nextPageToken
    });
}

Formati delle chiavi di archiviazione

L’SDK gestisce in modo trasparente i prefissi delle chiavi di archiviazione. Puoi passare le chiavi con o senza il prefisso di protocollo:

// All equivalent — the SDK strips the prefix internally
await client.storage.getSignedUrl("local://products/image.jpg");
await client.storage.getSignedUrl("s3://products/image.jpg");
await client.storage.getSignedUrl("products/image.jpg");

Riferimento dell’API

Metodo	Descrizione	Restituisce
putObject({ file, key?, bucket?, metadata? })	Caricare un file	UploadFileResult
getSignedUrl(key, bucket?)	Ottenere l’URL di download + metadati	DownloadConfig
getObject(key, bucket?)	Scaricare come oggetto File	File | null
deleteObject(key, bucket?)	Eliminare un file	void
listObjects(prefix, options?)	Elencare i file per prefisso	StorageListResult

Prossimi passi

• Configurazione dell’archiviazione — Configurare S3 o l’archiviazione locale sul server
• Interrogare i dati — Operazioni CRUD e query builder
• Autenticazione — Accesso e gestione delle sessioni