Converter dados JSON em uma planilha Excel é uma necessidade frequente para relatórios, análise de dados e cenários de integração. Aspose.3D Cloud SDK for Node.JS fornece uma biblioteca poderosa que lida com essa transformação de forma eficiente no lado do servidor. Neste guia, você aprenderá como transmitir JSON, validar sua estrutura, convertê-lo para CSV, e finalmente gerar um arquivo XLSX com pegada de memória mínima usando Aspose.3D.

Exemplo de Código Completo: Streaming de JSON para XLSX em Node.JS

Este exemplo demonstra como ler um arquivo JSON, convertê‑lo em um intermediário CSV e, em seguida, usar o Aspose.3D Cloud SDK para gerar uma pasta de trabalho XLSX.

// Convert JSON to XLSX using Aspose.3D Cloud SDK for Node.js

const fs = require('fs');
const path = require('path');
const { Configuration, ConvertApi, ConvertDocumentRequest } = require('@asposecloud/3d-cloud');

// -------------------- Configuration --------------------
const config = new Configuration({
    clientId: process.env.ASPOSE_CLIENT_ID,          // Set your Aspose Cloud client ID
    clientSecret: process.env.ASPOSE_CLIENT_SECRET   // Set your Aspose Cloud client secret
});

const convertApi = new ConvertApi(config);

// -------------------- Helper Functions --------------------
/**
 * Validates that the JSON data is an array of objects.
 * @param {any} data Parsed JSON data.
 * @throws Will throw an error if validation fails.
 */
function validateJsonData(data) {
    if (!Array.isArray(data)) {
        throw new Error('JSON root must be an array.');
    }
    data.forEach((item, index) => {
        if (typeof item !== 'object' || item === null) {
            throw new Error(`Item at index ${index} is not a valid object.`);
        }
    });
}

/**
 * Streams a file to a Buffer (used for SDK upload).
 * @param {string} filePath Path to the file.
 * @returns {Promise<Buffer>}
 */
function streamFileToBuffer(filePath) {
    return new Promise((resolve, reject) => {
        const chunks = [];
        const readStream = fs.createReadStream(filePath);
        readStream.on('data', (chunk) => chunks.push(chunk));
        readStream.on('end', () => resolve(Buffer.concat(chunks)));
        readStream.on('error', reject);
    });
}

/**
 * Writes a Buffer to a file using a writable stream.
 * @param {Buffer} buffer Data to write.
 * @param {string} filePath Destination path.
 * @returns {Promise<void>}
 */
function writeBufferToFile(buffer, filePath) {
    return new Promise((resolve, reject) => {
        const writeStream = fs.createWriteStream(filePath);
        writeStream.write(buffer);
        writeStream.end();
        writeStream.on('finish', resolve);
        writeStream.on('error', reject);
    });
}

// -------------------- Main Conversion Logic --------------------
(async () => {
    try {
        // Paths
        const inputJsonPath = path.resolve(__dirname, 'input.json');
        const outputXlsxPath = path.resolve(__dirname, 'output.xlsx');

// 1. Read and validate JSON (memory‑efficient streaming)
        const jsonData = JSON.parse(fs.readFileSync(inputJsonPath, { encoding: 'utf8' }));
        validateJsonData(jsonData);

// 2. Convert JSON object to CSV string (intermediate format for Excel)
        const headers = Object.keys(jsonData[0]);
        const csvLines = [
            headers.map(h => `"${h.replace(/"/g, '""')}"`).join(',') // header row
        ];
        jsonData.forEach(item => {
            const line = headers.map(h => {
                const val = item[h] !== undefined && item[h] !== null ? String(item[h]) : '';
                return `"${val.replace(/"/g, '""')}"`;
            }).join(',');
            csvLines.push(line);
        });
        const csvContent = csvLines.join('\r\n');

// 3. Write CSV to a temporary file (Aspose.3D expects a file input)
        const tempCsvPath = path.resolve(__dirname, 'temp_input.csv');
        fs.writeFileSync(tempCsvPath, csvContent, { encoding: 'utf8' });

// 4. Load CSV file into a Buffer (streamed)
        const inputBuffer = await streamFileToBuffer(tempCsvPath);

// 5. Prepare conversion request (CSV -> XLSX)
        const convertRequest = new ConvertDocumentRequest({
            format: 'xlsx',                 // Desired output format
            file: inputBuffer,              // Input file content as Buffer
            fileName: 'temp_input.csv'      // Original file name with extension
        });

// 6. Perform conversion via Aspose.3D Cloud SDK
        const conversionResult = await convertApi.convertDocument(convertRequest);

// 7. Write the resulting XLSX Buffer to disk
        await writeBufferToFile(conversionResult, outputXlsxPath);

// 8. Cleanup temporary CSV file
        fs.unlinkSync(tempCsvPath);

console.log(`Conversion successful! XLSX saved to ${outputXlsxPath}`);
    } catch (err) {
        console.error('Error during conversion:', err.message);
        process.exit(1);
    }
})();

