مثال کامل کارآمد برای حذف اشیاء حاشیه‌نویسی از 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}`);
})();

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

حذف حاشیه‌نویسی‌های PDF از طریق REST API با استفاده از cURL

در زیر دستورات cURL آمده است که همان جریان کار حذف حاشیه‌نویسی را از طریق GroupDocs.Annotation Cloud REST endpoints انجام می‌دهند.

# 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 یا آدرس دانلود رسمی دریافت کنید.

پس از نصب، کتابخانه را وارد کنید و یک شیء پیکربندی ایجاد کنید همان‌طور که در مثال کد نشان داده شده است:

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 بزرگ‌تر از ۱۰۰ مگابایت، ترجیحاً از نقطه انتهایی بارگذاری چندبخشی استفاده کنید تا از زمان‌سنجی جلوگیری شود.
• ثبت لاگ پاسخ‌های API - شناسه‌های درخواست و پاسخ‌ها را برای مسیرهای حسابرسی و رفع مشکل آسان‌تر ذخیره کنید.
• استفاده مجدد از توکن‌های دسترسی - توکن OAuth را تا زمان انقضا در کش نگه دارید تا بار احراز هویت کاهش یابد.

سوالات متداول

• چگونه می‌توانم با GroupDocs.Annotation Cloud API احراز هویت کنم؟
  یک شناسه کلاینت (client ID) و رمز (secret) را از حساب GroupDocs خود دریافت کنید، سپس یک توکن دسترسی را از طریق نقطه انتهایی OAuth درخواست کنید. برای جزئیات، به مستندات رسمی مراجعه کنید.

• آیا می‌توانم حاشیه‌نویسی‌های خاص را به جای همه حذف کنم؟
  بله، شناسه‌های حاشیه‌نویسی‌هایی که می‌خواهید حذف کنید را در DeleteAnnotationsRequest ارائه دهید. SDK پس از فراخوانی GetAnnotations فهرست شناسه‌های حاشیه‌نویسی را برمی‌گرداند.

• چگونه می‌توانم اشیاء Annotation را از PDF با REST در Node.JS حذف کنم؟
  برای حذف اشیاء Annotation از PDF با استفاده از REST در Node.JS، از GroupDocs.Annotation Cloud SDK for Node.js استفاده کنید تا پس از دریافت شناسه‌های حاشیه‌نویسی، endpoint DeleteAnnotations را فراخوانی کنید. جریان کامل کار در مثال کد و بخش cURL این راهنما نشان داده شده است.

• برای استفاده در تولید چه مجوزی لازم است؟
  برای تولید به یک مجوز پرداختی نیاز است. می‌توانید در حین ارزیابی، یک مجوز موقت را از صفحهٔ مجوز موقت دریافت کنید.

مطالعه بیشتر

• استخراج یا حذف حاشیه‌نویسی‌ها از PDF با استفاده از REST API در Node.js
• متن خط خورده در PDF با Node.js و REST API
• حذف حاشیه‌نویسی‌ها از PDF با استفاده از REST API در Python

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

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

• 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 موجود است. برای دریافت کمک، به انجمن پشتیبانی مراجعه کنید.

مطالعه بیشتر

• تقسیم PDF به چندین PDF در Node.JS
• قفل کردن اسناد PDF با رمز عبور با استفاده از REST API در Node.js
• نحوه ادغام فایل‌های PDF در C# با استفاده از REST API

افزودن واترمارک تصویر به اسناد PDF در جاوا در 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 در جاوا

مثال زیر پیاده‌سازی کامل از مقداردهی اولیهٔ کلاینت تا ذخیره‌سازی 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
   

برای جزئیات بیشتر در مورد بدنه‌های درخواست و پارامترهای پشتیبانی‌شده، مستندات رسمی API را ببینید.

نصب و پیکربندی 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 نیاز دارید. Client ID و Client Secret خود را از پرتال GroupDocs دریافت کنید. نصب زمان اجرا اضافی لازم نیست زیرا 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 در جاوا کاری ساده است هنگامی که از GroupDocs.Watermark Cloud SDK for Java استفاده می‌کنید. SDK تمام عملیات‌های سطح پایین PDF را مدیریت می‌کند و به شما امکان می‌دهد بر جنبه‌های بصری مانند شفافیت، مقیاس‌بندی و موقعیت‌یابی تمرکز کنید. چه پیاده‌سازی بومی جاوا را ترجیح دهید و چه گردش کار مبتنی بر cURL در ابر، می‌توانید نتایج با کیفیت بالا را بدون کاهش عملکرد به دست آورید. به‌خاطر داشته باشید که برای استفاده در محیط تولید یک لایسنس مناسب دریافت کنید؛ جزئیات قیمت‌گذاری در صفحه محصول موجود است و می‌توانید برای ارزیابی از صفحه لایسنس موقت استفاده کنید.

سوالات متداول

• چگونه می‌توانم واترمارک تصویر را به PDF در جاوا اضافه کنم بدون از دست دادن کیفیت؟
  از ویژگی scaleFactor برای اندازه‌گیری واترمارک نسبت به صفحه استفاده کنید و DPI اصلی PDF منبع را حفظ کنید. SDK وضوح PDF را حفظ می‌کند، بنابراین واترمارک در هر سطح زوم واضح باقی می‌ماند.

• آیا می‌توانم چندین واترمارک به یک PDF اضافه کنم؟
  بله. اشیاء ImageWatermark جداگانه‌ای با پیکربندی‌های مختلف ایجاد کنید و آنها را به‌صورت متوالی با فراخوانی addWatermark چندین بار یا با افزودن آنها به یک لیست در درخواست اضافه کنید.

• فرمت‌های تصویر پشتیبانی‌شده برای واترمارک چیست؟
  API انواع تصویر رایج مانند PNG، JPG، BMP، GIF و TIFF را می‌پذیرد. PNG برای کیفیت بدون افت و پشتیبانی از شفافیت توصیه می‌شود.

• آیا راهی برای پیش‌نمایش واترمارک قبل از اعمال آن وجود دارد؟
  شما می‌توانید از GroupDocs.Watermark Cloud SDK for Java برای تولید یک PDF موقت با واترمارک استفاده کنید و آن را برای بررسی دانلود کنید. این کار از همان فراخوانی addWatermark با مسیر خروجی که به یک مکان موقت اشاره دارد، استفاده می‌کند.

Read More

• افزودن واترمارک به تصاویر با استفاده از جاوا
• افزودن واترمارک به Word در جاوا - Watermark Creator
• افزودن واترمارک تصویر به PDF | نحوه افزودن واترمارک به اسناد PDF با استفاده از .NET