Upload

`put(file, options)`

put() carica un file e restituisce il nuovo oggetto.

const { id, url } = await blob.put("./photo.png", {
    name: "photo",
    prefix: "avatars",
});

Input

Input	Ambiente	Note
`string` (percorso di file)	Solo Node.js	Aperto con `fs.openAsBlob` e trasmesso in streaming dal disco, mai caricato interamente in memoria. L’estensione deriva dal basename del percorso.
`Blob` / `File`	Node.js e browser	Un `File` fornisce il suo `name` (e la sua estensione).
`Uint8Array` (incluso `Buffer`)	Node.js e browser	Passa `filename` per impostare l’estensione.
`ArrayBuffer`	Node.js e browser	Passa `filename` per impostare l’estensione.

L’estensione dell’oggetto deriva da filename, poi dal basename del percorso o dal nome del File. I byte e un semplice Blob non hanno nome, quindi passa filename (ad esempio "data.json") quando li carichi.

In Node.js, un percorso che non può essere aperto lancia un semplice Error (Cannot open file: <path>, con l’errore originale in cause). In un browser, passare un percorso fallisce prima, con l’errore dell’importazione di node:fs. Usa invece un File proveniente da un <input type="file">.

Opzioni

Opzione	Tipo	Descrizione
`name`	`string`	Nome dell’oggetto senza estensione, conforme a `^[A-Za-z0-9_][A-Za-z0-9_.-]{0,127}$`, senza `..`, che non termini con `-ex<digits>`. Obbligatorio, a meno che un token di upload non lo fissi.
`prefix`	`string`	Percorso simile a una cartella: fino a 8 segmenti conformi a `^[A-Za-z0-9_][A-Za-z0-9_.-]{0,63}$`, 256 caratteri.
`private`	`boolean`	Predefinito `false`. Gli oggetti privati ricevono sempre un hash di sicurezza e hanno `url: null`.
`security_hash`	`boolean`	Aggiunge `_<hash>` al nome.
`expire`	`string`	`"30"` (giorni), `"30d"` o `"168h"`; da 7 a 1825 giorni (Enterprise fino a 1 ora). La scadenza diventa parte dell’id.
`overwrite`	`boolean`	`false` fallisce con `OBJECT_ALREADY_EXISTS` quando il nome è già in uso. Solo upload semplici.
`disposition`	`"inline"` \| `"attachment"`	`Content-Disposition` dell’oggetto.
`auto_download`	`boolean`	Forza un download (`application/octet-stream`).
`cache_control`	`string`	`immutable`, `max-age=60..31536000` o `no-cache` (Enterprise).
`metadata`	`Record<string, string>`	Pro ed Enterprise. Chiavi `^[a-z0-9-]{1,64}$` (mai `sq-*`), fino a 5 chiavi e 512 byte.
`checksum_sha256`	`string`	64 caratteri esadecimali minuscoli. Una mancata corrispondenza fallisce con `CHECKSUM_MISMATCH` e non viene memorizzato nulla. Solo upload semplici.
`filename`	`string`	Nome di file la cui estensione diventa l’estensione dell’oggetto. Per impostazione predefinita è il nome del `File` o il basename del percorso.
`mime_type`	`string`	Usato solo per scegliere l’estensione quando `filename` non ne ha una. Il server ricava il `Content-Type`.

Vedi Object Post per tutte le regole lato server.

Risultato

Campo	Tipo	Descrizione
`id`	`string`	Id opaco dell’oggetto. Memorizzalo così com’è.
`private`	`boolean`	Se l’oggetto è privato.
`url`	`string \| null`	URL pubblico, o `null` per un oggetto privato (usa `downloadUrl()`).
`expires_at`	`string`	Quando scade l’oggetto, se ha una scadenza.
`size`	`number`	Dimensione in byte.
`name`, `prefix`, `sha256`, `replaced`		Solo upload semplici.
`parts`	`number`	Solo upload multipart: numero di parti inviate.

Upload semplici e multipart

put() sceglie il flusso di upload in base alla dimensione del file:

Dimensione del file	Flusso	Endpoint
Fino a 90 MiB (94.371.840 byte) inclusi	Upload semplice, una richiesta	Object Post
Oltre 90 MiB, fino a 10 GiB	Upload multipart (a blocchi)	Chunked Init

