تبدیل داده‌های JSON به یک صفحه‌گسترده Excel یک نیاز مکرر برای گزارش‌گیری، تجزیه و تحلیل داده‌ها و سناریوهای یکپارچه‌سازی است. Aspose.3D Cloud SDK for Node.JS یک کتابخانه قدرتمند فراهم می‌کند که این تبدیل را به‌صورت کارآمد در سمت سرور انجام می‌دهد. در این راهنما شما یاد خواهید گرفت چگونه JSON را به‌صورت جریان پردازش کنید، ساختار آن را اعتبارسنجی کنید، به CSV تبدیل کنید و در نهایت با استفاده از Aspose.3D یک فایل XLSX با مصرف حافظه کم تولید کنید.

مثال کامل کد: استریم JSON به XLSX در Node.JS

این مثال نشان می‌دهد که چگونه یک فایل JSON را بخوانید، آن را به یک فایل میانی CSV تبدیل کنید، و سپس از Aspose.3D Cloud SDK برای تولید یک کتاب‌کار 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);
    }
})();

توجه: این مثال کد عملکرد اصلی را نشان می‌دهد. قبل از استفاده از آن در پروژه خود، اطمینان حاصل کنید که مسیرهای فایل و مقادیر پیکربندی را به‌گونه‌ای به‌روز کنید که با محیط واقعی شما مطابقت داشته باشد، بررسی کنید که تمام وابستگی‌های مورد نیاز به‌درستی نصب شده‌اند و به‌طور کامل در محیط توسعه خود تست کنید. اگر با مشکلی مواجه شدید، لطفاً به مستندات رسمی مراجعه کنید یا برای دریافت کمک به تیم پشتیبانی مراجعه نمایید.

تبدیل JSON به XLSX از طریق REST API با استفاده از cURL

می‌توانید بدون نوشتن هیچ کدی، با فراخوانی مستقیم نقطهٔ انتهایی تبدیل Aspose.3D همان نتیجه را به دست آورید. مراحل زیر نشان می‌دهند چگونه یک توکن دسترسی دریافت کنید، فایل CSV را بارگذاری کنید، درخواست تبدیل را ارسال کنید و خروجی 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

دستورات فوق یک جریان کاری کامل از ابتدا تا انتها برای JSON to XLSX in Node.JS را نشان می‌دهند که در آن ترجیح می‌دهید از رویکرد صرفاً REST استفاده کنید. برای جزئیات بیشتر، به official API documentation مراجعه کنید.

چگونه تبدیل JSON به XLSX به صورت حافظه‌کارآمد در Node.JS کار می‌کند

فرآیند تبدیل به مراحل واضحی تقسیم می‌شود که مصرف حافظه را کم نگه می‌دارند:

  1. خواندن و اعتبارسنجی JSON - اسکریپت از fs.readFileSync برای بارگذاری فایل JSON استفاده می‌کند و سپس validateJsonData را فراخوانی می‌کند. این تابع بررسی می‌کند که ریشه یک آرایه باشد و هر عنصر یک شیء باشد، تا از ورود ورودی‌های خراب به مراحل بعدی جلوگیری شود.
const jsonData = JSON.parse(fs.readFileSync(inputJsonPath, { encoding: 'utf8' }));
validateJsonData(jsonData);
  1. تبدیل JSON به CSV - با تکرار تنها یک بار بر روی آرایه JSON، کد یک رشته CSV را در حافظه می‌سازد. تولید سرصفحه با استفاده از Object.keys بر روی اولین شیء انجام می‌شود و ترتیب ستون‌ها با داده‌ها مطابقت دارد.
const headers = Object.keys(jsonData[0]);
const csvLines = [headers.map(h => `"${h.replace(/"/g, '""')}"`).join(',')];
  1. نوشتن فایل CSV موقت - محتوای CSV در یک فایل موقت (temp_input.csv) نوشته می‌شود. این مرحله نیازهای Aspose.3D API را برآورده می‌کند، که انتظار ورودی فایل را دارد، در حالی که همچنان امکان استریم بعدی را فراهم می‌کند.
fs.writeFileSync(tempCsvPath, csvContent, { encoding: 'utf8' });

  1. جریان‌گذاری فایل به بافر - streamFileToBuffer فایل CSV موقت را با استفاده از یک جریان خواندن می‌خواند و تکه‌ها را در یک Buffer واحد جمع می‌کند. این کار از بارگذاری کل فایل به یک رشته بزرگ به‌صورت یکجا جلوگیری می‌کند.

    const inputBuffer = await streamFileToBuffer(tempCsvPath);

  2. انجام تبدیل - یک ConvertDocumentRequest با format: 'xlsx' و CSV بافر شده ایجاد می‌شود. SDK داده‌ها را به سرویس ابری می‌فرستد که یک Buffer از نوع XLSX برمی‌گرداند.

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

  3. نوشتن XLSX به دیسک - بافر حاصل با استفاده از writeBufferToFile نوشته می‌شود، و این کار خط لوله را تکمیل می‌کند بدون اینکه فایل کامل XLSX را برای مدت طولانی‌تری در حافظه نگه دارد.

