Resumo dos limites de upload de arquivo AWS S3 e CloudFront | Multiparte e URL assinada

Ao construir recursos de upload de arquivo usando AWS, é extremamente importante compreender que S3, CloudFront, API Gateway e Lambda têm diferentes limites de tamanho e qual camada se torna o gargalo. Este artigo organiza os limites de cada serviço, explica como usar uploads em múltiplas partes e URLs assinadas para lidar com arquivos grandes, e fornece exemplos de implementação em PHP.

Limite de upload do Amazon S3

O upload de objetos para S3 tem limites de tamanho diferentes dependendo do método utilizado.

A AWS recomenda o upload em múltiplas partes para arquivos de 100 MB ou mais, e deve ser usado ativamente para arquivos grandes tanto pela eficiência de retransmissão em caso de falha de rede quanto pela melhoria de throughput por transferência paralela.

Casos em que o upload multipart é necessário

O upload multipart é um método que divide um objeto em múltiplas partes, envia cada uma em requisições independentes e as combina ao final. É eficaz nos seguintes casos.

• <strong>Arquivos acima de 100 MB</strong>: Este é o ponto de corte para multipart recomendado pela AWS.
• <strong>ambientes com rede instável</strong>：mesmo se ocorrer erro, você pode reenviar apenas as partes que falharam.
• <strong>maximizar throughput</strong>：fazer upload de múltiplas partes em paralelo para melhorar a velocidade de transferência.
• <strong>pausar e retomar o upload</strong>：ao salvar o ID de Upload, você pode retomar entre sessões.

O fluxo de upload multipart tem basicamente 3 etapas.

1. <strong>Início</strong> (CreateMultipartUpload): obter o ID do Upload
2. <strong>Envio de partes</strong> (UploadPart): fazer upload de cada parte e registrar a ETag
3. <strong>Concluído</strong> (CompleteMultipartUpload): Enviar uma lista de números de partes e ETags para confirmar o objeto

Se cancelar no meio do caminho sem chamar <code>AbortMultipartUpload</code>, as partes incompletas continuarão sendo cobradas como taxa de armazenamento. É altamente recomendável configurar uma política de ciclo de vida do bucket S3 para 「削除未完了のマルチパートアップロードを N 日後に削除」.

Prazo de validade e tamanho da URL pré-assinada

Ao usar URLs pré-assinadas (Presigned URL), clientes sem permissão de acesso ao S3 (como navegadores e aplicativos móveis) podem fazer upload de arquivos diretamente para o S3. Como não passa por um servidor intermediário, é eficiente mesmo para arquivos de grande volume.

A URL pré-assinada é gerada no backend e retornada ao cliente, e o cliente envia uma solicitação PUT diretamente para essa URL. Como a URL contém uma assinatura, ela só terá sucesso se o arquivo correto for enviado dentro do prazo de validade.

Limite de tamanho de body do CloudFront

Ao encaminhar requisições através do CloudFront para uma origem (como S3 ou EC2), há um limite no tamanho do corpo da requisição.

Nas configurações de distribuição do CloudFront, você pode habilitar 「Allow requests with body」 e aumentar o limite, mas observe que em Lambda@Edge o limite de 1 MB não pode ser alterado. Para upload de arquivos grandes, recomendamos adotar uma arquitetura que faz upload direto de S3 do cliente usando Presigned URL, sem passar pelo CloudFront.

Limite de Payload do API Gateway

O API Gateway (tanto REST API quanto HTTP API) possui um limite máximo de tamanho de payload.

O limite de 10 MB do API Gateway é classificado como cota de serviço da AWS e não pode ser aumentado. Considere fazer upload de arquivos maiores que 10 MB via Presigned URL em vez de API Gateway, pois contornar esse limite é considerado um erro de design.

Limitações de arquivo via Lambda

Ao receber arquivos em uma função Lambda, há um limite para o payload de evento passado do API Gateway. Além disso, o Lambda em si tem as seguintes limitações.

