ترکیب چندین سند PDF در یک فایل واحد یک نیاز رایج هنگام ساخت گردش کارهای سند یا تولید گزارش‌ها است. GroupDocs.Merger Cloud SDK for Node.js ادغام PDF در Node.JS را بدون نیاز به کار با ساختارهای سطح پایین PDF آسان می‌کند. این راهنما شما را از طریق تنظیمات، پیاده‌سازی گام به گام، یک مثال کامل کد، تماس‌های معادل cURL و نکات عملکردی برای PDFهای بزرگ یا رمزگذاری‌شده راهنمایی می‌کند.

قبل از شروع: پیش‌نیازها و نصب

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

  • Node.js 14 یا بالاتر نصب شده بر روی ماشین توسعه شما.
  • یک حساب فعال GroupDocs Cloud با client ID و client secret.
  • دسترسی به فایل‌های PDF که می‌خواهید ترکیب کنید، ذخیره شده در GroupDocs Cloud storage.

SDK را از طریق npm نصب کنید و آخرین بسته را دانلود کنید:

npm install groupdocs-merger-cloud

همچنین می‌توانید SDK را از صفحهٔ رسمی انتشار دریافت کنید: Download SDK. پس از نصب، آماده‌اید که کدنویسی را آغاز کنید.

راهنمای گام به گام برای ادغام PDF در Node.JS

مرحله 1: نصب SDK و وارد کردن کلاس‌های مورد نیاز

ابتدا کلاس‌هایی را که برای ادغام PDFها نیاز دارید، وارد کنید.

const { MergeApi, MergeOptions, FileInfo, Configuration } = require("@groupdocs/merger-cloud");

این وارد کردن به شما دسترسی به API اصلی، اشیاء پیکربندی و توصیف‌گرهای فایل را می‌دهد.

مرحله ۲: پیکربندی اعتبارهای GroupDocs خود

یک شیء پیکربندی با اعتبارهای کلاینت خود ایجاد کنید.

const config = new Configuration({
    clientId: "YOUR_CLIENT_ID",
    clientSecret: "YOUR_CLIENT_SECRET"
});

ارائهٔ اعتبارهای صحیح به کتابخانه امکان می‌دهد درخواست‌های شما را احراز هویت کند.

مرحله 3: تعریف فایل‌های PDF برای ادغام

فهرست اسناد PDF که می‌خواهید ترکیب کنید. این مرحله شما را برای ادغام PDF در Node.JS به‌صورت کارآمد آماده می‌کند.

const filesToMerge = [
    new FileInfo({ filePath: "input1.pdf" }),
    new FileInfo({ filePath: "input2.pdf" })
];

هر FileInfo به فایلی که در ذخیره‌سازی GroupDocs Cloud شما ذخیره شده است اشاره می‌کند.

مرحله 4: تنظیم گزینه‌های ادغام

محل خروجی را پیکربندی کنید و فهرست فایل‌ها را به درخواست ادغام پیوست کنید.

const mergeOptions = new MergeOptions();
mergeOptions.fileInfos = filesToMerge;
mergeOptions.outputPath = "merged_output.pdf";

این تنظیمات کنترل می‌کنند که چگونه PDF را در Node.JS ترکیب می‌کنید و نتیجه در کجا ذخیره می‌شود.

مرحله 5: اجرای عملیات ادغام

یک نمونه از API ایجاد کنید، متد merge را فراخوانی کنید و پاسخ را مدیریت کنید.

const mergeApi = new MergeApi(config);

try {
    const result = await mergeApi.mergeDocuments(mergeOptions);
    console.log("Merge completed. Output file stored at:", result.path);
} catch (error) {
    console.error("Error during PDF merge:", error);
}

فراخوانی ناهمزمان مسیر سند ادغام‌شده را در صورت موفقیت عملیات برمی‌گرداند.

مثال کامل پیاده‌سازی برای ادغام PDFها در Node.JS

کد زیر جریان کاری کامل از پیکربندی تا پردازش نتایج را نشان می‌دهد.

const { MergeApi, MergeOptions, FileInfo, Configuration } = require("@groupdocs/merger-cloud");

// Configure the SDK (replace with your actual credentials)
const config = new Configuration({
    clientId: "YOUR_CLIENT_ID",
    clientSecret: "YOUR_CLIENT_SECRET"
});

async function mergePdfFiles() {
    // Initialize the Merge API
    const mergeApi = new MergeApi(config);

// Define the PDF files to be merged (must exist in GroupDocs Cloud storage)
    const filesToMerge = [
        new FileInfo({ filePath: "input1.pdf" }),
        new FileInfo({ filePath: "input2.pdf" })
    ];

// Set merge options
    const mergeOptions = new MergeOptions();
    mergeOptions.fileInfos = filesToMerge;
    mergeOptions.outputPath = "merged_output.pdf";

try {
        // Perform the merge operation
        const result = await mergeApi.mergeDocuments(mergeOptions);
        console.log("Merge completed. Output file stored at:", result.path);
    } catch (error) {
        console.error("Error during PDF merge:", error);
    }
}

// Execute the merge
mergePdfFiles();

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

ادغام PDFها از طریق REST API با استفاده از cURL

