Guida rapida all'API di Blob Storage

Blob Storage conserva i tuoi file, serve quelli pubblici da una CDN e fornisce link a quelli privati. Questa pagina ti porta da una chiave API a un file caricato e a un link di download, con curl. Lo storage è incluso in ogni piano: consulta Blob Storage per piani, prezzi e FAQ.

URL base

Ogni endpoint di questa reference è relativo a:

https://blob.squarecloud.app/v1

Autenticazione

Blob Storage accetta le stesse chiavi API dell’API di Square Cloud, nell’header Authorization. La chiave ha bisogno dello scope blob:write per caricare e di blob:read per elencare e scaricare, e non può essere limitata ad applicazioni specifiche. Creane una nelle impostazioni di sicurezza del tuo account e conservala in una variabile d’ambiente:

export SQUARECLOUD_API_KEY="your-api-key"

Scope e upload token sono spiegati in Autenticazione.

Carica un file

Object Post accetta il file come multipart/form-data e il suo nome, senza estensione, nella query:

curl --request POST \
  --url 'https://blob.squarecloud.app/v1/objects?name=logo&prefix=images' \
  --header "Authorization: $SQUARECLOUD_API_KEY" \
  --form 'file=@./logo.png'

{
  "status": "success",
  "response": {
    "id": "pub/3155597145698959364/images/logo.png",
    "private": false,
    "url": "https://blob.squarecloud.dev/pub/3155597145698959364/images/logo.png",
    "size": 416230,
    "name": "logo",
    "prefix": "images",
    "sha256": "5f70bf18a086007016e948b04aed3b82103a36bea41755b6cddfaf10ace3c6ef",
    "replaced": false
  }
}

Il file è pubblico per impostazione predefinita: url funziona subito in un browser o in un tag <img>. Salva l’id così come arriva, perché tutte le altre route lo richiedono. Una singola richiesta accetta file da 512 byte a 100 MB. I file più grandi, fino a 10 GiB, passano per l’upload chunked o per il gateway S3.

Carica un file privato

Aggiungi private=true e il file non avrà un URL pubblico (url è null):

curl --request POST \
  --url 'https://blob.squarecloud.app/v1/objects?name=invoice&prefix=invoices&private=true' \
  --header "Authorization: $SQUARECLOUD_API_KEY" \
  --form 'file=@./invoice.pdf'

Scarica un file

Un file pubblico si scarica dal suo url. Per uno privato, Object Download firma un link temporaneo che funziona senza credenziali e reindirizza lì, quindi curl -L salva il file:

curl -L --output invoice.pdf \
  --url 'https://blob.squarecloud.app/v1/objects/download?object=<id>' \
  --header "Authorization: $SQUARECLOUD_API_KEY"

Sostituisci <id> con l’id dell’upload. Aggiungi redirect=false per ricevere il link in JSON e passarlo a qualcun altro. Per link che puoi revocare o proteggere con una password, crea un link di condivisione.

Elenca ed elimina file

Object List restituisce i tuoi file pagina per pagina:

curl --url 'https://blob.squarecloud.app/v1/objects?prefix=images/' \
  --header "Authorization: $SQUARECLOUD_API_KEY"

Objects Delete rimuove un file, o fino a 100 in una sola richiesta:

curl --request DELETE \
  --url 'https://blob.squarecloud.app/v1/objects' \
  --header "Authorization: $SQUARECLOUD_API_KEY" \
  --header 'Content-Type: application/json' \
  --data '{ "object": "<id>" }'

Quando qualcosa va storto

Gli errori arrivano come { "status": "error", "code": "..." }. Quelli che incontrerai più probabilmente all’inizio:

Codice	HTTP	Soluzione
`ACCESS_DENIED`	401	La chiave è mancante o non viene riconosciuta. Controlla l’header `Authorization`.
`PERMISSION_DENIED`	401	L’account non ha un piano attivo, quindi non può caricare file.
`MISSING_SCOPE`	403	La chiave non ha `blob:write` o `blob:read`. Crea una chiave con quello scope.
`RESOURCE_NOT_ALLOWED`	403	La chiave è limitata ad alcune applicazioni. Usa una chiave senza questa restrizione.
`FILE_TOO_LARGE`	413	Il file supera i 100 MB. Usa l’upload chunked.

Tutti i codici sono in Errori.

Prossimi passi

SDK Blob

Carica e gestisci file da JavaScript, con gli upload chunked gestiti per te.

Compatibilità S3

Usa aws-cli, boto3, rclone o qualsiasi SDK AWS.

Link e condivisione

Link temporanei, link di condivisione e quando usare ciascuno.

Upload dal browser

Permetti ai visitatori di caricare file senza esporre la tua chiave API.

Primi passi

Oggetti

Upload a blocchi

Account

Link di condivisione

S3

Guida rapida all'API di Blob Storage

URL base

Autenticazione

Carica un file

Carica un file privato

Scarica un file

Elenca ed elimina file

Quando qualcosa va storto

Prossimi passi

SDK Blob

Compatibilità S3

Link e condivisione

Upload dal browser

​URL base

​Autenticazione

​Carica un file

​Carica un file privato

​Scarica un file

​Elenca ed elimina file

​Quando qualcosa va storto

​Prossimi passi

SDK Blob

Compatibilità S3

Link e condivisione

Upload dal browser

URL base

Autenticazione

Carica un file

Carica un file privato

Scarica un file

Elenca ed elimina file

Quando qualcosa va storto

Prossimi passi