המרת 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 to XLSX Conversion via REST API Using 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. לפרטים נוספים, ראו את תיעוד ה‑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(',')];
```
Write Temporary CSV File - תוכן ה‑CSV נכתב לקובץ זמני (temp_input.csv). שלב זה ממלא את דרישות ה‑Aspose.3D API, הצופה לקלט קובץ, תוך שמירה על אפשרות הזרמת הנתונים מאוחר יותר.

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

זרימת קובץ למאגר - 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 לדיסק - ה‑buffer שנוצר נכתב באמצעות writeBufferToFile, משלים את צינור העבודה מבלי להחזיק את קובץ ה‑XLSX המלא בזיכרון יותר מהנדרש.
```
await writeBufferToFile(conversionResult, outputXlsxPath);
```

כל שלב נועד ל- JSON ל‑XLSX זרימה ב‑Node.JS ו- JSON ל‑XLSX חסכוני בזיכרון ב‑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 ל‑XLSX יעילה בזיכרון ב‑Node.JS.

באיזה פורמט קובץ מצפה ה‑SDK כקלט להמרה?

קצה ההמרה עובד עם CSV כפורמט ביניים. הדוגמה יוצרת קובץ CSV זמני מכיוון ש‑Aspose.3D מצפה לקלט קובץ לפני יצירת ה‑XLSX.

איך אני מתמודד עם מערכי נתונים גדולים שמעלים את מגבלות הזיכרון הרגילות?

השתמש בגישה המבוססת על זרימה המוצגת בקוד. היא קוראת את קובץ המקור באמצעות זרם קריאה, בונה את קובץ ה‑CSV שורה אחרי שורה, ושולחת את החוצץ לשירות הענן, תוך הבטחה שרק חלקים קטנים נשארים בזיכרון בכל רגע.

האם יש דרך לאוטומט את התהליך בצינור CI/CD?

בהחלט. ניתן לקרוא לאותו סקריפט Node.JS מתוך סקריפטי בנייה, וניתן לשלב את פקודות cURL בשלבי shell. רק יש לוודא שמשתני הסביבה ASPOSE_CLIENT_ID ו‑ASPOSE_CLIENT_SECRET מסופקים בצורה מאובטחת.

דוגמת קוד מלאה: זרימת JSON ל‑XLSX ב‑Node.JS#

JSON to XLSX Conversion via REST API Using cURL#

כיצד JSON ל‑XLSX יעיל בזיכרון ב‑Node.JS פועל#

הכנת סביבת העבודה לייצוא JSON ל‑XLSX - דרישות מוקדמות והגדרה#

נקודות מפתח#

שאלות נפוצות#

האם ניתן להמיר JSON ל‑XLSX ב‑Node.JS מבלי לטעון את כל הקובץ לזיכרון?#

באיזה פורמט קובץ מצפה ה‑SDK כקלט להמרה?#

איך אני מתמודד עם מערכי נתונים גדולים שמעלים את מגבלות הזיכרון הרגילות?#

האם יש דרך לאוטומט את התהליך בצינור CI/CD?#

קריאה נוספת#