Armazenamento e Gerenciamento de Arquivos

Armazene, organize e recupere arquivos nos buckets do GFile Plus.

Upload e organização de arquivos em buckets

Armazene qualquer tipo de arquivo — imagens, vídeos, documentos, arquivos compactados — organizados em buckets e pastas.

Método 1: Upload direto

Faça upload de um arquivo diretamente usando dados multipart.

curl -X POST "/api/v1/tenants/:tenantId/buckets/:bucketId/files/upload?apiKey=<your-api-key>" \
  -F "file=@./minha-foto.jpg" \
  -F 'body={"name":"minha-foto.jpg","path":"/fotos/"}'

Método 2: Criar registro e depois fazer upload do binário

Primeiro crie um registro de arquivo no bucket, depois faça upload do conteúdo binário separadamente. Essa abordagem reserva a entrada do arquivo primeiro, permitindo ao usuário fazer upload do conteúdo depois (por exemplo, via formulário).

Passo 1 — Criar o registro do arquivo:

curl -X POST "/api/v1/tenants/:tenantId/buckets/:bucketId/files?apiKey=<your-api-key>" \
  -H "Content-Type: application/json" \
  -d '{"name": "minha-foto.jpg", "path": "/fotos/"}'

A resposta inclui o id do arquivo:

{
  "id": "<file-id>",
  "name": "minha-foto.jpg",
  "path": "/fotos/"
}

Passo 2 — Fazer upload do conteúdo binário:

curl -X POST "/api/v1/tenants/:tenantId/buckets/:bucketId/files/<file-id>/reupload?apiKey=<your-api-key>" \
  -H "Content-Type: application/octet-stream" \
  --data-binary @./minha-foto.jpg

Use o id da resposta do Passo 1 como :fileId na URL de reupload.

Tipos de arquivo suportados:

Categoria	Extensões
Imagens	jpg, png, gif, webp, svg, bmp, ico, tiff
Vídeos	mp4, avi, mov, mkv, webm, flv, wmv
Áudio	mp3, wav, ogg, flac, aac
Documentos	pdf, doc, docx
Planilhas	xls, xlsx, csv
Apresentações	ppt, pptx
Arquivos compactados	zip, tar, gz, rar, 7z
Fontes	ttf, otf, woff, woff2
Arquivos de texto	txt, md, json, xml, yaml, html, css, js

Download e visualização de arquivos

Recupere o conteúdo de arquivos para visualização inline ou como download.

# Ver arquivo inline (exibição no navegador)
curl "/api/v1/tenants/:tenantId/buckets/:bucketId/files/:fileId/view?apiKey=<your-api-key>"

# Download de arquivo como anexo
curl "/api/v1/tenants/:tenantId/buckets/:bucketId/files/:fileId/download?apiKey=<your-api-key>" \
  -o arquivo-saida.jpg

Downloads parciais com requisições de intervalo

Baixe intervalos de bytes específicos para arquivos grandes — útil para downloads resumíveis ou seeking em mídia.

# Download dos bytes 0-1023 (primeiro 1KB)
curl "/api/v1/tenants/:tenantId/buckets/:bucketId/files/:fileId/view?apiKey=<your-api-key>" \
  -H "Range: bytes=0-1023"

A resposta inclui os cabeçalhos Content-Range e Accept-Ranges: bytes.

Substituir conteúdo do arquivo sem alterar metadados

Re-faça upload do conteúdo binário de um arquivo preservando seu ID, cabeçalhos, alias e metadados.

# Re-upload do conteúdo do arquivo
curl -X POST "/api/v1/tenants/:tenantId/buckets/:bucketId/files/:fileId/reupload?apiKey=<your-api-key>" \
  -H "Content-Type: application/octet-stream" \
  --data-binary @./arquivo-atualizado.jpg

Obter informações de tamanho e tipo do arquivo

Expanda os metadados do arquivo para incluir tamanho calculado (legível) e tipo de arquivo detectado.

# Obter arquivo com informações de tamanho e tipo
curl "/api/v1/tenants/:tenantId/buckets/:bucketId/files/:fileId?expands=SIZE&expands=TYPE&apiKey=<your-api-key>"

A resposta inclui:

{
  "expands": {
    "size": { "bytes": 2048576, "human": "2 MB" },
    "type": { "type": "IMAGE" }
  }
}