SDK JavaScript para ingestão de dados modulares no Forge, permitindo que aplicações frontend enviem dados para datasets específicos.
npm install forge-sdkyarn add forge-sdk<script src="https://cdn.exemplo.com/forge-sdk.umd.js"></script>
<script>
// SDK disponível globalmente como 'ForgeSDK'
const forge = ForgeSDK.default;
</script>Para começar a usar o SDK, você precisa inicializá-lo com sua chave API:
import { forge } from 'forge-sdk';
forge.init({
apiUrl: 'https://api.exemplo.com', // URL base da API Forge
apiKey: 'sk_forge_sua_chave_api', // Sua chave API (obtida no painel administrativo)
timeout: 30000, // Timeout em ms (opcional, padrão: 30000)
debug: false // Modo debug (opcional, padrão: false)
});O SDK permite enviar dados para datasets específicos que foram definidos no painel administrativo:
// Envio básico de dados
try {
const resposta = await forge.sendData('nomeDoDataset', {
// Os dados seguem a estrutura definida pelo seu dataset
campo1: 'valor1',
campo2: 'valor2',
campoNumerico: 123,
objetoAninhado: {
subcampo: 'valor'
},
lista: [1, 2, 3]
});
if (resposta.success) {
console.log(`Dados enviados com sucesso! ID: ${resposta.recordId}`);
}
} catch (erro) {
console.error('Falha ao enviar dados:', erro.message);
}Você pode configurar metadados adicionais e comportamento de retentativas:
const opcoes = {
// Zona do data lake (ex.: "landing", "raw", "silver")
targetZone: 'landing',
// Formato de arquivo: 'json' (padrão), 'parquet', 'csv' ou 'avro'
targetFormat: 'csv',
// (Somente quando targetFormat === 'avro') — esquema Avro opcional
avro_schema: {
name: 'Pessoa',
type: 'record',
fields: [
{ name: 'nome', type: 'string' },
{ name: 'idade', type: 'int' }
]
},
metadata: {
source: 'app-web',
sessionId: 'abc123',
userAgent: navigator.userAgent,
},
retry: true,
maxRetries: 3,
};
// Envio dos dados usando as opções acima
const resposta = await forge.sendData('nomeDoDataset', dados, opcoes);O método uploadFile permite enviar arquivos binários (CSV, JSON, Parquet, Avro, imagens etc.) usando multipart/form-data.
// Selecionar um arquivo de um <input type="file"/>
const input = document.querySelector('#fileInput');
const arquivo = input.files[0];
const opcoes = {
targetZone: 'landing', // (opcional) zona no data lake
metadata: {
description: 'Importação inicial',
tags: ['csv', 'financeiro']
}
};
try {
const resposta = await forge.uploadFile('projetos', arquivo, opcoes);
if (resposta.success) {
console.log('Arquivo carregado! ID:', resposta.recordId);
}
} catch (erro) {
console.error('Falha no upload:', erro.message);
}Em Node.js o file pode ser um fs.ReadStream:
import fs from 'fs';
const stream = fs.createReadStream('./dados.csv');
await forge.uploadFile('projetos', stream, { targetZone: 'landing' });Verifique se a API do Forge está operacional:
try {
const saude = await forge.checkHealth();
console.log(`Status da API: ${saude.status}`);
} catch (erro) {
console.error('API indisponível:', erro.message);
}Obtenha informações sobre o estado atual do SDK:
const status = forge.getStatus();
console.log(`SDK inicializado: ${status.initialized}`);
console.log(`Versão do SDK: ${status.sdkVersion}`);O SDK possui tratamento de erros robusto:
try {
await forge.sendData('nomeDoDataset', dados);
} catch (erro) {
if (erro.message.includes('Autenticação falhou')) {
// Problema com a chave API
console.error('Chave API inválida ou expirada');
} else if (erro.message.includes('Muitas requisições')) {
// Rate limiting
console.error('Limite de taxa excedido, tente novamente mais tarde');
} else {
// Outros erros
console.error('Erro ao enviar dados:', erro.message);
}
}Exemplo de integração com um formulário HTML:
document.getElementById('formularioContato').addEventListener('submit', async (evento) => {
evento.preventDefault();
const form = evento.target;
const botaoEnviar = form.querySelector('button[type="submit"]');
const mensagemStatus = form.querySelector('.status-mensagem');
// Desabilitar botão durante o envio
botaoEnviar.disabled = true;
mensagemStatus.textContent = 'Enviando...';
try {
// Coletar dados do formulário
const formData = new FormData(form);
const dados = Object.fromEntries(formData.entries());
// Enviar para o dataset 'contatos'
const resposta = await forge.sendData('contatos', dados);
if (resposta.success) {
form.reset();
mensagemStatus.textContent = 'Mensagem enviada com sucesso!';
mensagemStatus.classList.add('sucesso');
} else {
mensagemStatus.textContent = 'Falha ao enviar mensagem: ' + (resposta.errors?.[0] || 'Erro desconhecido');
mensagemStatus.classList.add('erro');
}
} catch (erro) {
mensagemStatus.textContent = 'Erro: ' + erro.message;
mensagemStatus.classList.add('erro');
} finally {
botaoEnviar.disabled = false;
}
});O SDK é compatível com:
- Navegadores modernos (Chrome, Firefox, Safari, Edge)
- Node.js 12+
- React, Vue, Angular e outros frameworks frontend
- Vanilla JavaScript
O SDK possui suporte completo a TypeScript com tipos exportados:
import { forge, ForgeConfig, DataIngestionResponse } from 'forge-sdk';
// Configuração tipada
const config: ForgeConfig = {
apiUrl: 'api_url',
apiKey: 'sk_forge_sua_chave_api',
};
forge.init(config);
// Uso com tipagem
async function enviarDados(): Promise<DataIngestionResponse> {
return await forge.sendData('clientes', { nome: 'João' });
}MIT