Object storage

O bucket é um recurso do canvas do ambiente, como uma aplicação ou um banco. Ele guarda arquivos (uploads de usuários, imagens, relatórios, exportações) e fala a API S3, então os SDKs da AWS e as ferramentas que você já usa funcionam sem mudança.

Um bucket entra no ambiente pelo mesmo fluxo de qualquer recurso: você o adiciona ao rascunho, liga as aplicações que vão usá-lo e aplica a revisão.

Criar um bucket e ligar aplicações

No canvas do ambiente, adicione um recurso Bucket e defina a cota (espaço máximo em GiB).
Ligue cada aplicação que vai usar o bucket com uma aresta de referência. Na aresta, escolha o acesso:
- leitura e escrita (padrão);
- só leitura;
- opcionalmente, um prefixo (por exemplo uploads/), que limita a chave àquela parte do bucket.
Aplique a revisão. A plataforma cria o bucket, emite uma chave própria para cada aplicação ligada e injeta as variáveis no ambiente dela. As aplicações reiniciam para receber os valores.

Cada aplicação recebe uma chave diferente. Remover a aresta revoga a chave daquela aplicação sem afetar as outras. Rotacionar a chave de uma aplicação cria a nova antes, reinicia a aplicação e só então revoga a antiga.

Variáveis injetadas

Variável	Secreta	Conteúdo
`S3_ENDPOINT`	não	Endpoint HTTPS do serviço, por exemplo `https://s3.apps.<domínio>`
`S3_REGION`	não	Região a informar ao SDK (`us-east-1`)
`S3_BUCKET`	não	Nome físico do bucket (`b-...`), diferente do nome que você deu no canvas
`S3_FORCE_PATH_STYLE`	não	`true`: o endereço é sempre `https://<endpoint>/<bucket>/<chave>`
`AWS_ACCESS_KEY_ID`	sim	Chave de acesso desta aplicação
`AWS_SECRET_ACCESS_KEY`	sim	Segredo da chave desta aplicação

Os valores secretos ficam no cofre da sua organização e nunca aparecem no portal, nos logs nem na API.

O endpoint é o mesmo para as aplicações e para os navegadores. Por isso uma URL pré-assinada gerada pelo backend funciona em qualquer lugar.

Saída de rede

A aresta de referência também libera a saída de rede da aplicação até o endpoint. Sem a aresta, a aplicação não alcança o serviço.

Usar nos SDKs da AWS

Configure o SDK com S3_ENDPOINT, S3_REGION e path-style (S3_FORCE_PATH_STYLE=true). As credenciais vêm de AWS_ACCESS_KEY_ID e AWS_SECRET_ACCESS_KEY, que todos os SDKs leem do ambiente.

Node.js (AWS SDK v3)

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

const s3 = new S3Client({
  endpoint: process.env.S3_ENDPOINT,
  region: process.env.S3_REGION,
  forcePathStyle: process.env.S3_FORCE_PATH_STYLE === "true",
});

await s3.send(
  new PutObjectCommand({
    Bucket: process.env.S3_BUCKET,
    Key: "uploads/relatorio.pdf",
    Body: buffer,
    ContentType: "application/pdf",
  }),
);

.NET (AWSSDK.S3)

using Amazon.S3;
using Amazon.S3.Model;

var config = new AmazonS3Config
{
    ServiceURL = Environment.GetEnvironmentVariable("S3_ENDPOINT"),
    AuthenticationRegion = Environment.GetEnvironmentVariable("S3_REGION"),
    ForcePathStyle = Environment.GetEnvironmentVariable("S3_FORCE_PATH_STYLE") == "true",
};
using var s3 = new AmazonS3Client(config); // credenciais de AWS_ACCESS_KEY_ID / AWS_SECRET_ACCESS_KEY

await s3.PutObjectAsync(new PutObjectRequest
{
    BucketName = Environment.GetEnvironmentVariable("S3_BUCKET"),
    Key = "uploads/relatorio.pdf",
    FilePath = "/tmp/relatorio.pdf",
});

Python (boto3)

import os
import boto3
from botocore.config import Config

s3 = boto3.client(
    "s3",
    endpoint_url=os.environ["S3_ENDPOINT"],
    region_name=os.environ["S3_REGION"],
    config=Config(s3={"addressing_style": "path" if os.environ.get("S3_FORCE_PATH_STYLE") == "true" else "auto"}),
)

s3.upload_file("/tmp/relatorio.pdf", os.environ["S3_BUCKET"], "uploads/relatorio.pdf")

URLs pré-assinadas

Para que o navegador envie ou baixe um arquivo direto do bucket, sem passar pelo seu backend, gere uma URL pré-assinada com a chave da aplicação:

import { getSignedUrl } from "@aws-sdk/s3-request-presigner";

const url = await getSignedUrl(s3, new PutObjectCommand({ Bucket: process.env.S3_BUCKET, Key: "uploads/foto.png" }), {
  expiresIn: 900, // segundos
});

