> ## 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. # S3-Kompatibilität > Nutze aws-cli, boto3, rclone und die AWS SDKs mit Blob Storage über das S3-kompatible Gateway: Endpoint, Buckets, unterstützte Operationen und Limits. Blob Storage spricht die S3-API unter `https://s3-blob.squarecloud.app`. Jedes Tool, bei dem du einen eigenen Endpoint festlegen kannst, funktioniert: aws-cli, boto3, das AWS SDK für JavaScript, rclone, Cyberduck und die meisten Backup-Tools. ## Zugangsdaten S3-Tools signieren Requests mit einem Zugangsschlüsselpaar. Hol es dir über [S3 Credentials](/de/blob-reference/endpoint/s3-credentials): ```bash theme={null} curl https://blob.squarecloud.app/v1/s3/credentials \ --header 'Authorization: YOUR_API_KEY' ``` Das Paar wird **aus deinem API-Schlüssel abgeleitet**. Es braucht keine separate Verwaltung: Das Widerrufen oder Neugenerieren des Schlüssels wirkt sich genauso auf das Paar aus, und das Paar erhält dieselben Scopes. Ein Schlüssel mit nur `blob:read` ergibt ein reines Lese-Paar. Das Paar ändert sich nicht, solange sich der API-Schlüssel nicht ändert. Hol es also einmal ab und bewahre es in deinem Secret Manager oder in einer Umgebungsvariable auf. Ruf die Route nicht bei jedem Start auf: Sie akzeptiert 10 Requests pro Stunde. | Einstellung | Wert | | ------------ | ------------------------------------------------------------- | | Endpoint | `https://s3-blob.squarecloud.app` | | Region | `auto` | | Adressierung | Path-Style (`https://s3-blob.squarecloud.app//`) | | Signatur | AWS Signature Version 4 | ## Buckets Dein Konto sieht drei feste Buckets. Du kannst keine Buckets erstellen oder löschen. | Bucket | Inhalt | Zugriff | | --------- | ------------------------------------------------------------------------------------------ | ---------------------------- | | `public` | Öffentliche Dateien, ausgeliefert unter `https://blob.squarecloud.dev/pub//` | Lesen und Schreiben | | `private` | Private Dateien, ohne öffentliche URL | Lesen und Schreiben | | `legacy` | Legacy-Dateien, hochgeladen vor dem Update im September 2026 | Lesen, Auflisten und Löschen | Ein Key im Bucket `public` oder `private` ist der Objektpfad **ohne** deine Nutzer-ID: `images/logo.png` im Bucket `public` ist in der REST-API das Objekt `pub//images/logo.png`. Dateien, die über S3 geschrieben werden, erscheinen in der REST-API und im Dashboard, und umgekehrt. ## Konfiguration ```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 braucht `signature_version="s3v4"` für Presigned URLs: Ohne diese Einstellung signiert `generate_presigned_url` mit dem älteren SigV2, das das Gateway nicht akzeptiert. Presigned URLs gelten bis zu 7 Tage (604800 Sekunden). Antworten des Gateways werden nie an der Edge gecacht. Eine Presigned URL funktioniert genau dann nicht mehr, wenn sie abläuft, wenn der API-Schlüssel widerrufen wird oder wenn das Objekt gelöscht wird. ## Unterstützte Operationen | Bereich | Operationen | | -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Buckets | `ListBuckets`, `HeadBucket`, `GetBucketLocation`. `CreateBucket` auf einen bestehenden Bucket ist erfolgreich; `DeleteBucket` antwortet mit `BucketNotEmpty`, solange der Bucket Dateien enthält. | | Auflisten | `ListObjects` und `ListObjectsV2`, mit `delimiter`, `prefix` und `encoding-type=url`. | | Objekte | `HeadObject`, `GetObject` (mit `Range`, `If-Match`, `If-None-Match`, `If-Modified-Since`), `PutObject` (bis 100 MB in einem Request), `CopyObject` (Metadaten-Direktiven `COPY` und `REPLACE`), `DeleteObject`, `DeleteObjects` (bis 1000 Keys). | | Multipart | `CreateMultipartUpload`, `UploadPart` (5 MB bis 80 MB pro Teil, außer dem letzten), `UploadPartCopy`, `CompleteMultipartUpload`, `AbortMultipartUpload`, `ListParts`, `ListMultipartUploads`. Objekte bis 10 GiB. | | Integrität | `Content-MD5` wird immer verifiziert, auch wenn zusätzlich ein `x-amz-checksum-*`-Header gesendet wird. `x-amz-checksum-crc32`, `-sha1` und `-sha256` werden ebenfalls verifiziert; eine Abweichung antwortet mit `BadDigest`. `crc32c` und `crc64nvme` werden ohne Verifizierung akzeptiert. `aws-chunked`-Bodys werden unterstützt. | | Kompatibilität | `GetBucketVersioning`, `GetBucketAcl`, `GetObjectAcl` und die Tagging-Lesezugriffe antworten mit festen Werten, damit Tools, die sie abfragen, weiter funktionieren. | Bucket Policies, CORS, Lifecycle, Website, Verschlüsselung, Object Lock, Versionen, Logging, Benachrichtigungen, Replikation, ACL- und Tag-Schreibzugriffe, `GET` per `partNumber` sowie Browser-POST-Formular-Uploads antworten mit `501 NotImplemented`. Verwende die [Kontoeinstellungen](/de/blob-reference/endpoint/settings-put) für Lifecycle-Regeln. ## Keys * Keys sind wörtliche Pfade. Ein Key kann bis zu etwa 1000 Bytes lang sein: Das Limit von 1024 Bytes zählt auch das Kontopräfix mit. Ein längerer Key antwortet mit `KeyTooLongError`, und die Meldung nennt die genaue Anzahl an Bytes, die dir zur Verfügung stehen. Segmente dürfen nicht leer, `.` oder `..` sein. * Ein 0-Byte-Key, der auf `/` endet, ist ein Ordner-Marker, so wie die AWS-Konsole Ordner erstellt. * Der ausgelieferte `Content-Type` wird wie in der REST-API aus der Endung bestimmt. Ausführbare Dateien werden mit `InvalidArgument` abgelehnt, und `.html`, `.svg` und `.xml` werden als Downloads ausgeliefert. ## Metadaten, Cache und Ablauf * `x-amz-meta-*`-Header bleiben bei **Pro und Enterprise** erhalten (bis zu 5 Schlüssel und 512 Bytes, sonst `MetadataTooLarge`). Bei anderen Plänen werden sie verworfen. * `Cache-Control` und `Content-Disposition` bleiben erhalten. Ein `Cache-Control` ohne Caching (`no-cache`, `no-store` oder `max-age=0`) wird außerhalb von Enterprise mit `AccessDenied` abgelehnt. * [Regeln pro Präfix](/de/blob-reference/endpoint/settings-put) gelten für Objekte, die über S3 geschrieben werden, einschließlich der automatischen Löschung. `max_size` und `extensions` einer Regel gelten nur für REST-Uploads. ## Limits | Limit | Wert | | ----------------------------------------------------- | ------------------------------------------------------------------- | | Requests pro Konto, alle 10 Sekunden | **Hobby** 100 · **Standard** 200 · **Pro** 400 · **Enterprise** 600 | | Serverseitige Kopien (`CopyObject`, `UploadPartCopy`) | 20 pro 10 Sekunden | | Per `DeleteObjects` gelöschte Keys | 2000 pro 10 Sekunden | | Offene Multipart-Uploads | 32 pro Konto, geteilt mit den Chunked Uploads der REST-API | | Einzelnes `PutObject` | 100 MB | | Teil (`UploadPart`) | 5 MB bis 80 MB, außer dem letzten Teil | | Objektgröße | 10 GiB | | Ungültige Zugangsdaten | Zu viele Fehlversuche sperren die IP für einige Minuten | Über einem Limit antwortet das Gateway mit `SlowDown` (HTTP 503), und die AWS SDKs warten und wiederholen von selbst. S3-Requests **zählen nicht** zum API-Request-Limit deines Plans. Prüfe das Schlüsselpaar, bevor du in einer Schleife wiederholst: Eine IP, die zu viele ungültige Zugangsdaten sendet, wird für einige Minuten gesperrt. ### Teilgröße Multipart-Tools teilen große Dateien selbst auf; halte jeden Teil bei **80 MB oder weniger**. Die Standardwerte der AWS CLI (8 MB) und von rclone (5 MB) passen bereits. ```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, // bis 80 MB }).done(); ``` Schreiben erfordert einen kostenpflichtigen Plan. Ohne einen solchen, und im reinen Lese-Bucket `legacy`, antworten Schreibzugriffe mit `AccessDenied`. Das Speicherkontingent gilt wie in der REST-API. ## Fehler Das Gateway antwortet mit Standard-S3-XML-Fehlern, sodass SDKs sie nativ verarbeiten: | Fehler | Wann | | --------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------ | | `AccessDenied` | Kein kostenpflichtiger Plan, reiner Lese-Schlüssel, Schreiben in `legacy` oder eine Option außerhalb deines Plans. | | `NoSuchBucket` | Der Bucket ist nicht `public`, `private` oder `legacy`. | | `NoSuchKey` | Das Objekt existiert nicht. | | `InvalidArgument` | Ein gesperrter Dateityp (ausführbare Dateien und Installer) oder ein fehlerhafter Header. | | `QuotaExceeded` | Das Konto hat seinen enthaltenen Speicher erreicht. | | `EntityTooLarge` / `EntityTooSmall` | Ein `PutObject` über 100 MB, ein Teil über 80 MB oder ein Teil unter 5 MB, der nicht der letzte ist. | | `InvalidPart` / `InvalidPartOrder` / `NoSuchUpload` | Multipart-Abschluss mit fehlerhaften Teilen oder ein Upload, der nicht mehr existiert. | | `BadDigest` | Der Body stimmt nicht mit `Content-MD5` oder dem `x-amz-checksum-*`-Header überein. | | `PreconditionFailed` | Eine `If-Match`- oder `If-None-Match`-Bedingung ist fehlgeschlagen. | | `MetadataTooLarge` | Mehr als 5 Metadaten-Schlüssel oder 512 Bytes. | | `KeyTooLongError` | Der Key ist zu lang (etwa 1000 Bytes). Die Meldung nennt das genaue Limit für dein Konto. | | `SlowDown` | HTTP 503: Ein Rate Limit oder das Limit offener Uploads wurde erreicht. SDKs wiederholen von selbst mit Backoff. | | `NotImplemented` | Die Operation wird nicht unterstützt (siehe oben). |