> ## Documentation Index > Fetch the complete documentation index at: https://docs.squarecloud.app/llms.txt > Use this file to discover all available pages before exploring further. # Compatibilità S3 > Usa aws-cli, boto3, rclone e gli SDK AWS con Blob Storage tramite il gateway compatibile con S3: endpoint, bucket, operazioni supportate e limiti. 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](/it/blob-reference/endpoint/s3-credentials): ```bash theme={null} 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//`) | | 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//` | 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//images/logo.png` sull'API REST. I file scritti tramite S3 compaiono sull'API REST e nella dashboard, e viceversa. ## Configurazione ```bash aws-cli theme={null} 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 ``` ```python boto3 theme={null} 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, ) ``` ```javascript AWS SDK v3 theme={null} 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", })); ``` ```ini rclone theme={null} [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](/it/blob-reference/endpoint/settings-put) 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](/it/blob-reference/endpoint/settings-put) 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. ```bash aws-cli theme={null} aws configure set default.s3.multipart_chunksize 64MB ``` ```python boto3 theme={null} 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) ``` ```javascript AWS SDK v3 theme={null} 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). |