Upload de Arquivo Grande
Envie arquivos de até 200 MB. O cliente faz upload do corpo do arquivo diretamente para o Google Cloud Storage usando uma URL PUT assinada de curta duração, e depois registra o upload na API.
Como funciona
O corpo do arquivo é enviado diretamente do cliente para o Google Cloud Storage usando uma URL PUT assinada V4 de curta duração — os bytes nunca passam pelo servidor da API, o que permite que o endpoint aceite arquivos de até 200 MB. Um único upload são três chamadas do cliente:POST /v2/files/sign— a API gera uma URL PUT assinada para o GCS válida por ~15 minutos e retorna os headers que o cliente deve repetir no PUT.PUTdo corpo do arquivo diretamente para auploadUrlretornada. O PUT carrega exatamente os headers derequiredHeaders— nem mais, nem menos — eles estão vinculados à assinatura V4, então um header faltando, extra ou diferente faz o GCS rejeitar o PUT com403.POST /v2/files/register— a API verifica o tamanho do objeto enviado contra o que você declarou no/sign, move-o server-side da área de staging temporária para o local final, faz deduplicação por hash de conteúdo, e retorna oFileDTOpadrão (mesmo formato de POST /files).
Etapa 2 — PUT direto para o Google Cloud Storage
Envie exatamente os headers retornados emrequiredHeaders (atualmente Content-Type e x-goog-if-generation-match):
200 em caso de sucesso. O header x-goog-if-generation-match: 0 torna o PUT create-only — re-execuções retornam 412 Precondition Failed.
Etapa 3 — registrar o upload
Após o PUT ser bem-sucedido, finalize o upload. O tamanho declarado não precisa ser enviado de novo — o servidor lembra osize que você declarou no /sign (por ~16 minutos) e o compara com o objeto realmente enviado:
201 com o FileDTO padrão. Se um arquivo com conteúdo idêntico já existir no workspace, a API retorna 200 com o FileDTO do arquivo existente em vez de criar uma duplicata. O campo opcional process funciona exatamente como em POST /files.
Arquivos suportados
Os mesmos de POST /files — Texto, Word, Planilha, PDF, Excel, PowerPoint, Imagem, Vídeo, Áudio e mais de 30 extensões de código.Limites
- Tamanho máximo por upload: 200 MB
- Um arquivo por fluxo (execute as três etapas novamente para arquivos adicionais)
- Limite de armazenamento: 30 arquivos
Erros
| Status | Significado |
|---|---|
400 | Validação do /register falhou (campo ausente ou object_path mal formado) |
401 | Token Bearer ausente ou inválido |
403 | Caller não tem permissão de API para o workspace alvo — ou, no PUT do GCS, os headers não correspondem a requiredHeaders |
404 | Sessão de upload expirada (janela de ~15 minutos) ou desconhecida, ou o objeto nunca foi enviado — recomece pelo /sign |
412 | No PUT do GCS: o objeto já existe (a URL assinada é create-only) |
415 | content_type não suportado no /register |
422 | Validação do /sign falhou (campo ausente ou size > 200 MB) — ou o objeto enviado é maior que o tamanho declarado no /sign (o objeto é excluído) |
429 | Throttled |
Autorizações
Bearer authentication header of the form Bearer <token>, where <token> is your auth token.
Cabeçalhos
ID of the workspace. If not provided, the user's selected workspace will be used.
Corpo
Original filename including extension (e.g. report.pdf). Used to derive the stored extension.
MIME type of the file. Bound into the signed URL - the client MUST PUT with exactly this Content-Type header.
Declared file size in bytes. The server remembers this value and /register rejects the upload if the actual uploaded object is larger than declared. Hard maximum: 200 MB (209715200 bytes).
Resposta
Signed PUT URL minted.
Pre-signed Google Cloud Storage PUT URL. Valid for ~15 minutes.
GCS object path the file will land at. Pass this back to POST /v2/files/register.
Headers the client MUST send on the PUT - bound into the V4 signature. Contains exactly Content-Type (the value you declared) and x-goog-if-generation-match: 0 (create-only). Send these headers verbatim and do not add others.
Short-lived signed download URL (~3 hours) for the uploaded object. For a durable reference, use the url field of the FileDTO returned by POST /v2/files/register.