> ## 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. # Compatibilidade com S3 > Use aws-cli, boto3, rclone e os AWS SDKs com o Blob Storage pelo gateway compatível com S3: endpoint, buckets, operações suportadas e limites. O Blob Storage fala a API S3 em `https://s3-blob.squarecloud.app`. Qualquer ferramenta que permita definir um endpoint personalizado funciona: aws-cli, boto3, o AWS SDK para JavaScript, rclone, Cyberduck e a maioria das ferramentas de backup. ## Credenciais Ferramentas S3 assinam as requisições com um par de chaves de acesso. Obtenha-o em [Credenciais S3](/pt-br/blob-reference/endpoint/s3-credentials): ```bash theme={null} curl https://blob.squarecloud.app/v1/s3/credentials \ --header 'Authorization: YOUR_API_KEY' ``` O par é **derivado da sua chave de API**. Ele não precisa de gerenciamento separado: revogar ou regenerar a chave faz o mesmo com o par, e o par recebe os mesmos escopos. Uma chave com apenas `blob:read` gera um par somente leitura. O par não muda enquanto a chave de API não mudar, então busque-o uma vez e guarde-o no seu gerenciador de segredos ou em uma variável de ambiente. Não chame a rota a cada inicialização: ela aceita 10 requisições por hora. | Configuração | Valor | | ------------- | ------------------------------------------------------------- | | Endpoint | `https://s3-blob.squarecloud.app` | | Região | `auto` | | Endereçamento | Path-style (`https://s3-blob.squarecloud.app//`) | | Assinatura | AWS Signature Version 4 | ## Buckets A sua conta enxerga três buckets fixos. Não é possível criar nem excluir buckets. | Bucket | Conteúdo | Acesso | | --------- | --------------------------------------------------------------------------------- | ---------------------------- | | `public` | Arquivos públicos, servidos em `https://blob.squarecloud.dev/pub//` | Leitura e escrita | | `private` | Arquivos privados, sem URL pública | Leitura e escrita | | `legacy` | Arquivos legados, enviados antes da atualização de setembro de 2026 | Leitura, listagem e exclusão | Uma chave no bucket `public` ou `private` é o caminho do objeto **sem** o seu ID de usuário: `images/logo.png` no bucket `public` é o objeto `pub//images/logo.png` na API REST. Arquivos gravados pelo S3 aparecem na API REST e no dashboard, e vice-versa. ## Configuração ```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 ``` O boto3 precisa de `signature_version="s3v4"` para URLs pré-assinadas: sem isso, o `generate_presigned_url` assina com o SigV2 antigo, que o gateway não aceita. URLs pré-assinadas duram até 7 dias (604800 segundos). As respostas do gateway nunca ficam em cache no edge. Uma URL pré-assinada deixa de funcionar exatamente quando expira, quando a chave de API é revogada ou quando o objeto é excluído. ## Operações suportadas | Área | Operações | | --------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Buckets | `ListBuckets`, `HeadBucket`, `GetBucketLocation`. `CreateBucket` em um bucket existente tem sucesso; `DeleteBucket` responde `BucketNotEmpty` enquanto o bucket tiver arquivos. | | Listagem | `ListObjects` e `ListObjectsV2`, com `delimiter`, `prefix` e `encoding-type=url`. | | Objetos | `HeadObject`, `GetObject` (com `Range`, `If-Match`, `If-None-Match`, `If-Modified-Since`), `PutObject` (até 100 MB em uma única requisição), `CopyObject` (diretivas de metadados `COPY` e `REPLACE`), `DeleteObject`, `DeleteObjects` (até 1000 chaves). | | Multipart | `CreateMultipartUpload`, `UploadPart` (de 5 MB a 80 MB por parte, exceto a última), `UploadPartCopy`, `CompleteMultipartUpload`, `AbortMultipartUpload`, `ListParts`, `ListMultipartUploads`. Objetos de até 10 GiB. | | Integridade | `Content-MD5` é sempre verificado, mesmo quando um cabeçalho `x-amz-checksum-*` também é enviado. `x-amz-checksum-crc32`, `-sha1` e `-sha256` também são verificados; uma divergência responde `BadDigest`. `crc32c` e `crc64nvme` são aceitos sem verificação. Corpos `aws-chunked` são suportados. | | Compatibilidade | `GetBucketVersioning`, `GetBucketAcl`, `GetObjectAcl` e as leituras de tags respondem valores fixos, para que as ferramentas que as consultam continuem funcionando. | Políticas de bucket, CORS, lifecycle, website, criptografia, object lock, versões, logging, notificações, replicação, escrita de ACL e de tags, `GET` por `partNumber` e uploads por formulário POST do navegador respondem `501 NotImplemented`. Use as [configurações da conta](/pt-br/blob-reference/endpoint/settings-put) para regras de lifecycle. ## Chaves * As chaves são caminhos literais. Uma chave pode ter até cerca de 1000 bytes: o limite de 1024 bytes também conta o prefixo da conta. Uma chave maior responde `KeyTooLongError`, e a mensagem diz o número exato de bytes que você tem. Os segmentos não podem ser vazios, `.` ou `..`. * Uma chave de 0 bytes terminada em `/` é um marcador de pasta, do jeito que o console da AWS cria pastas. * O `Content-Type` servido é derivado da extensão, como na API REST. Executáveis são recusados com `InvalidArgument`, e `.html`, `.svg` e `.xml` são servidos como download. ## Metadados, cache e expiração * Os cabeçalhos `x-amz-meta-*` são mantidos no **Pro e no Enterprise** (até 5 chaves e 512 bytes, caso contrário `MetadataTooLarge`). Nos demais planos eles são descartados. * `Cache-Control` e `Content-Disposition` são mantidos. Um `Cache-Control` sem cache (`no-cache`, `no-store` ou `max-age=0`) fora do Enterprise é recusado com `AccessDenied`. * As [regras por prefixo](/pt-br/blob-reference/endpoint/settings-put) se aplicam aos objetos gravados pelo S3, incluindo a exclusão automática. `max_size` e `extensions` de uma regra só se aplicam aos uploads pela API REST. ## Limites | Limite | Valor | | --------------------------------------------------- | ------------------------------------------------------------------- | | Requisições por conta, a cada 10 segundos | **Hobby** 100 · **Standard** 200 · **Pro** 400 · **Enterprise** 600 | | Cópias no servidor (`CopyObject`, `UploadPartCopy`) | 20 a cada 10 segundos | | Chaves excluídas por `DeleteObjects` | 2000 a cada 10 segundos | | Uploads multipart abertos | 32 por conta, compartilhados com os uploads em partes da API REST | | `PutObject` único | 100 MB | | Parte (`UploadPart`) | 5 MB a 80 MB, exceto a última parte | | Tamanho do objeto | 10 GiB | | Credenciais inválidas | Falhas demais bloqueiam o IP por alguns minutos | Acima de um limite, o gateway responde `SlowDown` (HTTP 503), e os SDKs da AWS esperam e tentam novamente por conta própria. As requisições S3 **não contam** para o limite de requisições de API do seu plano. Confira o par de chaves antes de tentar novamente em loop: um IP que envia credenciais inválidas demais fica bloqueado por alguns minutos. ### Tamanho da parte As ferramentas multipart dividem arquivos grandes por conta própria; mantenha cada parte com **80 MB ou menos**. Os padrões do AWS CLI (8 MB) e do rclone (5 MB) já se encaixam. ```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, // até 80 MB }).done(); ``` Gravar exige um plano pago. Sem ele, e no bucket `legacy` (somente leitura), as gravações respondem `AccessDenied`. A cota de armazenamento se aplica como na API REST. ## Erros O gateway responde com os erros XML padrão do S3, então os SDKs os tratam nativamente: | Erro | Quando | | --------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------- | | `AccessDenied` | Sem plano pago, chave somente leitura, gravação no `legacy` ou uma opção fora do seu plano. | | `NoSuchBucket` | O bucket não é `public`, `private` nem `legacy`. | | `NoSuchKey` | O objeto não existe. | | `InvalidArgument` | Um tipo de arquivo bloqueado (executáveis e instaladores) ou um cabeçalho malformado. | | `QuotaExceeded` | A conta atingiu o armazenamento incluído. | | `EntityTooLarge` / `EntityTooSmall` | Um `PutObject` acima de 100 MB, uma parte acima de 80 MB ou uma parte abaixo de 5 MB que não seja a última. | | `InvalidPart` / `InvalidPartOrder` / `NoSuchUpload` | Conclusão de multipart com partes inválidas, ou um upload que não existe mais. | | `BadDigest` | O corpo não corresponde ao `Content-MD5` ou ao cabeçalho `x-amz-checksum-*`. | | `PreconditionFailed` | Uma condição `If-Match` ou `If-None-Match` falhou. | | `MetadataTooLarge` | Mais de 5 chaves de metadados ou 512 bytes. | | `KeyTooLongError` | A chave é longa demais (cerca de 1000 bytes). A mensagem diz o limite exato da sua conta. | | `SlowDown` | HTTP 503: um limite de taxa ou o limite de uploads abertos foi atingido. Os SDKs tentam novamente com backoff por conta própria. | | `NotImplemented` | A operação não é suportada (veja acima). |