Compatibilità S3

Blob Storage parla l’API S3 su https://s3-blob.squarecloud.app. Funziona qualsiasi strumento che permetta di impostare un endpoint personalizzato: aws-cli, boto3, l’SDK AWS per JavaScript, rclone, Cyberduck e la maggior parte degli strumenti di backup.

Credenziali

Gli strumenti S3 firmano le richieste con una coppia di chiavi di accesso. Ottienila da S3 Credentials:

curl https://blob.squarecloud.app/v1/s3/credentials \
  --header 'Authorization: YOUR_API_KEY'

La coppia è derivata dalla tua chiave API. Non richiede una gestione separata: revocare o rigenerare la chiave ha lo stesso effetto sulla coppia, e la coppia ottiene gli stessi scope. Una chiave con solo blob:read produce una coppia di sola lettura. La coppia non cambia finché non cambia la chiave API, quindi recuperala una volta e conservala nel tuo secret manager o in una variabile d’ambiente. Non chiamare la route a ogni avvio: accetta 10 richieste all’ora.

Impostazione	Valore
Endpoint	`https://s3-blob.squarecloud.app`
Regione	`auto`
Indirizzamento	Path-style (`https://s3-blob.squarecloud.app/<bucket>/<key>`)
Firma	AWS Signature Version 4

Bucket

Il tuo account vede tre bucket fissi. Non puoi creare né eliminare bucket.

Bucket	Contenuto	Accesso
`public`	File pubblici, distribuiti su `https://blob.squarecloud.dev/pub/<user_id>/<key>`	Lettura e scrittura
`private`	File privati, senza URL pubblico	Lettura e scrittura
`legacy`	File legacy, caricati prima dell’aggiornamento di settembre 2026	Lettura, elenco ed eliminazione

Una chiave nel bucket public o private è il percorso dell’oggetto senza il tuo user id: images/logo.png nel bucket public corrisponde all’oggetto pub/<user_id>/images/logo.png sull’API REST. I file scritti tramite S3 compaiono sull’API REST e nella dashboard, e viceversa.

Configurazione

aws configure set aws_access_key_id SQ2_...
aws configure set aws_secret_access_key ...
aws configure set region auto

aws s3 cp ./logo.png s3://public/images/logo.png \
  --endpoint-url https://s3-blob.squarecloud.app
aws s3 ls s3://public/images/ --endpoint-url https://s3-blob.squarecloud.app

import boto3
from botocore.config import Config

s3 = boto3.client(
    "s3",
    endpoint_url="https://s3-blob.squarecloud.app",
    aws_access_key_id="SQ2_...",
    aws_secret_access_key="...",
    region_name="auto",
    config=Config(signature_version="s3v4", s3={"addressing_style": "path"}),
)

s3.upload_file("report.pdf", "private", "reports/2026/report.pdf")
url = s3.generate_presigned_url(
    "get_object",
    Params={"Bucket": "private", "Key": "reports/2026/report.pdf"},
    ExpiresIn=3600,
)

import { S3Client, PutObjectCommand } from "@aws-sdk/client-s3";

const s3 = new S3Client({
  endpoint: "https://s3-blob.squarecloud.app",
  region: "auto",
  forcePathStyle: true,
  credentials: { accessKeyId: "SQ2_...", secretAccessKey: "..." },
});

await s3.send(new PutObjectCommand({
  Bucket: "public",
  Key: "images/logo.png",
  Body: buffer,
  ContentType: "image/png",
}));

[squarecloud]
type = s3
provider = Other
access_key_id = SQ2_...
secret_access_key = ...
endpoint = https://s3-blob.squarecloud.app
region = auto
force_path_style = true

boto3 richiede signature_version="s3v4" per gli URL prefirmati: senza, generate_presigned_url firma con il vecchio SigV2, che il gateway non accetta. Gli URL prefirmati durano fino a 7 giorni (604800 secondi).

Le risposte del gateway non vengono mai messe in cache all’edge. Un URL prefirmato smette di funzionare esattamente quando scade, quando la chiave API viene revocata o quando l’oggetto viene eliminato.

Operazioni supportate

Area	Operazioni
Bucket	`ListBuckets`, `HeadBucket`, `GetBucketLocation`. `CreateBucket` su un bucket esistente ha esito positivo; `DeleteBucket` risponde `BucketNotEmpty` finché il bucket contiene file.
Elenco	`ListObjects` e `ListObjectsV2`, con `delimiter`, `prefix` e `encoding-type=url`.
Oggetti	`HeadObject`, `GetObject` (con `Range`, `If-Match`, `If-None-Match`, `If-Modified-Since`), `PutObject` (fino a 100 MB in una sola richiesta), `CopyObject` (direttive di metadati `COPY` e `REPLACE`), `DeleteObject`, `DeleteObjects` (fino a 1000 chiavi).
Multipart	`CreateMultipartUpload`, `UploadPart` (da 5 MB a 80 MB per parte, tranne l’ultima), `UploadPartCopy`, `CompleteMultipartUpload`, `AbortMultipartUpload`, `ListParts`, `ListMultipartUploads`. Oggetti fino a 10 GiB.
Integrità	`Content-MD5` viene sempre verificato, anche quando viene inviato anche un header `x-amz-checksum-*`. Vengono verificati anche `x-amz-checksum-crc32`, `-sha1` e `-sha256`; una mancata corrispondenza risponde `BadDigest`. `crc32c` e `crc64nvme` sono accettati senza verifica. I corpi `aws-chunked` sono supportati.
Compatibilità	`GetBucketVersioning`, `GetBucketAcl`, `GetObjectAcl` e le letture dei tag rispondono con valori fissi, così gli strumenti che li interrogano continuano a funzionare.