Ao processar arquivos no Lambda, arquivos temporários são gravados em <code>/tmp</code>. O padrão é 512 MB, mas você pode estender o armazenamento efêmero até 10 GB máximo nas configurações do Lambda (com custo adicional).

Exemplo de código de upload multipart S3 em PHP

Este é um exemplo de implementação de upload em múltiplas partes usando AWS SDK for PHP (v3). Ao usar a classe <code>MultipartUploader</code> do SDK, a divisão de chunks, retentativas e processamento de conclusão são tratados automaticamente.

use Aws\S3\S3Client;
use Aws\S3\MultipartUploader;
use Aws\Exception\MultipartUploadException;

$s3 = new S3Client([
    'region'  => 'ap-northeast-1',
    'version' => 'latest',
]);

$uploader = new MultipartUploader($s3, '/path/to/large-file.mp4', [
    'bucket'          => 'your-bucket-name',
    'key'             => 'uploads/' . basename('/path/to/large-file.mp4'),
    'before_initiate' => function (\Aws\Command $command) {
        // アップロード開始前のフック
    },
    'before_upload'   => function (\Aws\Command $command) {
        // 各パートアップロード前のフック（プログレス表示など）
    },
    'concurrency'     => 5,    // 並列アップロード数
    'part_size'       => 10 * 1024 * 1024, // 1パート = 10 MiB
]);

try {
    $result = $uploader->upload();
    echo 'アップロード完了: ' . $result['ObjectURL'];
} catch (MultipartUploadException $e) {
    // 失敗したパートから再開する例
    $uploader = new MultipartUploader($s3, '/path/to/large-file.mp4', [
        'state' => $e->getState(),
    ]);
    $result = $uploader->upload();
}

Este é o método para emitir uma URL pré-assinada e permitir que o cliente faça upload diretamente para o S3.

use Aws\S3\S3Client;

$s3 = new S3Client([
    'region'  => 'ap-northeast-1',
    'version' => 'latest',
]);

// 署名付きURLを生成（有効期限: 15分）
$cmd = $s3->getCommand('PutObject', [
    'Bucket'       => 'your-bucket-name',
    'Key'          => 'uploads/' . uniqid('', true) . '.jpg',
    'ContentType'  => 'image/jpeg',
]);

$request = $s3->createPresignedRequest($cmd, '+15 minutes');
$presignedUrl = (string) $request->getUri();

// このURLをクライアントに返す
// クライアントはこのURLに PUT リクエストでファイルを直接送信する
echo json_encode(['upload_url' => $presignedUrl]);

Diretrizes para seleção de arquitetura

• <strong>~10 MB</strong>：implementação simples com API Gateway → Lambda → S3
• <strong>10 MB até 100 MB</strong>: Recomenda-se upload direto do cliente para S3 usando Presigned URL
• <strong>100 MB até 5 GB</strong>: Presigned URL + upload multipart para transferência estável
• <strong>Acima de 5 GB</strong>: Upload multipart obrigatório (PUT sozinho não funciona)

Procedimento de teste usando arquivos de limite do DevLab

Para validar as configurações de upload do S3 na prática, é necessário um arquivo de teste com tamanho exato. Usando os arquivos de teste de valor limite do DevLab, você pode verificar eficientemente o comportamento antes e depois de tamanhos específicos.

1. Baixe o arquivo do tamanho desejado para teste a partir da <a href="/ja/files/threshold/">lista de arquivos para teste de valor limite</a> do DevLab.
2. Ao validar a linha de alternância multipart, você também pode usar a versão de tamanho grande da <a href="/ja/files/images/png/">imagem de teste PNG</a>.
3. Faça upload do arquivo baixado usando o comando <code>aws s3 cp</code> ou as APIs <code>PutObject</code> / <code>MultipartUploader</code> do SDK e verifique o sucesso/falha em arquivos próximos ao limite.