Upload de Arquivos via Token Pré-assinado

Autenticação

Este endpoint requer autenticação. Inclua seu token Bearer no cabeçalho Authorization.

Authorization: Bearer SEU_TOKEN_AQUI

Parâmetros de Caminho

slug

string

required

O slug do schema para o qual você quer gerar o token de upload

Corpo da Requisição

minutes

integer

required

Número de minutos que a URL de upload deve ser válida (1-60 minutos)

Resposta

integer

Identificador único do token de upload gerado

upload_url

string

URL pré-assinada para upload direto de arquivos para o Oracle Cloud Storage

expires_at

string

Data e hora de expiração da URL de upload no formato ISO 8601

success

boolean

Indica se o token foi gerado com sucesso

Processo de Upload

Após gerar o token, você receberá uma upload_url que deve ser usada para fazer o upload direto do arquivo via HTTP PUT.

Etapa 1: Gerar Token

Use este endpoint para obter URL pré-assinada

Etapa 2: Fazer Upload

Use a URL retornada com método PUT para upload

Segurança

URLs expiram automaticamente (1-60 min)

Performance

Upload direto para Oracle Cloud Storage

Exemplo de Fluxo Completo

# 1. Gerar token (válido por 15 minutos)
TOKEN_RESPONSE=$(curl -X POST \
  "https://api.datasnap.com.br/api/v1/schemas/meu-schema/generate-upload-token" \
  -H "Authorization: Bearer SEU_TOKEN_AQUI" \
  -H "Content-Type: application/json" \
  -d '{"minutes": 15}')

# 2. Extrair URL de upload
UPLOAD_URL=$(echo $TOKEN_RESPONSE | jq -r '.upload_url')

# 3. Fazer upload direto via PUT
curl -X PUT \
  "${UPLOAD_URL}/dados.jsonl" \
  -H "Content-Type: application/octet-stream" \
  --data-binary "@dados.jsonl"

Como Usar

1. Gerar Token

curl -X POST \
  "https://api.datasnap.com.br/api/v1/schemas/meu-schema/generate-upload-token" \
  -H "Authorization: Bearer SEU_TOKEN_AQUI" \
  -H "Content-Type: application/json" \
  -d '{"minutes": 15}'

Resposta:

{
  "id": 8,
  "upload_url": "{pre_signed_url}",
  "expires_at": "2025-10-03T03:29:08.000000Z",
  "success": true
}

2. Fazer Upload

Use a upload_url retornada como prefixo e adicione o nome do arquivo:

curl -X PUT \
  "{pre_signed_url}/dados.jsonl" \
  -H "Content-Type: application/octet-stream" \
  --data-binary "@dados.jsonl"

Regras importantes:

A URL de upload expira automaticamente após o horário em expires_at
Cada arquivo deve ter um nome único incluído na URL
Sempre use a extensão .jsonl no nome do arquivo
Após a expiração, você deve gerar um novo token
Tamanho máximo: 10MB por arquivo para melhor experiência
Sempre use a extensão .jsonl no nome do arquivo

Requisitos de Formato de Arquivo

Os arquivos devem estar no formato JSONL (JSON Lines) onde cada linha contém um objeto JSON válido.

Exemplo JSONL Válido

{"nome": "João Silva", "idade": 30, "cidade": "São Paulo"}
{"nome": "Maria Santos", "idade": 25, "cidade": "Rio de Janeiro"}
{"nome": "Carlos Oliveira", "idade": 35, "cidade": "Belo Horizonte"}

Exemplos Inválidos

// Inválido - JSON incorreto
{nome: "João", idade: 30}

// Inválido - múltiplos objetos em uma linha
{"nome": "João"} {"idade": 30}

// Inválido - formato array em vez de linha por linha
[{"nome": "João"}, {"nome": "Maria"}]

Validação de Token

minutes

integer

O valor deve estar entre 1 e 60 minutos

Códigos de Erro

200

Success

Token gerado com sucesso

401

Error

Não autorizado - Token de autenticação inválido ou ausente

422

Error

Erro de validação - Valor de minutes inválido (deve estar entre 1 e 60)

Exemplos Completos

# 1. Criar arquivo JSONL de exemplo
echo '{"produto": "Notebook", "preco": 2500.00, "categoria": "Eletrônicos"}
{"produto": "Mouse", "preco": 50.00, "categoria": "Periféricos"}
{"produto": "Teclado", "preco": 120.00, "categoria": "Periféricos"}' > produtos.jsonl

