Skip to main content
Questa pagina documenta @squarecloud/blob v4. Stai effettuando l’upgrade dalla v3? Leggi la guida alla migrazione v3 → v4.
@squarecloud/blob è l’SDK JavaScript ufficiale per Square Cloud Blob Storage. Copre ogni endpoint dell’API Blob più il gateway S3.

​
Requisiti

  • Node.js 20 o più recente, oppure qualsiasi browser moderno. L’SDK usa solo fetch, FormData e Blob.
  • Distribuito come ESM e CommonJS, con zero dipendenze a runtime.
  • @aws-sdk/client-s3 è una peer dependency opzionale, necessaria solo se chiami s3().

​
Installazione

​
Creare il client

Gli esempi leggono la chiave dalla variabile d’ambiente SQUARECLOUD_API_KEY. Impostala nel terminale in cui li esegui:
Verifica il client con una prima chiamata. stats() legge il tuo utilizzo:
Stampa il numero di oggetti e i byte che occupano, per esempio:

​
Costruttore

​
Credenziali

La credenziale viene inviata così com’è nell’header Authorization, senza prefisso Bearer.
Non inviare mai una chiave API a un browser. Genera un token di upload sul tuo server e passa al client solo il token.

​
Cosa non puoi configurare

maxRetries è l’unica opzione. Il client non accetta:
  • Un URL base. È fisso su https://blob.squarecloud.app/v1/.
  • Un fetch personalizzato. Le richieste usano il fetch globale.
  • Un timeout o un AbortSignal. Una chiamata dura quanto fetch attende, e non c’è modo di annullarla.
  • Header personalizzati.

​
Metodi

Ogni metodo restituisce dati semplici (niente classi), tranne s3(), che restituisce un S3Client. Opzioni e risultati usano i nomi dei campi dell’API, per lo più in snake_case (security_hash, expires_at), quindi il riferimento dell’API Blob si applica così com’è. Il pacchetto esporta anche SquareCloudBlobError, il tipo BlobErrorCode e ogni tipo di opzione e di risultato (PutOptions, PutResult, ListedObject, ObjectInfo, Share, Rule, …). Vedi Errori.

​
Id degli oggetti

Ogni oggetto è identificato da un id opaco, come pub/... per un oggetto pubblico o prv/... per uno privato.
  • Memorizza l’id esattamente come viene restituito. Non costruirne mai uno a mano e non analizzarlo mai.
  • Modificare private o expire cambia l’id. Sostituisci sempre l’id memorizzato con quello restituito da update().
  • Usa l’url della risposta invece di costruire gli URL. Gli oggetti privati hanno url: null: ottieni un link con downloadUrl() o con una condivisione.

​
Prossimi passi

Upload

Carica file e genera token di upload.

Quickstart dell'API Blob

URL base e un primo upload con curl.

Piani di Blob Storage

Cosa include ogni piano.