تحويل JSON إلى XLSX في Node.JS

تحويل بيانات JSON إلى جدول بيانات Excel هو طلب شائع للتقارير وتحليل البيانات وسيناريوهات التكامل. يوفر Aspose.3D Cloud SDK for Node.JS مكتبة قوية تتعامل مع هذا التحويل بكفاءة على جانب الخادم. في هذا الدليل ستتعلم كيفية تدفق JSON، والتحقق من هيكله، وتحويله إلى CSV، وأخيرًا إنشاء ملف XLSX بأقل استهلاك للذاكرة باستخدام Aspose.3D.

مثال كامل للكود: تحويل 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 إلى XLSX في Node.JS في السيناريوهات التي تفضل فيها نهج REST النقي. لمزيد من التفاصيل، راجع وثائق API الرسمية.

كيف يعمل تحويل JSON إلى XLSX بكفاءة الذاكرة في Node.JS

عملية التحويل مقسمة إلى مراحل واضحة تحافظ على انخفاض استهلاك الذاكرة:

قراءة والتحقق من صحة JSON - يستخدم البرنامج النصي fs.readFileSync لتحميل ملف JSON ثم يستدعي validateJsonData. تقوم هذه الدالة بالتحقق من أن الجذر هو مصفوفة وأن كل عنصر هو كائن، مما يمنع إدخال بيانات غير صحيحة من الوصول إلى المراحل اللاحقة.

const jsonData = JSON.parse(fs.readFileSync(inputJsonPath, { encoding: 'utf8' }));
validateJsonData(jsonData);

تحويل JSON إلى CSV - من خلال التكرار على مصفوفة JSON مرة واحدة فقط، يبني الكود سلسلة CSV في الذاكرة. يتم إنشاء العنوان باستخدام Object.keys على الكائن الأول، مما يضمن أن ترتيب الأعمدة يتطابق مع البيانات.
```
const headers = Object.keys(jsonData[0]);
const csvLines = [headers.map(h => `"${h.replace(/"/g, '""')}"`).join(',')];
```
اكتب ملف CSV مؤقت - يتم كتابة محتوى CSV إلى ملف مؤقت (temp_input.csv). هذه الخطوة تلبي متطلبات Aspose.3D API، الذي يتوقع إدخال ملف، مع الاستمرار في السماح بالبث لاحقًا.

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

Stream File to Buffer - streamFileToBuffer يقرأ ملف CSV المؤقت باستخدام تدفق قراءة، ويجمع القطع في Buffer واحد. هذا يمنع تحميل الملف بالكامل في سلسلة نصية كبيرة مرة واحدة.
```
const inputBuffer = await streamFileToBuffer(tempCsvPath);
```
إجراء التحويل - يتم إنشاء 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);
```
كتابة XLSX إلى القرص - يتم كتابة المخزن المؤقت الناتج باستخدام writeBufferToFile، مكتملًا خط الأنابيب دون الاحتفاظ بملف XLSX الكامل في الذاكرة لفترة أطول من اللازم.
```
await writeBufferToFile(conversionResult, outputXlsxPath);
```

كل خطوة مصممة لـ JSON to XLSX Streaming in Node.JS و JSON to XLSX memory efficient in Node.JS، مما يجعل الحل مناسبًا لمجموعات البيانات الكبيرة.

إعداد البيئة لتصدير JSON إلى XLSX - المتطلبات والإعداد

قبل أن تبدأ، تأكد من استيفاء المتطلبات المسبقة التالية:

تم تثبيت Node.js 14+ على جهازك.
حساب Aspose Cloud مع معرف العميل والسر الخاص بالعميل.
الوصول إلى الإنترنت لإجراء مكالمات 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 to XLSX memory efficient in Node.JS التحويل.

ما هو تنسيق الملف الذي يتوقعه SDK كإدخال للتحويل؟

نقطة النهاية للتحويل تعمل مع CSV كتنسيق وسيط. المثال ينشئ ملف CSV مؤقت لأن Aspose.3D يتوقع إدخال ملف قبل إنشاء XLSX.

كيف يمكنني التعامل مع مجموعات البيانات الكبيرة التي تتجاوز حدود الذاكرة المعتادة؟

استخدم نهج الـ streaming الموضح في الشيفرة. يقرأ ملف المصدر باستخدام read stream، يبني ملف CSV سطرًا بسطر، ويرسل الـ buffer إلى خدمة السحابة، مما يضمن بقاء أجزاء صغيرة فقط في الذاكرة في أي وقت.

هل هناك طريقة لأتمتة العملية في خط أنابيب CI/CD؟

بالطبع. يمكن استدعاء نفس برنامج Node.JS من سكريبتات البناء، ويمكن دمج أوامر cURL في خطوات الشل. فقط تأكد من توفير متغيرات البيئة ASPOSE_CLIENT_ID و ASPOSE_CLIENT_SECRET بأمان.

مثال كامل للكود: تحويل JSON إلى XLSX باستخدام البث في Node.JS#

تحويل JSON إلى XLSX عبر REST API باستخدام cURL#

كيف يعمل تحويل JSON إلى XLSX بكفاءة الذاكرة في Node.JS#

إعداد البيئة لتصدير JSON إلى XLSX - المتطلبات والإعداد#

النقاط الرئيسية#

الأسئلة الشائعة#

هل يمكنني تحويل JSON إلى XLSX في Node.JS دون تحميل الملف بالكامل في الذاكرة؟#

ما هو تنسيق الملف الذي يتوقعه SDK كإدخال للتحويل؟#

كيف يمكنني التعامل مع مجموعات البيانات الكبيرة التي تتجاوز حدود الذاكرة المعتادة؟#

هل هناك طريقة لأتمتة العملية في خط أنابيب CI/CD؟#

قراءة إضافية#