مثال عملي كامل لإزالة كائنات التعليقات التوضيحية من PDF باستخدام REST في Node.JS

يوضح هذا المثال كيفية تحميل ملف PDF، حذف جميع التعليقات التوضيحية الخاصة به، وتنزيل الملف المنظف باستخدام GroupDocs.Annotation SDK.

const fs = require('fs');
const path = require('path');
const GroupDocsAnnotationCloud = require("@groupdocs/annotation-cloud");

// ==== Authentication =========================================================
const clientId = "YOUR_CLIENT_ID";
const clientSecret = "YOUR_CLIENT_SECRET";

const config = new GroupDocsAnnotationCloud.Configuration(clientId, clientSecret);
const annotationsApi = new GroupDocsAnnotationCloud.AnnotationsApi(config);
const storageApi = new GroupDocsAnnotationCloud.StorageApi(config);

// ==== Local & Remote file definitions =======================================
const localInputPath = path.resolve(__dirname, "input.pdf");
const localOutputPath = path.resolve(__dirname, "output.pdf");
const remoteFilePath = "input.pdf";

// ==== Main workflow ==========================================================
(async () => {
    // 1. Upload PDF to GroupDocs Cloud storage
    const fileBytes = fs.readFileSync(localInputPath);
    const uploadRequest = new GroupDocsAnnotationCloud.UploadFileRequest({
        path: remoteFilePath,
        file: fileBytes
    });
    await storageApi.uploadFile(uploadRequest);

// 2. Build FileInfo object for the uploaded PDF
    const fileInfo = new GroupDocsAnnotationCloud.FileInfo({
        filePath: remoteFilePath
    });

// 3. Retrieve all existing annotations
    const getAnnotationsRequest = new GroupDocsAnnotationCloud.GetAnnotationsRequest({
        fileInfo: fileInfo
    });
    const annotationsResult = await annotationsApi.getAnnotations(getAnnotationsRequest);
    const annotationIds = (annotationsResult.annotations || []).map(a => a.id);

// 4. Delete all annotations (if any)
    if (annotationIds.length > 0) {
        const deleteRequest = new GroupDocsAnnotationCloud.DeleteAnnotationsRequest({
            fileInfo: fileInfo,
            annotationIds: annotationIds
        });
        await annotationsApi.deleteAnnotations(deleteRequest);
    }

// 5. Download the cleaned PDF back to local storage
    const downloadRequest = new GroupDocsAnnotationCloud.DownloadFileRequest({
        path: remoteFilePath
    });
    const fileStream = await storageApi.downloadFile(downloadRequest);
    fs.writeFileSync(localOutputPath, fileStream);
    console.log(`All annotations removed. Clean file saved to ${localOutputPath}`);
})();

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

حذف تعليقات PDF عبر REST API باستخدام cURL

فيما يلي أوامر cURL التي تنفّذ نفس سير عمل إزالة التعليقات التوضيحية عبر نقاط النهاية REST لسحابة GroupDocs.Annotation.

# 1. Obtain an access token
curl -X POST "https://api.groupdocs.cloud/v2.0/auth/token" \
     -H "Content-Type: application/json" \
     -d "{\"client_id\":\"YOUR_CLIENT_ID\",\"client_secret\":\"YOUR_CLIENT_SECRET\"}"

# 2. Upload the source PDF
curl -X PUT "https://api.groupdocs.cloud/v2.0/storage/file/input.pdf" \
     -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
     -H "Content-Type: application/pdf" \
     --data-binary "@input.pdf"

# 3. Retrieve annotation IDs
curl -X GET "https://api.groupdocs.cloud/v2.0/annotation/annotations?filePath=input.pdf" \
     -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

# 4. Delete all retrieved annotations
curl -X DELETE "https://api.groupdocs.cloud/v2.0/annotation/annotations?filePath=input.pdf" \
     -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
     -H "Content-Type: application/json" \
     -d "{\"annotationIds\":[\"id1\",\"id2\"]}"

# 5. Download the cleaned PDF
curl -X GET "https://api.groupdocs.cloud/v2.0/storage/file/input.pdf" \
     -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
     -o output.pdf

للحصول على قائمة كاملة بنقاط النهاية والمعلمات، راجع وثائق API الرسمية.

كيف تعمل إزالة كائنات التعليقات التوضيحية من PDF باستخدام REST في Node.JS

