Blob Object Post

curl --request POST \
  --url 'https://blob.squarecloud.app/v1/objects?name=myfile&prefix=images&expire=30' \
  --header 'Authorization: YOUR_API_KEY' \
  --form 'file=@./myphone.png'

import fs from 'node:fs';

const form = new FormData();
form.append('file', new Blob([fs.readFileSync('./myphone.png')]), 'myphone.png');

const params = new URLSearchParams({
  name: 'myfile',
  prefix: 'images',
  expire: '30',
});

const response = await fetch(`https://blob.squarecloud.app/v1/objects?${params}`, {
  method: 'POST',
  headers: { Authorization: 'YOUR_API_KEY' },
  body: form,
});

import requests

with open('myphone.png', 'rb') as f:
    response = requests.post(
        'https://blob.squarecloud.app/v1/objects',
        headers={'Authorization': 'YOUR_API_KEY'},
        params={'name': 'myfile', 'prefix': 'images', 'expire': 30},
        files={'file': ('myphone.png', f, 'image/png')},
    )

{
    "status": "success",
    "response": {
        "id": "3155597145698959364/images/test_lxch4k7y-07ee.png",
        "name": "test",
        "prefix": "images",
        "size": 416230,
        "url": "https://public-blob.squarecloud.dev/3155597145698959364/images/test_lxch4k7y-07ee.png"
    }
}

string

obbligatorio

La chiave API del tuo account. Puoi trovarla nelle impostazioni del tuo account.

Object Post carica un singolo file su Square Cloud Blob Storage e restituisce un URL su CDN che puoi incorporare o condividere direttamente, senza dover provisionare un bucket o gestire tu stesso gli ACL. Serve da base per allegati, export generati e contenuti multimediali caricati dagli utenti per le applicazioni ospitate sulla piattaforma. L’estensione memorizzata deriva dal nome file che invii nella parte multipart (con fallback sul tipo MIME dichiarato e poi su bin), quindi invia sempre un nome file reale. Praticamente qualsiasi tipo di file è accettato; vengono rifiutati solo eseguibili e installer. Agli oggetti può essere assegnata una scadenza automatica compresa tra 7 e 1825 giorni (5 anni), dopo la quale non vengono più serviti. Una singola richiesta accetta file da 512 byte fino a 100 MB, il body più grande accettato dall’edge di Cloudflare. I file più grandi, fino a 1 GiB, passano per il flusso di caricamento chunked. Una volta caricato un file, sfoglialo con Object List, rimuovilo con Object Delete, oppure monitora l’utilizzo rispetto alla quota del tuo piano con Account Stats.

file

obbligatorio

Usa FormData (multipart/form-data). Esattamente un file per richiesta.
Invia un nome file reale: l’estensione memorizzata viene derivata da esso.

string

obbligatorio

Una stringa che rappresenta il nome del file. (senza estensione)
Deve rispettare il pattern a-z, A-Z, 0-9 e _. (da 3 a 32 caratteri)

string

Una stringa che rappresenta il prefisso del file.
Deve rispettare il pattern a-z, A-Z, 0-9 e _. (da 3 a 32 caratteri)

number

Un numero che indica il periodo di scadenza del file, compreso tra 7 e 1825 giorni (5 anni).

boolean

Imposta su true se è richiesto un hash di sicurezza.

boolean

Imposta su true se il file deve essere configurato per il download automatico.

Limiti di frequenza e concorrenza

Il caricamento richiede un piano a pagamento.

Ogni account può avere al massimo 4 caricamenti in corso simultaneamente. Avviare un altro caricamento mentre 4 sono ancora in esecuzione restituisce TOO_MANY_CONCURRENT_UPLOADS (429).
I piani Hobby e Standard sono inoltre limitati a 1 caricamento al secondo (RATE_LIMITED, 429). I piani Pro ed Enterprise sono esenti dal limite al secondo.

Per motivi di sicurezza, i formati che un browser renderizza inline (.html, .svg, .xml, .xhtml e simili) vengono sempre consegnati come download (serviti come application/octet-stream) invece di essere renderizzati. Impostare auto_download=true applica lo stesso comportamento di download forzato a qualsiasi tipo di file.

Tipi di file

