مقایسهٔ فایل‌های Word به‌صورت برنامه‌نویسی یک نیاز مکرر برای سرویس‌های بک‌اند است که باید تغییرات را شناسایی کنند، گزارش‌های بازنگری تولید کنند یا سیاست‌های سند را اعمال نمایند. GroupDocs.Comparison Cloud SDK for Node.js یک API قدرتمند فراهم می‌کند که این کار را برای برنامه‌های Node.js ساده می‌سازد. در این راهنما خواهید آموخت که چگونه SDK را تنظیم کنید، مقایسهٔ کامل دو فایل DOCX را اجرا کنید، از دستورات معادل cURL استفاده کنید، هر بخش از پیاده‌سازی را درک کنید و توصیه‌های بهترین‑عمل را برای حفظ قابلیت اطمینان و امنیت راه‌حل خود دنبال کنید.

مثال کامل کد: مقایسه اسناد Word در Node.JS

مثال زیر یک جریان کار کامل انتها‑به‑انتها برای مقایسه دو سند Word با استفاده از GroupDocs.Comparison Cloud SDK for Node.js را نشان می‌دهد.

const GroupDocsComparisonCloud = require("@groupdocs/comparison-cloud");
const fs = require("fs");
const path = require("path");

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

const config = new GroupDocsComparisonCloud.Configuration(clientId, clientSecret);
const compareApi = new GroupDocsComparisonCloud.CompareApi(config);
const storageApi = new GroupDocsComparisonCloud.StorageApi(config);

// ==== File definitions =======================================================
const sourceFileName = "document1.docx";
const targetFileName = "document2.docx";
const resultFileName = "comparison_result.docx";

const sourceFilePath = path.resolve(__dirname, sourceFileName);
const targetFilePath = path.resolve(__dirname, targetFileName);

// ==== Main async function ====================================================
(async () => {
    try {
        // ---- Upload source document -----------------------------------------
        const sourceData = fs.readFileSync(sourceFilePath);
        const uploadSourceReq = new GroupDocsComparisonCloud.UploadFileRequest({
            path: sourceFileName,
            file: sourceData
        });
        await storageApi.uploadFile(uploadSourceReq);

// ---- Upload target document -----------------------------------------
        const targetData = fs.readFileSync(targetFilePath);
        const uploadTargetReq = new GroupDocsComparisonCloud.UploadFileRequest({
            path: targetFileName,
            file: targetData
        });
        await storageApi.uploadFile(uploadTargetReq);

// ---- Prepare comparison options --------------------------------------
        const compareOptions = new GroupDocsComparisonCloud.CompareOptions({
            sourceFile: new GroupDocsComparisonCloud.FileInfo({ filePath: sourceFileName }),
            targetFiles: [new GroupDocsComparisonCloud.FileInfo({ filePath: targetFileName })],
            outputPath: resultFileName,
            // optional: you can set settings like generateSummaryPage, showDeletedContent, etc.
        });

const compareRequest = new GroupDocsComparisonCloud.CompareDocumentRequest({
            compareOptions: compareOptions
        });

// ---- Execute comparison -----------------------------------------------
        const compareResult = await compareApi.compareDocument(compareRequest);
        console.log("Comparison completed. Result stored at:", compareResult.path);

// ---- (Optional) Clean up uploaded files --------------------------------
        await storageApi.deleteFile(new GroupDocsComparisonCloud.DeleteFileRequest({ path: sourceFileName }));
        await storageApi.deleteFile(new GroupDocsComparisonCloud.DeleteFileRequest({ path: targetFileName }));
        // Note: result file remains in storage; you can download it if needed.
    } catch (error) {
        console.error("Error during comparison:", error);
    }
})();

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

انجام مقایسه سند با cURL و REST API

اگر ترجیح می‌دهید رویکردی مستقل از زبان داشته باشید، می‌توانید همان نتیجه را با درخواست‌های ساده HTTP به دست آورید. در زیر دستورات اساسی cURL آورده شده است.

  1. احراز هویت و دریافت توکن دسترسی
    YOUR_CLIENT_ID و YOUR_CLIENT_SECRET را با اعتبارهای خود جایگزین کنید.
curl -X POST "https://api.groupdocs.cloud/v2.0/oauth2/token" \
     -H "Content-Type: application/x-www-form-urlencoded" \
     -d "grant_type=client_credentials&client_id=YOUR_CLIENT_ID&client_secret=YOUR_CLIENT_SECRET"
  1. بارگذاری فایل DOCX منبع