1. إعداد المصادقة - يتم إنشاء فئة Configuration باستخدام clientId و clientSecret الخاصين بك، مما ينشئ سياقًا موثوقًا لجميع استدعاءات API اللاحقة.

   const config = new GroupDocsAnnotationCloud.Configuration(clientId, clientSecret);
   

2. رفع الملف - يرسل UploadFileRequest بايتات ملف PDF المحلي إلى تخزين GroupDocs Cloud. تتولى طريقة storageApi.uploadFile عملية النقل.

   const uploadRequest = new GroupDocsAnnotationCloud.UploadFileRequest({
       path: remoteFilePath,
       file: fileBytes
   });
   await storageApi.uploadFile(uploadRequest);
   

3. استرجاع التعليقات التوضيحية - يبني GetAnnotationsRequest كائن طلب يحتوي على مرجع FileInfo. تُعيد استدعاء annotationsApi.getAnnotations مجموعة من كائنات التعليقات التوضيحية، يتم استخراج المعرفات منها.

   const getAnnotationsRequest = new GroupDocsAnnotationCloud.GetAnnotationsRequest({
       fileInfo: fileInfo
   });
   const annotationsResult = await annotationsApi.getAnnotations(getAnnotationsRequest);
   

4. حذف التعليقات التوضيحية - إذا كانت هناك أي معرفات، يتم ملء DeleteAnnotationsRequest وتمريره إلى annotationsApi.deleteAnnotations، الذي يزيل التعليقات التوضيحية بشكل دائم من ملف PDF المخزن.

   const deleteRequest = new GroupDocsAnnotationCloud.DeleteAnnotationsRequest({
       fileInfo: fileInfo,
       annotationIds: annotationIds
   });
   await annotationsApi.deleteAnnotations(deleteRequest);
   

5. تنزيل ملف PDF نظيف - أخيرًا، يقوم DownloadFileRequest بجلب الملف المحدث، وتكتب fs.writeFileSyncه إلى نظام الملفات المحلي.

   const downloadRequest = new GroupDocsAnnotationCloud.DownloadFileRequest({
       path: remoteFilePath
   });
   const fileStream = await storageApi.downloadFile(downloadRequest);
   fs.writeFileSync(localOutputPath, fileStream);
   

للحصول على تعريفات مفصلة للفئات والطرق، راجع مرجع API.

التثبيت والتهيئة GroupDocs.Annotation Cloud SDK for Node.js

يتم توزيع SDK كحزمة npm. قم بتثبيتها باستخدام الأمر أدناه ثم استخدم require في مشروعك.

npm install groupdocs-annotation-cloud

يمكنك أيضًا تنزيل أحدث حزمة مباشرةً من صفحة إصدارات GitHub أو من عنوان URL للتنزيل.

بعد التثبيت، استورد المكتبة وأنشئ كائن التكوين كما هو موضح في مثال الشيفرة التالي:

const GroupDocsAnnotationCloud = require("@groupdocs/annotation-cloud");
const config = new GroupDocsAnnotationCloud.Configuration("YOUR_CLIENT_ID", "YOUR_CLIENT_SECRET");

تأكد من أن بيئة التشغيل الخاصة بك تلبي متطلبات إصدار Node.js وأن لديك حساب GroupDocs صالح للحصول على بيانات اعتماد العميل.

خيارات وإعدادات إزالة التعليقات التوضيحية

يعرض SDK عدة معلمات يمكنك ضبطها:

• clientId / clientSecret - بيانات الاعتماد لمصادقة OAuth. قم بتعيينها في مُنشئ Configuration.
• fileInfo.filePath - مسار ملف PDF في تخزين GroupDocs Cloud. عدّل ذلك إذا كنت تخزن الملفات في مجلد مختلف.
• annotationIds - مصفوفة من المعرفات التي تم إرجاعها بواسطة GetAnnotations. توفير مجموعة فرعية يسمح بالحذف الانتقائي.

الإعدادات الإضافية مثل مهلات الطلب وتكوين الوكيل متاحة في وثائق SDK؛ راجع الوثائق الرسمية للحصول على القائمة الكاملة.

أفضل الممارسات لإزالة تعليقات PDF عبر REST

