قبل أن تبدأ: المتطلبات والتثبيت

قبل أن تبدأ، تأكد من أن لديك ما يلي:

• Node.js 14 أو أحدث مثبت على جهاز التطوير الخاص بك.
• حساب GroupDocs Cloud نشط مع معرف العميل والسر الخاص بالعميل.
• الوصول إلى ملفات PDF التي تريد دمجها، المخزنة في تخزين GroupDocs Cloud.

قم بتثبيت SDK عبر npm وقم بتنزيل أحدث حزمة:

npm install groupdocs-merger-cloud

يمكنك أيضًا الحصول على SDK من صفحة الإصدار الرسمية: تحميل SDK. بعد التثبيت، أنت جاهز للبدء في كتابة الشيفرة.

دليل خطوة بخطوة لدمج PDF في Node.JS

الخطوة 1: تثبيت SDK واستيراد الفئات المطلوبة

أولاً، استورد الفئات التي ستحتاجها لدمج ملفات PDF.

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

يمنحك هذا الاستيراد الوصول إلى واجهة برمجة التطبيقات الأساسية، وكائنات التكوين، ومؤشرات الملفات.

الخطوة 2: تكوين بيانات اعتماد 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، استدعاء طريقة الدمج، ومعالجة الاستجابة.

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();

ملاحظة: هذا المثال البرمجي يوضح الوظيفة الأساسية. قبل استخدامه في مشروعك، تأكد من تحديث أي مسارات ملفات وقيم التكوين لتتناسب مع بيئتك الفعلية، وتحقق من أن جميع الاعتمادات المطلوبة مثبتة بشكل صحيح، واختبر بدقة في بيئة التطوير الخاصة بك. إذا واجهت أي مشكلات، يرجى الرجوع إلى الوثائق الرسمية أو التواصل مع فريق الدعم للحصول على المساعدة.

دمج ملفات PDF عبر واجهة برمجة التطبيقات REST باستخدام 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 الكبيرة أو العديدة، احرص على مراعاة النصائح التالية:

• استخدام async/await لتجنب حظر حلقة الأحداث، خاصةً للوثائق الكبيرة.
• تحميل دفعي: رفع ملفات PDF المصدرية بالتوازي قبل استدعاء الدمج لتقليل الكمون الكلي.
• معالجة متدفقة: بالنسبة لملفات PDF الكبيرة جدًا، فكر في تخزين النتائج الوسيطة في التخزين السحابي ودمجها على دفعات أصغر.
• ملفات PDF مشفرة: قدم كلمات المرور في كائنات FileInfo؛ معالجة الملفات المشفرة يضيف عبئًا إضافيًا، لذا قم بدمجها بعد فك التشفير عندما يكون ذلك ممكنًا.

تطبيق هذه الممارسات يساعدك على دمج ملفات PDF في Node.JS بكفاءة مع تقليل استهلاك الذاكرة.

أسئلة قد تكون لديك

• كيف يمكنني دمج ملفات PDF في Node.JS باستخدام GroupDocs؟
  استخدم GroupDocs.Merger Cloud SDK for Node.js لإنشاء كائن MergeApi، وتكوين MergeOptions مع ملفات PDF المصدر الخاصة بك، واستدعاء mergeDocuments. يوضح مثال الشيفرة الكامل في هذا الدليل العملية.

• هل يمكنني دمج ملفات PDF المشفرة في Node.JS؟
  نعم، يدعم SDK دمج ملفات PDF المشفرة. قدم كلمات المرور الصحيحة في كائنات FileInfo قبل استدعاء mergeDocuments. راجع الوثائق الرسمية للحصول على التفاصيل.

• ما هي خيارات الترخيص لـ GroupDocs.Merger؟
  تقدم GroupDocs خطط أسعار مرنة. للاختبار، يمكنك طلب رخصة مؤقتة لتقييم المكتبة قبل شراء اشتراك كامل.

• أين يمكنني العثور على مزيد من الأمثلة والدعم؟
  تتوفر عينات إضافية في مستودع GitHub. للحصول على المساعدة، زر منتدى الدعم.

قراءة إضافية

• تقسيم PDF إلى ملفات PDF متعددة في Node.JS
• قفل مستندات PDF باستخدام كلمات مرور عبر REST API في Node.js
• كيفية دمج ملفات PDF في C# باستخدام REST API