اگر ترجیح می‌دهید از روش خالص REST استفاده کنید، همان عملیات را می‌توان با دستورات cURL انجام داد.

ابتدا یک توکن دسترسی دریافت کنید:

curl -X POST "https://api.groupdocs.cloud/v2.0/oauth2/token" \
     -H "Content-Type: application/json" \
     -d '{"client_id":"YOUR_CLIENT_ID","client_secret":"YOUR_CLIENT_SECRET","grant_type":"client_credentials"}'

فایل‌های PDF منبع را به ذخیره‌ساز خود بارگذاری کنید (به جای YOUR_ACCESS_TOKEN توکن مرحلهٔ قبلی را قرار دهید):

curl -X POST "https://api.groupdocs.cloud/v2.0/storage/file/upload?path=input1.pdf" \
     -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
     -F "file=@/local/path/input1.pdf"

بارگذاری را برای input2.pdf تکرار کنید. سپس درخواست عملیات ادغام را بدهید:

curl -X POST "https://api.groupdocs.cloud/v2.0/merger/merge" \
     -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
     -H "Content-Type: application/json" \
     -d '{
           "fileInfos": [
               {"filePath":"input1.pdf"},
               {"filePath":"input2.pdf"}
           ],
           "outputPath":"merged_output.pdf"
         }'

در نهایت، فایل ترکیب‌شده را دانلود کنید:

curl -X GET "https://api.groupdocs.cloud/v2.0/storage/file/download?path=merged_output.pdf" \
     -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
     -o merged_output.pdf

برای دریافت فهرست کامل نقاط انتهایی و پارامترها، به مرجع API مراجعه کنید.

پیکربندی گزینه‌های ادغام

SDK چندین گزینه را ارائه می‌دهد که به شما امکان تنظیم دقیق فرآیند ادغام را می‌دهد:

  • outputPath - مسیر مقصد برای PDF ترکیب‌شده. این را تنظیم کنید تا مکان ذخیره‌سازی نتیجه را کنترل کنید.
  • fileInfos - آرایه‌ای از اشیاء FileInfo که PDFهای منبع و ترتیب آن‌ها را تعریف می‌کند.

شما همچنین می‌توانید ویژگی‌های اضافی مانند pages برای ادغام محدوده‌های خاص صفحه یا password برای PDFهای رمزگذاری‌شده را تنظیم کنید. برای دریافت فهرست کامل فیلدهای قابل پیکربندی به مستندات رسمی مراجعه کنید.

ملاحظات عملکرد برای ادغام PDFها

هنگام ترکیب فایل‌های PDF بزرگ یا زیاد، این نکات را در نظر بگیرید:

  • Use async/await برای جلوگیری از مسدود کردن حلقهٔ رویداد، به‌ویژه برای اسناد بزرگ.
  • Batch uploads: بارگذاری فایل‌های PDF منبع به‌صورت موازی قبل از فراخوانی ادغام برای کاهش تأخیر کلی.
  • Streamed processing: برای PDFهای بسیار بزرگ، ذخیره نتایج میانی در فضای ذخیره‌سازی ابری و ادغام آن‌ها در بخش‌های کوچکتر را در نظر بگیرید.
  • Encrypted PDFs: رمزهای عبور را در اشیاء FileInfo ارائه دهید؛ پردازش فایل‌های رمزگذاری‌شده بار اضافی دارد، بنابراین در صورت امکان پس از رمزگشایی آن‌ها را ادغام کنید.

به‌کارگیری این روش‌ها به شما کمک می‌کند تا PDF را در Node.JS به‌صورت کارآمد ادغام کنید و در عین حال مصرف حافظه را به حداقل برسانید.

سؤالاتی که ممکن است داشته باشید

  • چگونه می‌توانم فایل‌های PDF را در Node.JS با استفاده از GroupDocs ادغام کنم؟
    از GroupDocs.Merger Cloud SDK for Node.js استفاده کنید تا یک نمونه MergeApi ایجاد کنید، MergeOptions را با PDFهای منبع خود پیکربندی کنید و mergeDocuments را فراخوانی کنید. مثال کامل کد در این راهنما فرآیند را نشان می‌دهد.

  • آیا می‌توانم فایل‌های PDF رمزگذاری‌شده را در Node.JS ادغام کنم؟
    بله، SDK از ادغام PDFهای رمزگذاری‌شده پشتیبانی می‌کند. قبل از فراخوانی mergeDocuments، رمزهای عبور صحیح را در اشیاء FileInfo ارائه دهید. برای جزئیات، به مستندات رسمی مراجعه کنید.

  • گزینه‌های مجوز برای GroupDocs.Merger چیست؟
    GroupDocs برنامه‌های قیمت‌گذاری انعطاف‌پذیر ارائه می‌دهد. برای آزمایش، می‌توانید یک مجوز موقت درخواست کنید تا کتابخانه را قبل از خرید اشتراک کامل ارزیابی کنید.

  • کجا می‌توانم نمونه‌های بیشتر و پشتیبانی پیدا کنم؟
    نمونه‌های اضافی در مخزن GitHub موجود است. برای دریافت کمک، به انجمن پشتیبانی مراجعه کنید.

مطالعه بیشتر