• تحقق من معرفات التعليقات التوضيحية - دائمًا تحقق من أن المعرفات التي تنوي حذفها موجودة؛ محاولة حذف معرفات غير موجودة قد تتسبب في حدوث خطأ 404.
• استخدام HTTPS - يجب إجراء جميع مكالمات API عبر HTTPS لحماية بيانات الاعتماد وبيانات المستند.
• معالجة الملفات الكبيرة باستخدام التحميل المجزأ - بالنسبة لملفات PDF التي يزيد حجمها عن 100 ميغابايت، يفضَّل استخدام نقطة النهاية للتحميل المتعدد لتجنب انتهاء المهلة.
• تسجيل استجابات API - احفظ معرفات الطلبات والاستجابات لسجلات التدقيق وتسهيل استكشاف الأخطاء.
• إعادة استخدام رموز الوصول - خزن رمز OAuth في الذاكرة المؤقتة حتى انتهاء صلاحيته لتقليل عبء المصادقة.

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

• كيف يمكنني المصادقة مع GroupDocs.Annotation Cloud API? احصل على معرف عميل وسر من حسابك في GroupDocs، ثم اطلب رمز وصول عبر نقطة النهاية OAuth. راجع الوثائق الرسمية للحصول على التفاصيل.

• هل يمكنني حذف تعليقات توضيحية محددة بدلاً من جميعها؟
  نعم، قدم معرفات التعليقات التوضيحية التي تريد إزالتها في DeleteAnnotationsRequest. تُعيد SDK قائمة بمعرفات التعليقات التوضيحية بعد استدعاء GetAnnotations.

• كيف يمكنني إزالة كائنات التعليق التوضيحي من PDF باستخدام REST في Node.JS؟
  استخدم GroupDocs.Annotation Cloud SDK for Node.js لاستدعاء نقطة النهاية DeleteAnnotations بعد استرجاع معرفات التعليقات التوضيحية. يتم عرض سير العمل الكامل في مثال الشيفرة وقسم cURL في هذا الدليل.

• ما هو الترخيص المطلوب للاستخدام في الإنتاج؟
  يلزم الحصول على ترخيص مدفوع للإنتاج. يمكنك الحصول على ترخيص مؤقت من صفحة صفحة الترخيص المؤقت أثناء التقييم.

قراءة إضافية

• استخراج أو إزالة التعليقات التوضيحية من PDF باستخدام REST API في Node.js
• نص مشطوب في PDF باستخدام Node.js و REST API
• إزالة التعليقات التوضيحية من PDF باستخدام REST API في Python

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

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

• 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

إضافة علامة مائية صورة إلى مستندات PDF في Java في 5 خطوات

1. تهيئة عميل API: إنشاء مثيل ApiClient باستخدام معرف العميل والسر الخاصين بك.

ApiClient apiClient = new ApiClient("YOUR_CLIENT_ID", "YOUR_CLIENT_SECRET");
WatermarkApi watermarkApi = new WatermarkApi(apiClient);

تقوم هذه الخطوة بربط كود Java الخاص بك بخدمة GroupDocs.Watermark Cloud. راجع مرجع API لمزيد من التفاصيل.

2. حدد ملف PDF المصدر: أنشئ كائن FileInfo يشير إلى ملف PDF الذي تريد إضافة علامة مائية إليه.

FileInfo fileInfo = new FileInfo();
fileInfo.setFilePath("input.pdf");

يجب تحميل الملف إلى تخزين GroupDocs الخاص بك قبل الطلب.

3. تكوين علامة مائية للصورة: تعريف مسار الصورة، الشفافية، معامل المقياس، الدوران والمحاذاة.

   ImageWatermark imageWatermark = new ImageWatermark();
   imageWatermark.setImagePath("watermark.png");
   imageWatermark.setOpacity(0.5);
   imageWatermark.setScaleFactor(0.3);
   imageWatermark.setHorizontalAlignment(HorizontalAlignment.CENTER);
   imageWatermark.setVerticalAlignment(VerticalAlignment.CENTER);
   imageWatermark.setMargin(new Margin(10, 10, 10, 10));
   

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

4. تعيين خيارات العلامة المائية ومسار الإخراج: اجمع معلومات الملف والعلامة المائية في كائن WatermarkOptions.

WatermarkOptions options = new WatermarkOptions();
options.setFileInfo(fileInfo);
options.setImageWatermark(imageWatermark);
options.setOutputPath("output.pdf");

يحدد outputPath للخدمة مكان تخزين ملف PDF الناتج.

5. تنفيذ الطلب: بناء AddWatermarkRequest واستدعاء الـ API. معالجة الاستجابات الناجحة أو الأخطاء.