await writeBufferToFile(conversionResult, outputXlsxPath);

هر مرحله برای JSON به XLSX استریمینگ در Node.JS و JSON به XLSX با کارایی حافظه در Node.JS طراحی شده است، به‌طوری که راه‌حل برای مجموعه داده‌های بزرگ مناسب باشد.

آماده‌سازی محیط برای تبدیل JSON به XLSX - پیش‌نیازها و تنظیمات

قبل از شروع، مطمئن شوید که پیش‌نیازهای زیر برآورده شده‌اند:

  • Node.js 14+ نصب شده بر روی دستگاه شما.
  • یک حساب Aspose Cloud با client ID و client secret.
  • دسترسی به اینترنت برای فراخوانی‌های API.

نصب Aspose.3D Cloud SDK for Node.JS از طریق npm:

npm install aspose3dcloud

همچنین می‌توانید بسته را به‌صورت مستقیم از صفحه انتشار دانلود کنید: Aspose.3D Cloud SDK for Node.JS Download.

اعتبارهای خود را به‌عنوان متغیرهای محیطی پیکربندی کنید یا آن‌ها را در یک فایل .env تنظیم کنید:

export ASPOSE_CLIENT_ID=YOUR_CLIENT_ID
export ASPOSE_CLIENT_SECRET=YOUR_CLIENT_SECRET

با نصب SDK و آماده بودن اعتبارها، می‌توانید اسکریپت تبدیل را اجرا کنید.

نکات کلیدی

تبدیل JSON به XLSX در Node.JS زمانی که از Aspose.3D Cloud SDK for Node.JS استفاده کنید، ساده می‌شود. این کتابخانه جریان‌سازی، اعتبارسنجی و تبدیل فرمت را مدیریت می‌کند در حالی که مصرف حافظه را پایین نگه می‌دارد، که برای بارهای بزرگ JSON ضروری است. مثال کد ارائه‌شده و جریان کاری معادل cURL به شما انعطاف‌پذیری می‌دهند تا بین یک کتابخانه کامل‌ویژگی یا یک فراخوانی سبک REST انتخاب کنید. به‌خاطر داشته باشید که اعتبارنامه‌های Aspose Cloud خود را ایمن کنید و برای استفاده در محیط تولید یک مجوز مناسب دریافت کنید. می‌توانید یک مجوز موقت را از صفحه مجوز موقت دریافت کنید و زمانی که آماده استقرار هستید، به یک مجوز کامل ارتقا دهید.

سوالات متداول

آیا می‌توانم JSON را به XLSX در Node.JS تبدیل کنم بدون اینکه کل فایل را در حافظه بارگذاری کنم؟

بله. ابزارهای استریمینگ SDK (streamFileToBuffer) و فرمت میانی CSV به شما امکان می‌دهند داده‌ها را تکه به تکه پردازش کنید و تبدیل JSON به XLSX با کارایی حافظه در Node.JS را به دست آورید.

SDK برای تبدیل چه فرمت فایلی را به عنوان ورودی انتظار دارد؟

نقطهٔ تبدیل با CSV به عنوان فرمت میانی کار می‌کند. این مثال یک فایل CSV موقت ایجاد می‌کند زیرا Aspose.3D قبل از تولید XLSX انتظار ورودی فایل را دارد.

چگونه می‌توانم مجموعه داده‌های بزرگ که از محدودیت‌های معمول حافظه فراتر می‌روند را مدیریت کنم؟

از رویکرد استریمینگ نشان داده شده در کد استفاده کنید. این روش فایل منبع را با یک استریم خواندن می‌خواند، CSV را خط به خط می‌سازد و بافر را به سرویس ابری ارسال می‌کند، به‌طوری‌که در هر زمان تنها بخش‌های کوچکی در حافظه باقی می‌مانند.

آیا راهی برای خودکارسازی فرآیند در یک خط لوله CI/CD وجود دارد؟

به‌طور قطع. همان اسکریپت Node.JS می‌تواند از اسکریپت‌های ساخت فراخوانی شود و دستورات cURL می‌توانند در مراحل شل یکپارچه شوند. فقط مطمئن شوید که متغیرهای محیطی ASPOSE_CLIENT_ID و ASPOSE_CLIENT_SECRET به‌صورت ایمن فراهم شده‌اند.

مطالعه بیشتر