curl -X PUT "https://api.groupdocs.cloud/v2.0/storage/file/document1.docx" \
     -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
     -H "Content-Type: application/octet-stream" \
     --data-binary "@path/to/document1.docx"
  1. بارگذاری فایل DOCX هدف
curl -X PUT "https://api.groupdocs.cloud/v2.0/storage/file/document2.docx" \
     -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
     -H "Content-Type: application/octet-stream" \
     --data-binary "@path/to/document2.docx"
  1. عملیات مقایسه را اجرا کنید
curl -X POST "https://api.groupdocs.cloud/v2.0/comparison/compare" \
     -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
     -H "Content-Type: application/json" \
     -d '{
           "sourceFile": { "filePath": "document1.docx" },
           "targetFiles": [{ "filePath": "document2.docx" }],
           "outputPath": "comparison_result.docx"
         }'
  1. دانلود فایل مقایسهٔ تولید شده
curl -X GET "https://api.groupdocs.cloud/v2.0/storage/file/comparison_result.docx" \
     -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
     -o comparison_result.docx

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

درک مقایسه اسناد Word در کد Node.JS

در زیر تجزیه و تحلیل گام به گام مثال کامل آورده شده است:

  1. وارد کردن SDK و ماژول‌های Node.js
const GroupDocsComparisonCloud = require("@groupdocs/comparison-cloud");
const fs = require("fs");
const path = require("path");

فضای نام GroupDocsComparisonCloud دسترسی به تمام کلاس‌های API را فراهم می‌کند.

  1. پیکربندی را با اعتبارهای کلاینت ایجاد کنید
const config = new GroupDocsComparisonCloud.Configuration(clientId, clientSecret);

این شیء هر درخواست API بعدی را احراز هویت می‌کند.

  1. ایجاد نمونه CompareApi و StorageApi
const compareApi = new GroupDocsComparisonCloud.CompareApi(config);
const storageApi = new GroupDocsComparisonCloud.StorageApi(config);

CompareApi مقایسه را انجام می‌دهد، در حالی که StorageApi مدیریت بارگذاری و حذف فایل‌ها را بر عهده دارد. برای جزئیات متدها، به مستندات API مراجعه کنید.

  1. بارگذاری فایل‌های DOCX منبع و هدف
const uploadSourceReq = new GroupDocsComparisonCloud.UploadFileRequest({
    path: sourceFileName,
    file: sourceData
});
await storageApi.uploadFile(uploadSourceReq);

الگوی مشابه برای فایل هدف تکرار می‌شود.

  1. پیکربندی CompareOptions و اجرای مقایسه
const compareOptions = new GroupDocsComparisonCloud.CompareOptions({
    sourceFile: new GroupDocsComparisonCloud.FileInfo({ filePath: sourceFileName }),
    targetFiles: [new GroupDocsComparisonCloud.FileInfo({ filePath: targetFileName })],
    outputPath: resultFileName,
});
const compareRequest = new GroupDocsComparisonCloud.CompareDocumentRequest({
    compareOptions: compareOptions
});
const compareResult = await compareApi.compareDocument(compareRequest);

CompareOptions به شما امکان می‌دهد عملیات را به‌دقت تنظیم کنید (مثلاً یک صفحه خلاصه تولید کنید). شیء نتیجه مسیر سند مقایسه‌ای تولید شده را شامل می‌شود.

  1. پاک‌سازی فایل‌های موقت (اختیاری)
await storageApi.deleteFile(new GroupDocsComparisonCloud.DeleteFileRequest({ path: sourceFileName }));
await storageApi.deleteFile(new GroupDocsComparisonCloud.DeleteFileRequest({ path: targetFileName }));

حذف نسخه‌های اصلی بارگذاری‌شده، فضای ذخیره‌سازی را منظم نگه می‌دارد.

پیش‌نیازها و راه‌اندازی برای GroupDocs.Comparison

  1. نسخه Node.js - اطمینان حاصل کنید که Node 14 یا بالاتر را اجرا می‌کنید.
  2. دریافت اعتبارهای مشتری - در پورتال GroupDocs Cloud ثبت‌نام کنید تا clientId و clientSecret را دریافت کنید.
  3. نصب SDK