AddWatermarkRequest request = new AddWatermarkRequest(options);
try {
    AddWatermarkResponse response = watermarkApi.addWatermark(request);
    System.out.println("Watermark added successfully. Output file: " + response.getPath());
} catch (Exception e) {
    System.err.println("Error adding watermark: " + e.getMessage());
}

بعد التنفيذ، يصبح ملف PDF المطبوع عليه العلامة المائية متاحًا في الموقع الذي حددته.

مثال كامل على الكود: إضافة علامة مائية صورة إلى مستندات PDF في Java

يوضح المثال التالي التنفيذ الكامل من تهيئة العميل إلى حفظ ملف PDF مع علامة مائية.

import com.groupdocs.cloud.watermark.api.WatermarkApi;
import com.groupdocs.cloud.watermark.client.ApiClient;
import com.groupdocs.cloud.watermark.model.AddWatermarkRequest;
import com.groupdocs.cloud.watermark.model.AddWatermarkResponse;
import com.groupdocs.cloud.watermark.model.FileInfo;
import com.groupdocs.cloud.watermark.model.ImageWatermark;
import com.groupdocs.cloud.watermark.model.Margin;
import com.groupdocs.cloud.watermark.model.WatermarkOptions;
import com.groupdocs.cloud.watermark.model.enums.HorizontalAlignment;
import com.groupdocs.cloud.watermark.model.enums.VerticalAlignment;

public class AddImageWatermarkExample {
    public static void main(String[] args) {
        // Initialize API client (replace with your actual credentials)
        ApiClient apiClient = new ApiClient("YOUR_CLIENT_ID", "YOUR_CLIENT_SECRET");
        WatermarkApi watermarkApi = new WatermarkApi(apiClient);

// Input PDF file information
        FileInfo fileInfo = new FileInfo();
        fileInfo.setFilePath("input.pdf");

// Image watermark configuration
        ImageWatermark imageWatermark = new ImageWatermark();
        imageWatermark.setImagePath("watermark.png");          // Path to watermark image
        imageWatermark.setOpacity(0.5);                        // 50% opacity
        imageWatermark.setScaleFactor(0.3);                    // 30% of page size
        imageWatermark.setRotationAngle(0);                    // No rotation
        imageWatermark.setHorizontalAlignment(HorizontalAlignment.CENTER);
        imageWatermark.setVerticalAlignment(VerticalAlignment.CENTER);
        imageWatermark.setMargin(new Margin(10, 10, 10, 10));  // 10 points margin on all sides

// Watermark options
        WatermarkOptions options = new WatermarkOptions();
        options.setFileInfo(fileInfo);
        options.setImageWatermark(imageWatermark);
        options.setOutputPath("output.pdf"); // Resulting PDF with watermark

// Create request and call API
        AddWatermarkRequest request = new AddWatermarkRequest(options);
        try {
            AddWatermarkResponse response = watermarkApi.addWatermark(request);
            System.out.println("Watermark added successfully. Output file: " + response.getPath());
        } catch (Exception e) {
            System.err.println("Error adding watermark: " + e.getMessage());
            e.printStackTrace();
        }
    }
}

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

تطبيق علامة مائية صورة على مستندات PDF عبر cURL و REST API

فيما يلي طلبات REST التي يمكنك استخدامها مع cURL لتحقيق النتيجة نفسها دون كتابة كود Java.

1. الحصول على رمز وصول

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

   تحتوي الاستجابة على access_token يُستخدم في المكالمات اللاحقة.

2. تحميل ملف PDF المصدر

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

3. رفع صورة العلامة المائية

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

4. إضافة علامة مائية صورة

curl -X POST "https://api.groupdocs.cloud/v2.0/watermark/add" \
     -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
     -H "Content-Type: application/json" \
     -d '{
           "fileInfo": { "filePath": "input.pdf" },
           "imageWatermark": {
               "imagePath": "watermark.png",
               "opacity": 0.5,
               "scaleFactor": 0.3,
               "horizontalAlignment": "Center",
               "verticalAlignment": "Center",
               "margin": { "top": 10, "right": 10, "bottom": 10, "left": 10 }
           },
           "outputPath": "output.pdf"
         }'

هذا الطلب يعكس منطق كود Java، ويطبق نفس إعدادات الشفافية، والتحجيم، والمحاذاة.

5. تنزيل ملف PDF المطبوع عليه علامة مائية

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

لمزيد من التفاصيل حول أجسام الطلب والمعلمات المدعومة، راجع الوثائق الرسمية لواجهة برمجة التطبيقات.