# 2. Gerar token de upload (válido por 15 minutos)
TOKEN_RESPONSE=$(curl -X POST \
  "https://api.datasnap.com.br/api/v1/schemas/meu-schema/generate-upload-token" \
  -H "Authorization: Bearer SEU_TOKEN_AQUI" \
  -H "Content-Type: application/json" \
  -d '{"minutes": 15}')

echo "Token gerado:"
echo $TOKEN_RESPONSE | jq '.'

# 3. Extrair URL de upload
UPLOAD_URL=$(echo $TOKEN_RESPONSE | jq -r '.upload_url')

# 4. Fazer upload direto via PUT
echo "Fazendo upload..."
curl -X PUT \
  "${UPLOAD_URL}/produtos.jsonl" \
  -H "Content-Type: application/octet-stream" \
  --data-binary "@produtos.jsonl"

echo "Upload concluído!"

Boas Práticas

Gere tokens apenas quando necessário - Evite expiração desnecessária
Monitore o horário de expiração - Gere novos tokens antes que expirem
Use nomes descritivos para arquivos - Facilita organização e consulta posterior
Valide o formato JSONL localmente - Evite uploads com erro de formato
Mantenha arquivos abaixo de 10MB - Para melhor performance e experiência

URLs de upload expiram automaticamente - Complete o upload antes da expiração
Não compartilhe URLs de upload - São temporárias e específicas para seu uso
Cada arquivo precisa de nome único - Evite conflitos na URL de upload

Processo de Upload Completo

Preparar Arquivo

Crie ou valide seu arquivo no formato JSONL (um objeto JSON por linha)

Gerar Token

Use este endpoint para obter uma URL pré-assinada com expiração

Fazer Upload

Use a URL retornada com método HTTP PUT para enviar o arquivo

Confirmar Sucesso

Verifique se o upload foi concluído (código HTTP 200)

Consultar Dados

Use o endpoint de consultas para analisar os dados processados

Características Técnicas

Aspecto	Detalhes	Recomendações
Método de Upload	PUT direto na URL pré-assinada	Sempre use PUT, não POST
Tamanho de Arquivo	Sem limite prático	Divida arquivos >500MB
Expiração da URL	1-60 minutos configuráveis	Use 15 minutos para arquivos médios
Formato Obrigatório	JSONL (JSON Lines)	Uma linha = um objeto JSON
Processamento	Totalmente assíncrono	Arquivos ficam disponíveis após processamento

Próximos Passos

Após o upload bem-sucedido:

✅ Upload concluído - Arquivo enviado para Oracle Cloud Storage
🔄 Processamento em background - Dados sendo preparados para consulta
📊 Consulta disponível - Use endpoint de consultas para analisar dados
📁 Listar arquivos - Monitore status através do endpoint de listagem

Fluxo de Trabalho Visual

Arquivo JSONL → Gerar Token → Upload PUT → Processamento → Consulta
     ↓              ↓             ↓           ↓           ↓
  Validar      URL temporária  Oracle Cloud  Background  Dados
  formato       com expiração   Storage      Processing  Disponíveis

Endpoints Relacionados

Executar Consultas - Consultar dados enviados
Listar Arquivos - Gerenciar arquivos enviados

Documentação da API

Endpoints

​Autenticação

​Parâmetros de Caminho

​Corpo da Requisição

​Resposta

​Processo de Upload

Etapa 1: Gerar Token

Etapa 2: Fazer Upload

Segurança

Performance

​Exemplo de Fluxo Completo

​Como Usar

​1. Gerar Token

​2. Fazer Upload

​Requisitos de Formato de Arquivo

​Exemplo JSONL Válido

​Exemplos Inválidos

​Validação de Token

​Códigos de Erro

​Exemplos Completos

​Boas Práticas

​Processo de Upload Completo

​Características Técnicas

​Próximos Passos

​Fluxo de Trabalho Visual

​Endpoints Relacionados

Autenticação

Parâmetros de Caminho

Corpo da Requisição

Resposta

Processo de Upload

Exemplo de Fluxo Completo

Como Usar

1. Gerar Token

2. Fazer Upload

Requisitos de Formato de Arquivo

Exemplo JSONL Válido

Exemplos Inválidos

Validação de Token

Códigos de Erro

Exemplos Completos

Boas Práticas

Processo de Upload Completo

Características Técnicas

Próximos Passos

Fluxo de Trabalho Visual

Endpoints Relacionados