Praticamente qualsiasi estensione è accettata, inclusi i formati senza un tipo MIME registrato (.bam, .vcf, .fasta, .fastq, .parquet, .h5, .npy e così via). Non esiste più una whitelist di tipi MIME.

L’estensione memorizzata viene derivata dal nome file inviato nella parte multipart, con fallback sul tipo MIME dichiarato e poi su bin.
I suffissi di compressione composti vengono preservati: reads.fastq.gz viene memorizzato come .fastq.gz, non come .gz.
Il Content-Type servito viene derivato lato server dall’estensione. I formati sconosciuti vengono serviti come application/octet-stream, quindi vengono scaricati invece di essere renderizzati.
Eseguibili e installer vengono rifiutati con BLOCKED_FILE_TYPE: exe, msi, dll, bat, cmd, com, scr, cpl, pif, hta, vbs, vbe, jse, wsf, wsh, msc, reg, lnk, sys, drv, ps1, apk, xpi.

Risposta

string

Indica se la chiamata è andata a buon fine. “success” se riuscita, “error” in caso contrario.

object

Mostra Toggle object

string

L’ID del file caricato.

string

Il nome del file caricato.

string

Il prefisso sotto cui il file è stato memorizzato (riportato dalla query prefix; omesso quando non ne è stato inviato alcuno).

number

La dimensione del file caricato, in byte.

string

L’URL pubblico CDN del file caricato: https://public-blob.squarecloud.dev/<user_id>/<key>, dove la chiave è [prefix/]name[_hash][-exN].ext (i suffissi hash ed expiration compaiono solo se usati; l’estensione è derivata dal nome file caricato).

curl --request POST \
  --url 'https://blob.squarecloud.app/v1/objects?name=myfile&prefix=images&expire=30' \
  --header 'Authorization: YOUR_API_KEY' \
  --form 'file=@./myphone.png'

import fs from 'node:fs';

const form = new FormData();
form.append('file', new Blob([fs.readFileSync('./myphone.png')]), 'myphone.png');

const params = new URLSearchParams({
  name: 'myfile',
  prefix: 'images',
  expire: '30',
});

const response = await fetch(`https://blob.squarecloud.app/v1/objects?${params}`, {
  method: 'POST',
  headers: { Authorization: 'YOUR_API_KEY' },
  body: form,
});

import requests

with open('myphone.png', 'rb') as f:
    response = requests.post(
        'https://blob.squarecloud.app/v1/objects',
        headers={'Authorization': 'YOUR_API_KEY'},
        params={'name': 'myfile', 'prefix': 'images', 'expire': 30},
        files={'file': ('myphone.png', f, 'image/png')},
    )

{
    "status": "success",
    "response": {
        "id": "3155597145698959364/images/test_lxch4k7y-07ee.png",
        "name": "test",
        "prefix": "images",
        "size": 416230,
        "url": "https://public-blob.squarecloud.dev/3155597145698959364/images/test_lxch4k7y-07ee.png"
    }
}

Risoluzione dei problemi

Relativi all’oggetto

// The provided object name is invalid.
// Must adhere to the a to z, A to Z, 0 to 9, and _ pattern.
{
    "status": "error",
    "code": "INVALID_OBJECT_NAME"
}

// The provided object prefix is invalid.
// Must adhere to the a to z, A to Z, 0 to 9, and _ pattern.
{
    "status": "error",
    "code": "INVALID_OBJECT_PREFIX"
}

// The provided expiration value for the object is invalid.
// Must be a number ranging from 7 to 1825. (value in days).
{
    "status": "error",
    "code": "INVALID_OBJECT_EXPIRE"
}

// The provided security hash boolean is invalid.
// Just set to true or false. 😅
{
    "status": "error",
    "code": "INVALID_OBJECT_SECURITY_HASH"
}

// The provided auto-download boolean is invalid.
// Just set to true or false. 😅
{
    "status": "error",
    "code": "INVALID_STORAGE_AUTO_DOWNLOAD"
}

Relativi al file

Una singola richiesta accetta fino a 100 MB. Per file fino a 1 GiB, usa il flusso di caricamento chunked.

// The provided file is invalid.
{
    "status": "error",
    "code": "INVALID_FILE"
}

// The file extension is malformed or too long.
{
    "status": "error",
    "code": "INVALID_FILE_TYPE"
}