تثبيت وتكوين GroupDocs.Watermark Cloud SDK for Java

أضف اعتماد Maven إلى ملف pom.xml الخاص بك (أو المقتطف المكافئ لـ Gradle). المكتبة مستضافة على Maven Central.

<dependency>
    <groupId>com.groupdocs</groupId>
    <artifactId>groupdocs-watermark-cloud</artifactId>
    <version>23.8</version>
</dependency>

ستحتاج أيضًا إلى حساب GroupDocs Cloud صالح. استرجع معرف العميل و سر العميل من GroupDocs portal. لا يلزم أي تثبيت إضافي في وقت التشغيل لأن SDK يتواصل مع خدمة السحابة.

ضبط خيارات العلامة المائية بالصورة لمستندات PDF

يُتيح SDK عدة خصائص تسمح لك بالتحكم في المظهر البصري للعلامة المائية.

ضبط الشفافية

imageWatermark.setOpacity(0.75); // 75% opacity for a more visible watermark

تتراوح قيم الشفافية من 0.0 (شفاف تمامًا) إلى 1.0 (معتم تمامًا).

تغيير معامل المقياس

imageWatermark.setScaleFactor(0.5); // Watermark occupies 50% of the page width

عامل المقياس يحدد حجم العلامة المائية بالنسبة لأبعاد الصفحة.

تعيين المحاذاة والهوامش

imageWatermark.setHorizontalAlignment(HorizontalAlignment.RIGHT);
imageWatermark.setVerticalAlignment(VerticalAlignment.BOTTOM);
imageWatermark.setMargin(new Margin(20, 20, 20, 20));

تضع هذه الإعدادات العلامة المائية في الزاوية السفلية‑اليمنى مع هامش قدره 20 نقطة.

للحصول على قائمة كاملة بالخصائص القابلة للتكوين، راجع مرجع API.

الخلاصة

إضافة علامة مائية صورة إلى مستندات PDF في Java هي مهمة بسيطة عندما تستخدم GroupDocs.Watermark Cloud SDK for Java. يتعامل SDK مع جميع عمليات تعديل PDF منخفضة المستوى، مما يتيح لك التركيز على الجوانب البصرية مثل الشفافية، والتحجيم، والتموضع. سواء كنت تفضل تنفيذًا أصليًا بلغة Java أو سير عمل سحابي يعتمد على cURL، يمكن تحقيق نفس النتائج عالية الجودة دون التضحية بالأداء. تذكر الحصول على ترخيص مناسب للاستخدام في الإنتاج؛ تفاصيل التسعير متوفرة على صفحة المنتج ويمكن استخدام temporary license page للتقييم.

الأسئلة المتكررة

• كيف يمكنني إضافة علامة مائية صورة إلى PDF في Java دون فقدان الجودة؟
  استخدم الخاصية scaleFactor لتحديد حجم العلامة المائية نسبة إلى الصفحة والحفاظ على DPI الأصلي لملف PDF المصدر. يحافظ SDK على دقة PDF، لذا تظهر العلامة المائية واضحة عند أي مستوى تكبير.

• هل يمكنني إضافة علامات مائية متعددة إلى نفس ملف PDF؟
  نعم. أنشئ كائنات ImageWatermark منفصلة بإعدادات مختلفة وأضفها بالتتابع عن طريق استدعاء addWatermark عدة مرات أو عن طريق إضافتها إلى قائمة في الطلب.

• ما هي صيغ الصور المدعومة للعلامة المائية؟
  تقبل API صيغ الصور الشائعة مثل PNG, JPG, BMP, GIF و TIFF. يُنصح باستخدام PNG للحصول على جودة غير مضغوطة ودعم الشفافية.

• هل هناك طريقة لمعاينة العلامة المائية قبل تطبيقها؟
  يمكنك استخدام GroupDocs.Watermark Cloud SDK for Java لإنشاء ملف PDF مؤقت مع العلامة المائية وتحميله للمراجعة. يستخدم هذا نفس استدعاء addWatermark مع مسار إخراج يشير إلى موقع مؤقت.

اقرأ المزيد

• إضافة علامة مائية إلى الصور باستخدام Java
• إضافة علامة مائية إلى Word في Java - منشئ العلامات المائية
• إضافة علامة مائية صورة إلى PDF | كيفية إضافة علامة مائية إلى مستندات PDF باستخدام .NET