npm install groupdocs-comparison-cloud
  1. (اختیاری) دانلود پروژه نمونه - می‌توانید مخزن را از GitHub page کلون کنید.
  2. پیکربندی محیط خود - اعتبارنامه‌ها را به‌عنوان متغیرهای محیطی تنظیم کنید یا جایگزین‌کننده‌ها را در کد جایگزین کنید.

برای دریافت فهرست کامل باینری‌های قابل دانلود، صفحهٔ صفحه دانلود.

بهترین روش‌ها برای مقایسه مؤثر اسناد Word

  • اعتبارسنجی فایل‌های ورودی - قبل از بارگذاری، اندازه و فرمت فایل را بررسی کنید تا از فراخوانی‌های غیرضروری API جلوگیری شود.
  • استفاده مجدد از جلسات ذخیره‌سازی - فایل‌ها را یک بار بارگذاری کنید و مسیرهای آن‌ها را برای مقایسه‌های متعدد استفاده مجدد کنید تا تاخیر کاهش یابد.
  • فعال‌سازی صفحه خلاصه فقط در صورت نیاز - ایجاد صفحه خلاصه زمان پردازش را افزایش می‌دهد؛ برای بررسی‌های ساده diff آن را غیرفعال کنید.
  • پردازش اسناد بزرگ به صورت ناهمزمان - برای فایل‌های DOCX بزرگ‌تر از ۱۰ مگابایت، به‌جای انتظار همزمان، وضعیت کار را به‌صورت polling بررسی کنید.
  • امنیت اعتبارنامه‌ها - clientId و clientSecret را در متغیرهای محیطی یا یک مدیر اسرار ذخیره کنید؛ هرگز به‌صورت سخت‌کد نشده نگهداری نکنید.

نتیجه‌گیری

مقایسه اسناد Word در Node.JS به‌سادگی انجام می‌شود با GroupDocs.Comparison Cloud SDK for Node.js. با دنبال کردن مراحل نصب، استفاده از مثال کد ارائه‌شده و به‌صورت اختیاری بهره‌گیری از REST API با cURL، می‌توانید مقایسه قدرتمند اسناد را به هر سرویس بک‌اندی یکپارچه کنید. به‌خاطر داشته باشید که اعتبارنامه‌های خود را ایمن کنید، فایل‌های موقت را پاک کنید و گزینه‌های مقایسه را برای عملکرد بهینه تنظیم کنید. برای استقرارهای تولیدی به نسخه دارای لایسنس نیاز خواهید داشت؛ جزئیات قیمت‌گذاری در صفحه محصول موجود است و می‌توانید برای ارزیابی یک لایسنس موقت از صفحه لایسنس موقت دریافت کنید. امروز شروع به آزمایش کنید و قابلیت‌های مقایسهٔ قابل اعتماد اسناد را به برنامه‌های Node.js خود اضافه کنید.

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

  • چگونه می‌توانم اسناد Word را در Node.JS بدون نوشتن کد مقایسه کنم؟
    می‌توانید از همان عملیات از طریق تماس‌های REST استفاده کنید. مثال‌های cURL در این مقاله توالی دقیق را نشان می‌دهند: احراز هویت، بارگذاری فایل‌ها، فراخوانی نقطه انتهایی مقایسه و دانلود نتیجه.

  • کدام فرمت‌های فایل برای مقایسه پشتیبانی می‌شوند؟
    SDK از DOCX، DOC، ODT، RTF، و TXT و سایر فرمت‌ها پشتیبانی می‌کند. تمام نام‌های فرمت به حروف بزرگ/کوچک حساس نیستند، اما در مرجع API به صورت حروف بزرگ (مثلاً DOCX) مستند شده‌اند.

  • آیا می‌توانم بیش از دو سند را همزمان مقایسه کنم؟
    بله. آرایه targetFiles در CompareOptions می‌تواند شامل چندین شیء FileInfo باشد، که به شما امکان می‌دهد یک فایل منبع را در یک درخواست در برابر چندین هدف مقایسه کنید.

  • آیا راهی برای سفارشی‌سازی سبک بصری نتیجه مقایسه وجود دارد؟
    SDK تنظیماتی مانند showDeletedContent، showInsertedContent و generateSummaryPage را ارائه می‌دهد. این ویژگی‌ها را در CompareOptions تنظیم کنید تا نحوه برجسته‌سازی تغییرات را کنترل کنید. برای دریافت فهرست کامل گزینه‌ها به مستندات رسمی مراجعه کنید.

بیشتر بخوانید