A URL só pode fazer o que a chave da aplicação pode: uma aplicação de só leitura não gera URL de envio que funcione. Para envio direto do navegador, configure também o CORS do bucket.

CORS

Para chamadas de um navegador em outra origem (o front-end da sua aplicação), adicione regras de CORS ao bucket, com até 10 regras:

origens (por exemplo https://app.exemplo.com);
métodos (GET, PUT, POST, DELETE, HEAD);
cabeçalhos permitidos e expostos (exponha ETag para envio em partes);
tempo de cache da resposta de preflight.

A plataforma recusa origem curinga (*) junto com métodos de escrita. O portal tem uma regra própria, reservada, para o navegador de arquivos, que não conta no limite de 10.

Lifecycle

Regras de lifecycle (até 20 por bucket) apagam dados automaticamente por prefixo:

Campo	Efeito
`prefix`	Parte do bucket a que a regra se aplica (vazio = bucket inteiro)
`expirationDays`	Apaga objetos com mais de N dias
`noncurrentExpirationDays`	Com versionamento, apaga versões antigas com mais de N dias
`abortIncompleteMultipartDays`	Descarta envios em partes não concluídos depois de N dias

Versionamento

Com o versionamento ligado, cada gravação guarda a versão anterior e cada exclusão vira um marcador, de modo que você pode restaurar uma versão pelo portal (gaveta Versões do arquivo) ou pelo SDK.

Os estados seguem a regra do S3:

nunca ligado → ligado ↔ suspenso

Depois de ligado, o versionamento não volta a "nunca ligado": só pode ser suspenso (novas gravações deixam de criar versões, as antigas continuam guardadas). Versões antigas ocupam espaço da cota; use noncurrentExpirationDays para limpá-las.

Conteúdo público

Um bucket pode servir arquivos para qualquer pessoa, sem chave, em dois modos:

bucket inteiro;
prefixos (até 10, por exemplo public/ e assets/).

O acesso anônimo é sempre só de leitura de objetos: ninguém lista o bucket, envia nem apaga sem chave. A URL pública é https://s3.apps.<domínio>/<S3_BUCKET>/<chave>.

Para proteger os visitantes, toda resposta do serviço sai com:

Content-Security-Policy: sandbox: um HTML ou SVG servido pelo bucket não executa scripts nem acessa cookies, mesmo se aberto direto no navegador;
X-Content-Type-Options: nosniff: o navegador respeita o Content-Type gravado;
Cross-Origin-Resource-Policy: cross-origin: imagens e arquivos podem ser usados em páginas de outras origens.

Se você precisa servir um site estático com scripts, publique-o como aplicação, não pelo bucket. Conteúdo abusivo segue a política de uso aceitável; a suspensão de uma organização bloqueia a leitura pública e as chaves.

Chaves externas

Para uma ferramenta fora da plataforma (um backup, um pipeline de dados), um Admin do projeto cria uma chave externa na aba Chaves do bucket: nome, permissão (leitura ou leitura e escrita), prefixo opcional e validade opcional. O segredo aparece uma única vez. Revogar a chave corta o acesso em até um minuto.

Navegador de arquivos no portal

A aba Arquivos do bucket lista os objetos por pasta e permite enviar (arrastando ou pelo botão, com envio em partes para arquivos grandes), baixar, apagar e restaurar versões. Ver a lista exige o papel Viewer; enviar, baixar e apagar exigem Developer.

Limites por plano

Plano	Buckets	Espaço total	Transferência de saída por mês	Leitura pública	Versionamento	Excedente cobrado	Chaves externas por bucket
Starter	2	10 GiB	20 GiB	sim	não	não	2
Pro	10	250 GiB	500 GiB	sim	sim	sim	10
Business	50	2 TiB	4 TiB	sim	sim	sim	25
Enterprise	200	20 TiB	40 TiB	sim	sim	sim	50

Espaço: é a soma das cotas dos buckets. Ao atingir a cota de um bucket, novas gravações são recusadas e a leitura continua. Você recebe aviso em 80% e 100%.
Transferência de saída: sem excedente cobrado, ao esgotar a franquia do mês a leitura dos buckets da organização é bloqueada até a virada do ciclo ou a troca de plano. Com excedente, o uso acima da franquia é cobrado.
Os valores efetivos da sua organização aparecem em Planos e limites no portal (veja Planos e limites).

Remover um bucket

Remover um bucket apaga todos os objetos e versões e revoga todas as chaves. Por isso exige o papel Admin e a confirmação de ação destrutiva no rascunho, que mostra quantos objetos e bytes serão apagados. A plataforma mantém uma cópia de recuperação de desastre, mas ela não é restaurável pelo portal: para desfazer erros do dia a dia, use o versionamento.

Criar um bucket e ligar aplicações​

Variáveis injetadas​

Usar nos SDKs da AWS​

Node.js (AWS SDK v3)​

.NET (AWSSDK.S3)​

Python (boto3)​

URLs pré-assinadas​

CORS​

Lifecycle​

Versionamento​

Conteúdo público​

Chaves externas​

Navegador de arquivos no portal​

Limites por plano​

Remover um bucket​