Ogni file deve avere almeno 512 byte; i file più piccoli falliscono con FILE_TOO_SMALL. Un max_size di una regola o di un token di upload, o la tua quota di storage, possono abbassare il limite di 10 GiB.

Come funziona un upload multipart

L’SDK avvia l’upload e il server risponde con i limiti delle parti (max_size, max_parts).
Il file viene diviso in parti di min(max_size, max(16 MiB, ceil(size / max_parts))) byte. Una parte è di solito di 16 MiB o più, ma è più piccola quando il max_size del server è più piccolo.
Le parti vengono inviate 6 alla volta, il limite del server per le parti in transito. Una parte fallita viene ritentata entro maxRetries.
Quando tutte le parti sono arrivate, l’SDK completa l’upload.

Se una parte fallisce definitivamente, o il completamento fallisce, l’SDK attende le parti ancora in transito e poi annulla l’upload, così nessuna parte arriva dopo l’annullamento. Viene lanciato l’errore originale. Non c’è ripresa: chiama di nuovo put().

Un upload multipart non verifica overwrite: false né checksum_sha256. Sostituisce sempre un oggetto esistente con lo stesso nome.

Un account può avere al massimo 32 upload multipart aperti (condivisi con il gateway S3); uno in più fallisce con TOO_MANY_OPEN_UPLOADS. Poiché le parti vengono inviate 6 alla volta per account, esegui un solo upload di grandi dimensioni alla volta.

Upload dal browser

Non inviare mai la chiave API a un browser. Invece, il tuo server genera un token di upload a breve durata e il browser carica con quello.

Server
Browser

import { SquareCloudBlob } from "@squarecloud/blob";

const blob = new SquareCloudBlob(process.env.SQUARECLOUD_API_KEY);

// e.g. inside your API route
const { token } = await blob.uploadTokens.create({
    prefix: "avatars/",
    security_hash: true,
    max_size: 5 * 1024 * 1024,
    allowed_extensions: ["png", "jpg"],
});
// send only `token` to the browser

import { SquareCloudBlob } from "@squarecloud/blob";

const upload = new SquareCloudBlob(token);
const { url } = await upload.put(input.files[0], { name: "avatar" });

Un client creato con un token può solo chiamare put(), inclusi gli upload multipart. Qualsiasi altro metodo fallisce con 403 UPLOAD_TOKEN_NOT_ALLOWED.

`uploadTokens.create(options)`

Il token vincola ogni opzione con cui è stato generato.

Opzione	Tipo	Descrizione
`name`	`string`	Fissa il nome dell’oggetto. Senza di esso, l’hash di sicurezza viene sempre applicato.
`prefix`	`string`	Fissa il prefisso.
`private`	`boolean`	Fissa la visibilità.
`security_hash`	`boolean`	Aggiunge `_<hash>` al nome.
`expire`	`string`	Scadenza dell’oggetto, come in `put()`.
`max_size`	`number`	Dimensione massima del file in byte.
`allowed_extensions`	`string[]`	Da 1 a 20 estensioni.
`metadata`	`Record<string, string>`	Metadati applicati all’oggetto caricato.
`expires_in`	`number`	Durata del token in secondi, da 60 a 3600 (predefinito 900).
`max_uses`	`number`	Upload consentiti, da 1 a 100 (predefinito 1). Dopodiché il token fallisce con `UPLOAD_TOKEN_USED`.

Restituisce { token, expires_at, max_uses }. Vedi Upload Tokens per le regole lato server.

uploadTokens.create() è una scrittura e ha un solo tentativo: non viene mai ripetuto.

Servizi

Runtimes

Piattaforma

Risoluzione dei problemi

CLI

SDKs

Changelog

`put(file, options)`

Input

Opzioni

Risultato

Upload semplici e multipart

Come funziona un upload multipart

Upload dal browser

`uploadTokens.create(options)`

​put(file, options)

​Input

​Opzioni

​Risultato

​Upload semplici e multipart

​Come funziona un upload multipart

​Upload dal browser

​uploadTokens.create(options)

`put(file, options)`

Input

Opzioni

Risultato

Upload semplici e multipart

Come funziona un upload multipart

Upload dal browser

`uploadTokens.create(options)`