Vai al contenuto principale
Gli esempi usano il client blob di Creare il client.

put(file, options)

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

Input

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 the file "<path>". Check that the path exists and that this process can read it., con l’errore originale in cause). Fuori da Node.js, qualsiasi percorso lancia un semplice Error (File paths can only be uploaded in Node.js. Pass a Blob, a File or bytes instead.). In un browser, usa invece un File proveniente da un <input type="file">.

Opzioni

Vedi Object Post per tutte le regole lato server.

Risultato

Upload semplici e multipart

put() sceglie il flusso di upload in base alla dimensione del file: 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

  1. L’SDK avvia l’upload e il server risponde con i limiti delle parti (max_size, max_parts).
  2. 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ù (il servizio accetta fino a 32 MiB), ma è più piccola quando il max_size del server è più piccolo.
  3. Le parti vengono inviate 6 alla volta, il limite del server per le parti in transito. Una parte fallita viene ritentata entro maxRetries.
  4. 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(). Dopo un 503 STORAGE_UNAVAILABLE, attendi prima circa 10 secondi (vedi Interruzioni dello storage).
Un upload multipart non verifica checksum_sha256.
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.

Controllo di sovrascrittura negli upload multipart

Un upload multipart rispetta overwrite: false. Subito dopo aver avviato l’upload, l’SDK controlla il nome con info():
  • Se l’oggetto esiste, l’SDK annulla l’upload prima di inviare qualsiasi parte e lancia 409 OBJECT_ALREADY_EXISTS.
  • Se il controllo riceve un 429, l’SDK annulla l’upload prima di inviare qualsiasi parte e lancia quel 429.
  • Qualsiasi altro fallimento del controllo, come un blob:read mancante, un 404 o un errore di rete, lascia proseguire l’upload.
Il controllo consuma una richiesta dal rate limit dell’account e richiede lo scope blob:read. Il servizio controlla di nuovo il nome al completamento dell’upload, perché nel frattempo l’oggetto potrebbe essere comparso. Su quel 409, l’SDK annulla l’upload, il che libera uno dei 32 slot di upload aperti e scarta le parti. Non c’è alcun controllo con private: true o security_hash: true, perché il nome riceve un hash casuale e non può essere già in uso. Non c’è nemmeno con un token di upload: il servizio ignora overwrite per gli upload con token, ed è il token a decidere se il suo upload può sostituire un oggetto.

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.
Un client creato con un token può solo chiamare put(), inclusi gli upload multipart. Qualsiasi altro metodo fallisce con 403 UPLOAD_TOKEN_NOT_ALLOWED. L’SDK chiama https://blob.squarecloud.app con il fetch globale, quindi una pagina con una Content Security Policy deve consentire quell’origine in connect-src.

uploadTokens.create(options)

Il token vincola ogni opzione con cui è stato generato. Restituisce { token, expires_at, max_uses }. Vedi Upload Tokens per le regole lato server. La generazione fallisce con 403 PREFIX_NOT_ALLOWED quando una chiave limitata a dei prefissi chiede un prefisso al di fuori di essi, 403 PERMISSION_DENIED quando la credenziale non può generare token, 403 UPGRADE_REQUIRED per un’opzione che il tuo piano non include, e 401 PERMISSION_DENIED quando l’account non ha un piano attivo.
uploadTokens.create() è una scrittura e ha un solo tentativo: non viene mai ripetuto.

Prossimi passi

Oggetti

Elenca, aggiorna, copia, sposta ed elimina oggetti.

Riferimento API dell'upload

Gli endpoint REST dietro put().