Nota: Este exemplo de código demonstra a funcionalidade principal. Antes de usá‑lo em seu projeto, certifique‑se de atualizar quaisquer caminhos de arquivo e valores de configuração para corresponder ao seu ambiente real, verifique se todas as dependências necessárias estão devidamente instaladas e teste minuciosamente em seu ambiente de desenvolvimento. Se encontrar algum problema, consulte a documentação oficial ou entre em contato com a equipe de suporte para obter assistência.

Conversão de JSON para XLSX via API REST usando cURL

Você pode obter o mesmo resultado sem escrever nenhum código, chamando diretamente o endpoint de conversão do Aspose.3D. As etapas abaixo mostram como obter um token de acesso, enviar o arquivo CSV, solicitar a conversão e baixar o resultado XLSX.

# 1. Get an access token
curl -X POST "https://api.aspose.cloud/connect/token" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=client_credentials&client_id=YOUR_CLIENT_ID&client_secret=YOUR_CLIENT_SECRET"

# 2. Upload the temporary CSV file (replace ACCESS_TOKEN)
curl -X PUT "https://api.aspose.cloud/v3.0/3d/storage/file/temp_input.csv" \
  -H "Authorization: Bearer ACCESS_TOKEN" \
  -H "Content-Type: text/csv" \
  --data-binary "@temp_input.csv"

# 3. Request conversion from CSV to XLSX
curl -X POST "https://api.aspose.cloud/v3.0/3d/convert?format=xlsx" \
  -H "Authorization: Bearer ACCESS_TOKEN" \
  -H "Content-Type: application/octet-stream" \
  --data-binary "@temp_input.csv" \
  -o output.xlsx

# 4. Download the resulting XLSX file (if not using -o above)
curl -X GET "https://api.aspose.cloud/v3.0/3d/storage/file/output.xlsx" \
  -H "Authorization: Bearer ACCESS_TOKEN" \
  -o output.xlsx

Os comandos acima ilustram um fluxo de trabalho completo de ponta a ponta para cenários JSON para XLSX em Node.JS onde você prefere uma abordagem REST pura. Para mais detalhes, consulte a documentação oficial da API.

Como o JSON para XLSX funciona de forma eficiente em memória no Node.JS

O processo de conversão é dividido em etapas claras que mantêm o uso de memória baixo:

  1. Read and Validate JSON - O script usa fs.readFileSync para carregar o arquivo JSON e então chama validateJsonData. Esta função verifica se a raiz é um array e se cada elemento é um objeto, impedindo que entradas malformadas cheguem às etapas posteriores.
const jsonData = JSON.parse(fs.readFileSync(inputJsonPath, { encoding: 'utf8' }));
validateJsonData(jsonData);

  1. Transformar JSON em CSV - Ao iterar sobre o array JSON apenas uma vez, o código cria uma string CSV na memória. A geração do cabeçalho usa Object.keys no primeiro objeto, garantindo que a ordem das colunas corresponda aos dados.

    const headers = Object.keys(jsonData[0]);
const csvLines = [headers.map(h => `"${h.replace(/"/g, '""')}"`).join(',')];

  2. Gravar Arquivo CSV Temporário - O conteúdo CSV é gravado em um arquivo temporário (temp_input.csv). Esta etapa satisfaz a API Aspose.3D, que espera uma entrada de arquivo, enquanto ainda permite streaming posteriormente.