// Executable/installer extensions (exe, msi, bat, apk, ...) are not accepted.
{
    "status": "error",
    "code": "BLOCKED_FILE_TYPE"
}

// The file size is too small (< 512 bytes).
{
    "status": "error",
    "code": "FILE_TOO_SMALL"
}

Non autorizzato

// The API key is missing or invalid. Set a valid key in the Authorization header.
{
    "status": "error",
    "code": "ACCESS_DENIED"
}

// The account has no active paid plan. Uploading to Blob Storage requires a paid plan.
{
    "status": "error",
    "code": "PERMISSION_DENIED"
}

Quota di archiviazione superata

// You have exceeded your storage quota. Delete some files or upgrade your plan.
{
    "status": "error",
    "code": "STORAGE_QUOTA_EXCEEDED"
}

Tipo di contenuto non valido

// This route only accepts multipart/form-data requests with exactly one file.
{
    "status": "error",
    "code": "INVALID_CONTENT_TYPE"
}

Payload troppo grande

Una singola richiesta accetta fino a 100 MB. Per file fino a 1 GiB, usa il flusso di caricamento chunked.

// A single request accepts up to 100 MB. Use /v1/objects/chunked for files up to 1 GiB.
{
    "status": "error",
    "code": "FILE_TOO_LARGE"
}

Frequenza limitata

// Per-second upload limit reached (Hobby/Standard: max 1 upload per second).
{
    "status": "error",
    "code": "RATE_LIMITED"
}

// Too many simultaneous uploads (max 4 in progress at a time per account).
{
    "status": "error",
    "code": "TOO_MANY_CONCURRENT_UPLOADS"
}

Caricamento fallito

// Failed to upload object to storage. Please try again later.
{
    "status": "error",
    "code": "UPLOAD_FAILED"
}

Objects DeleteQuesta documentazione fornisce una panoramica completa dell'endpoint DELETE /v1/objects della SquareCloud Blob API.

curl --request POST \
  --url 'https://blob.squarecloud.app/v1/objects?name=myfile&prefix=images&expire=30' \
  --header 'Authorization: YOUR_API_KEY' \
  --form 'file=@./myphone.png'

import fs from 'node:fs';

const form = new FormData();
form.append('file', new Blob([fs.readFileSync('./myphone.png')]), 'myphone.png');

const params = new URLSearchParams({
  name: 'myfile',
  prefix: 'images',
  expire: '30',
});

const response = await fetch(`https://blob.squarecloud.app/v1/objects?${params}`, {
  method: 'POST',
  headers: { Authorization: 'YOUR_API_KEY' },
  body: form,
});

import requests

with open('myphone.png', 'rb') as f:
    response = requests.post(
        'https://blob.squarecloud.app/v1/objects',
        headers={'Authorization': 'YOUR_API_KEY'},
        params={'name': 'myfile', 'prefix': 'images', 'expire': 30},
        files={'file': ('myphone.png', f, 'image/png')},
    )

{
    "status": "success",
    "response": {
        "id": "3155597145698959364/images/test_lxch4k7y-07ee.png",
        "name": "test",
        "prefix": "images",
        "size": 416230,
        "url": "https://public-blob.squarecloud.dev/3155597145698959364/images/test_lxch4k7y-07ee.png"
    }
}

Endpoint Blob

Upload a Blocchi

Limiti di frequenza e concorrenza

Tipi di file

Risposta

Risoluzione dei problemi

Relativi all’oggetto

Relativi al file

Non autorizzato

Quota di archiviazione superata

Tipo di contenuto non valido

Payload troppo grande

Frequenza limitata

Caricamento fallito

​Limiti di frequenza e concorrenza

​Tipi di file

​Risposta

​Risoluzione dei problemi

​Relativi all’oggetto

​Relativi al file

​Non autorizzato

​Quota di archiviazione superata

​Tipo di contenuto non valido

​Payload troppo grande

​Frequenza limitata

​Caricamento fallito

Limiti di frequenza e concorrenza

Tipi di file

Risposta

Risoluzione dei problemi

Relativi all’oggetto

Relativi al file

Non autorizzato

Quota di archiviazione superata

Tipo di contenuto non valido

Payload troppo grande

Frequenza limitata

Caricamento fallito