Bucket policy, CORS, lifecycle, website, crittografia, object lock, versioni, logging, notifiche, replica, scritture di ACL e tag, GET per partNumber e upload tramite form POST dal browser rispondono 501 NotImplemented. Usa le impostazioni dell’account per le regole di lifecycle.

Chiavi

Le chiavi sono percorsi letterali. Una chiave può avere fino a circa 1000 byte: il limite di 1024 byte conta anche il prefisso dell’account. Una chiave più lunga risponde KeyTooLongError, e il suo messaggio indica il numero esatto di byte a tua disposizione. I segmenti non possono essere vuoti, . o ...
Una chiave di 0 byte che termina con / è un marcatore di cartella, come le cartelle create dalla console AWS.
Il Content-Type servito è derivato dall’estensione, come sull’API REST. Gli eseguibili vengono rifiutati con InvalidArgument e .html, .svg e .xml vengono serviti come download.

Metadati, cache e scadenza

Gli header x-amz-meta-* vengono mantenuti su Pro ed Enterprise (fino a 5 chiavi e 512 byte, altrimenti MetadataTooLarge). Sugli altri piani vengono scartati.
Cache-Control e Content-Disposition vengono mantenuti. Un Cache-Control senza cache (no-cache, no-store o max-age=0) al di fuori di Enterprise viene rifiutato con AccessDenied.
Le regole per prefisso si applicano agli oggetti scritti tramite S3, compresa l’eliminazione automatica. max_size ed extensions di una regola si applicano solo agli upload REST.

Limiti

Limite	Valore
Richieste per account, ogni 10 secondi	Hobby 100 · Standard 200 · Pro 400 · Enterprise 600
Copie lato server (`CopyObject`, `UploadPartCopy`)	20 ogni 10 secondi
Chiavi eliminate da `DeleteObjects`	2000 ogni 10 secondi
Upload multipart aperti	32 per account, condivisi con gli upload chunked REST
Singolo `PutObject`	100 MB
Parte (`UploadPart`)	Da 5 MB a 80 MB, tranne l’ultima parte
Dimensione dell’oggetto	10 GiB
Credenziali non valide	Troppi errori bloccano l’IP per qualche minuto

Oltre un limite il gateway risponde SlowDown (HTTP 503), e gli SDK AWS attendono e riprovano da soli. Le richieste S3 non contano nel limite di richieste API del tuo piano. Controlla la coppia di chiavi prima di riprovare in un ciclo: un IP che invia troppe credenziali non valide viene bloccato per qualche minuto.

Dimensione delle parti

Gli strumenti multipart dividono da soli i file grandi; mantieni ogni parte a 80 MB o meno. I valori predefiniti di AWS CLI (8 MB) e rclone (5 MB) vanno già bene.

aws configure set default.s3.multipart_chunksize 64MB

from boto3.s3.transfer import TransferConfig

config = TransferConfig(multipart_chunksize=64 * 1024 * 1024)
s3.upload_file("backup.tar.gz", "private", "backups/backup.tar.gz", Config=config)

import { Upload } from "@aws-sdk/lib-storage";

await new Upload({
  client: s3,
  params: { Bucket: "private", Key: "backups/backup.tar.gz", Body: stream },
  partSize: 64 * 1024 * 1024, // fino a 80 MB
}).done();

La scrittura richiede un piano a pagamento. Senza piano, e sul bucket legacy di sola lettura, le scritture rispondono AccessDenied. La quota di storage si applica come sull’API REST.

Errori

Il gateway risponde con gli errori XML standard di S3, così gli SDK li gestiscono in modo nativo:

Errore	Quando
`AccessDenied`	Nessun piano a pagamento, chiave di sola lettura, scrittura su `legacy` o un’opzione non inclusa nel tuo piano.
`NoSuchBucket`	Il bucket non è `public`, `private` o `legacy`.
`NoSuchKey`	L’oggetto non esiste.
`InvalidArgument`	Un tipo di file bloccato (eseguibili e installer) o un header malformato.
`QuotaExceeded`	L’account ha raggiunto lo storage incluso.
`EntityTooLarge` / `EntityTooSmall`	Un `PutObject` oltre 100 MB, una parte oltre 80 MB o una parte sotto 5 MB che non è l’ultima.
`InvalidPart` / `InvalidPartOrder` / `NoSuchUpload`	Completamento multipart con parti errate, oppure un upload che non esiste più.
`BadDigest`	Il corpo non corrisponde a `Content-MD5` o all’header `x-amz-checksum-*`.
`PreconditionFailed`	Una condizione `If-Match` o `If-None-Match` non è soddisfatta.
`MetadataTooLarge`	Più di 5 chiavi di metadati o 512 byte.
`KeyTooLongError`	La chiave è troppo lunga (circa 1000 byte). Il messaggio indica il limite esatto per il tuo account.
`SlowDown`	HTTP 503: è stato raggiunto un limite di frequenza o il limite di upload aperti. Gli SDK riprovano da soli con backoff.
`NotImplemented`	L’operazione non è supportata (vedi sopra).

Primi Passi

Oggetti

Upload a Blocchi

Account

Link di Condivisione

S3

Credenziali

Bucket

Configurazione

Operazioni supportate

Chiavi

Metadati, cache e scadenza

Limiti

Dimensione delle parti

Errori

​Credenziali

​Bucket

​Configurazione

​Operazioni supportate

​Chiavi

​Metadati, cache e scadenza

​Limiti

​Dimensione delle parti

​Errori

Credenziali

Bucket

Configurazione

Operazioni supportate

Chiavi

Metadati, cache e scadenza

Limiti

Dimensione delle parti

Errori