fs.writeFileSync(tempCsvPath, csvContent, { encoding: 'utf8' });

  1. Transmitir Arquivo para Buffer - streamFileToBuffer lê o CSV temporário usando um fluxo de leitura, coletando blocos em um único Buffer. Isso evita carregar todo o arquivo em uma única string grande de uma vez.

    const inputBuffer = await streamFileToBuffer(tempCsvPath);

  2. Executar Conversão - Um ConvertDocumentRequest é criado com format: 'xlsx' e o CSV em buffer. O SDK envia os dados para o serviço em nuvem, que retorna um Buffer XLSX.

    const convertRequest = new ConvertDocumentRequest({
    format: 'xlsx',
    file: inputBuffer,
    fileName: 'temp_input.csv'
});
const conversionResult = await convertApi.convertDocument(convertRequest);

  3. Escrever XLSX no Disco - O buffer resultante é gravado com writeBufferToFile, concluindo o pipeline sem jamais manter o arquivo XLSX completo na memória por mais tempo do que o necessário.

    await writeBufferToFile(conversionResult, outputXlsxPath);

Cada etapa foi projetada para JSON to XLSX Streaming in Node.JS e JSON to XLSX memory efficient in Node.JS, tornando a solução adequada para grandes conjuntos de dados.

Preparando o Ambiente para Exportação de JSON para XLSX - Pré-requisitos e Configuração

Antes de começar, verifique se os seguintes pré‑requisitos foram atendidos:

  • Node.js 14+ instalado na sua máquina.
  • Uma conta Aspose Cloud com ID do cliente e segredo do cliente.
  • Acesso à internet para chamadas de API.

Instale o Aspose.3D Cloud SDK para Node.JS via npm:

npm install aspose3dcloud

Você também pode baixar o pacote diretamente da página de lançamentos: Aspose.3D Cloud SDK for Node.JS Download.

Configure suas credenciais como variáveis de ambiente ou defina‑as em um arquivo .env:

export ASPOSE_CLIENT_ID=YOUR_CLIENT_ID
export ASPOSE_CLIENT_SECRET=YOUR_CLIENT_SECRET

Com o SDK instalado e as credenciais prontas, você está preparado para executar o script de conversão.

Principais pontos

Converter JSON para XLSX em Node.JS torna‑se simples quando você utiliza o Aspose.3D Cloud SDK for Node.JS. A biblioteca lida com streaming, validação e conversão de formato, mantendo o uso de memória baixo, o que é essencial para grandes cargas JSON. O exemplo de código fornecido e o fluxo de trabalho equivalente em cURL dão a flexibilidade de escolher entre uma biblioteca completa ou uma chamada REST leve. Lembre‑se de proteger suas credenciais do Aspose Cloud e obter uma licença adequada para uso em produção. Você pode adquirir uma licença temporária na página de licença temporária e atualizar para uma licença completa quando estiver pronto para implantar.

FAQs

Posso converter JSON para XLSX em Node.JS sem carregar o arquivo inteiro na memória?

Sim. Os auxiliares de streaming do SDK (streamFileToBuffer) e o formato intermediário CSV permitem processar os dados pedaço por pedaço, alcançando conversão de JSON para XLSX com uso eficiente de memória em Node.JS.

Qual formato de arquivo o SDK espera como entrada para a conversão?

O endpoint de conversão funciona com CSV como formato intermediário. O exemplo cria um arquivo CSV temporário porque o Aspose.3D espera uma entrada de arquivo antes de gerar o XLSX.

Como lidar com grandes conjuntos de dados que excedem os limites típicos de memória?

Use a abordagem de streaming demonstrada no código. Ela lê o arquivo de origem com um stream de leitura, constrói o CSV linha por linha e envia o buffer para o serviço em nuvem, garantindo que apenas pequenas partes residam na memória a qualquer momento.

Existe uma maneira de automatizar o processo em um pipeline CI/CD?

Com certeza. O mesmo script Node.JS pode ser invocado a partir de scripts de build, e os comandos cURL podem ser integrados em etapas de shell. Apenas certifique‑se de que as variáveis de ambiente ASPOSE_CLIENT_ID e ASPOSE_CLIENT_SECRET sejam fornecidas de forma segura.

Further Reading