کار با ویژگیهای سند برای مدیریت منظم محتوا ضروری است. GroupDocs.Metadata Cloud SDK for Java به توسعهدهندگان جاوا امکان ویرایش متادیتای سند Word بهصورت برنامهنویسی را میدهد و یک API ساده برای خواندن و بهروزرسانی فیلدهای اصلی و سفارشی ارائه میکند. این راهنما نشان میدهد چگونه متادیتای سند Word را در جاوا ویرایش کنیم، شامل تنظیمات، پیادهسازی کد، نکات پردازش دستهای و عیبیابی رایج.
ویرایش متادیتای سند Word - پیشنیازها و تنظیمات
برای شروع استفاده از کتابخانه، به Java 8 یا بالاتر و Maven نصب شده بر روی ماشین توسعه خود نیاز دارید.
نصب
SDK را با مختصات Maven ارائهشده توسط GroupDocs به پروژه خود اضافه کنید:
<dependency>
<groupId>com.groupdocs</groupId>
<artifactId>groupdocs-metadata-cloud</artifactId>
<version>latest</version>
</dependency>
بهجای آن میتوانید نصبکننده خط فرمان را اجرا کنید:
mvn install com.groupdocs:groupdocs-metadata-cloud
جدیدترین باینریها را از این صفحه دانلود کنید. پس از افزودن وابستگی، کلاینت خود را با شناسه کلاینت و رمز کلاینت (در دسترس در حساب GroupDocs شما) پیکربندی کنید.
import com.groupdocs.metadata.cloud.ApiClient;
import com.groupdocs.metadata.cloud.Configuration;
Configuration config = new Configuration();
config.setClientId("YOUR_CLIENT_ID");
config.setClientSecret("YOUR_CLIENT_SECRET");
ApiClient apiClient = new ApiClient(config);
برای گزینههای پیکربندی دقیق، به مستندات رسمی مراجعه کنید.
ویرایش متادیتای سند Word در Java
SDK از خواندن و نوشتن ویژگیهای اصلی (Title, Author, Subject و غیره) و همچنین ویژگیهای سفارشی تعریفشده توسط کاربر پشتیبانی میکند. این استاندارد Office Open XML را دنبال میکند تا سازگاری با Microsoft Word و سایر ویرایشگرها را تضمین کند.
ویژگیهای کلیدی GroupDocs.Metadata Cloud SDK for Java
- مدیریت ویژگیهای اصلی - دسترسی و اصلاح فیلدهای داخلی مانند عنوان، سازنده و کلیدواژهها.
- پشتیبانی از ویژگیهای سفارشی - افزودن، بهروزرسانی یا حذف فرادادههای تعریفشده توسط کاربر.
- مدیریت دستهبندی - مدیریت برنامهنویسی دستههای سند، ویژگی مفیدی برای طبقهبندی محتوا.
- عملیاتهای دستهای - پردازش تعداد زیادی فایل در یک درخواست برای بهبود عملکرد.
- گزارشگیری خطا - استثناهای دقیق به شناسایی ویژگیهای گمشده یا مشکلات دسترسی کمک میکنند.
پیکربندی فیلدهای متادیتا با GroupDocs.Metadata Cloud SDK
از کلاس DocumentInfo برای بازیابی و تنظیم مقادیر ویژگیها استفاده کنید. مرجع API جزئیات کامل هر متد را فراهم میکند: DocumentInfo Class.
import com.groupdocs.metadata.cloud.model.requests.*;
import com.groupdocs.metadata.cloud.model.*;
DocumentInfoRequest request = new DocumentInfoRequest("sample.docx");
DocumentInfoResponse response = apiClient.getDocumentInfo(request);
DocumentInfo info = response.getInfo();
// Update core properties
info.setTitle("Quarterly Report");
info.setAuthor("John Doe");
// Add a custom property
info.getCustomProperties().add(new CustomProperty("ProjectCode", "PRJ-2026"));
مدیریت ویژگیهای سفارشی و دستهها
خواص سفارشی به صورت جفتهای کلید‑مقدار ذخیره میشوند. همچنین میتوانید دستهبندیها را برای کمک به سازماندهی سند اختصاص دهید.
// Add a new category
info.getCategories().add("Finance");
// Update an existing custom property
info.getCustomProperties().stream()
.filter(p -> p.getName().equals("ProjectCode"))
.findFirst()
.ifPresent(p -> p.setValue("PRJ-2027"));
بهینهسازی عملکرد برای بهروزرسانیهای دستهجمعی متادیتا
هنگام بهروزرسانی متادیتا برای اسناد متعدد، همان نمونه ApiClient را مجدداً استفاده کنید و از نقطه انتهایی bulk بهره ببرید.
BulkUpdateRequest bulkRequest = new BulkUpdateRequest();
bulkRequest.addFile("doc1.docx", info1);
bulkRequest.addFile("doc2.docx", info2);
// ... add more files
BulkUpdateResponse bulkResponse = apiClient.bulkUpdateMetadata(bulkRequest);
پردازش فایلها در رشتههای موازی میتواند زمان کل اجرا را بیشتر کاهش دهد.
عیبیابی مشکلات رایج در ویرایش متادیتا
- Missing Property Exception - اطمینان حاصل کنید که نام ویژگی به درستی نوشته شده و در سند وجود دارد.
- Permission Errors - اطمینان حاصل کنید که کلاینت API دسترسی نوشتن به مکان ذخیرهسازی دارد.
- Unsupported Format - SDK با DOCX کار میکند؛ فایلهای قدیمیتر DOC باید ابتدا تبدیل شوند.
مراحل ویرایش فراداده سند Word در Java
- مقداردهی اولیه کلاینت API - اعتبارهای کلاینت خود را فراهم کنید و یک نمونه
ApiClientایجاد کنید. - بارگذاری سند Word - از
DocumentInfoRequestبرای دریافت متادیتای موجود استفاده کنید. - ویرایش فیلدهای اصلی و سفارشی - مقدارها را بر روی شیء
DocumentInfoهمانطور که در مثالها نشان داده شده تنظیم کنید. - ذخیره تغییرات - متد
UpdateDocumentMetadataرا فراخوانی کنید تا متادیتای بهروزرسانیشده را به فایل بازگردانید. - تأیید بهروزرسانی - اطلاعات سند را دوباره بازیابی کنید تا تأیید شود که تغییرات اعمال شدهاند.
برای جزئیات بیشتر در مورد هر کلاس، به مرجع API مراجعه کنید.
ویرایش متادیتای سند Word در Java - مثال کامل کد
مثال زیر یک جریان کاری کامل را نشان میدهد که یک فایل DOCX را میخواند، چندین فیلد متادیتا را بهروزرسانی میکند و نتیجه را ذخیره مینماید.
توجه: این مثال کد عملکرد اصلی را نشان میدهد. قبل از استفاده از آن در پروژه خود، مطمئن شوید مسیرهای فایل (
sample.docx) را به مکانهای واقعی خود بهروز کنید، اطمینان حاصل کنید تمام وابستگیهای مورد نیاز بهدرستی نصب شدهاند، و بهطور کامل در محیط توسعه خود تست کنید. اگر با مشکلی مواجه شدید، لطفاً به مستندات رسمی مراجعه کنید یا برای دریافت کمک به تیم پشتیبانی مراجعه کنید.
مدیریت متادیتای سند از طریق REST API با استفاده از cURL
همین عملیات میتوانند از طریق REST API ابری انجام شوند. در زیر دستورات cURL ضروری آورده شده است.
1. احراز هویت و دریافت توکن دسترسی
curl -X POST "https://api.groupdocs.cloud/v1.0/auth/login" \
-H "Content-Type: application/json" \
-d '{"client_id":"YOUR_CLIENT_ID","client_secret":"YOUR_CLIENT_SECRET"}'
۲. بارگذاری فایل Word منبع
curl -X POST "https://api.groupdocs.cloud/v1.0/storage/upload" \
-H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
-F "file=@/path/to/sample.docx"
3. بهروزرسانی فراداده (ویژگیهای اصلی و سفارشی)
{
"title": "Annual Financial Summary",
"author": "Finance Team",
"customProperties": [
{ "name": "Department", "value": "Finance" }
],
"categories": ["Financial Reports"]
}
curl -X PUT "https://api.groupdocs.cloud/v1.0/metadata/docx/sample.docx" \
-H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
-H "Content-Type: application/json" \
-d @metadata_update.json
4. فایل بهروزرسانیشده را دانلود کنید
curl -X GET "https://api.groupdocs.cloud/v1.0/storage/download/sample.docx" \
-H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
-o updated_sample.docx
برای مشخصات کامل API به مرجع API مراجعه کنید.
نتیجهگیری
ویرایش متادیتای سند Word بهصورت برنامهنویسی در Java بهسادگی با GroupDocs.Metadata Cloud SDK for Java امکانپذیر میشود. میتوانید ویژگیهای اصلی را تغییر دهید، فیلدهای سفارشی اضافه کنید و دستهبندیها را بهصورت کارآمد مدیریت کنید، حتی هنگام پردازش دستههای بزرگ. بهخاطر داشته باشید که برای استفاده در محیط تولید، یک لایسنس مناسب دریافت کنید؛ جزئیات قیمتگذاری در صفحه محصول موجود است و میتوانید یک لایسنس موقت را از صفحه لایسنس موقت دریافت کنید. این روشها را در مدیریت محتوا یا خطوط پردازش سند خود ادغام کنید تا فایلهای خود را بهخوبی سازماندهی و قابل جستجو نگه دارید.
سؤالات متداول
چگونه عنوان سند را بدون تأثیر بر سایر ویژگیها بهروزرسانی کنم؟
Use the setTitle method on the DocumentInfo object. The SDK updates only the specified field, leaving all other metadata untouched.
آیا میتوانم یک ویژگی سفارشی که دیگر نیازی به آن نیست را حذف کنم؟
بله، مجموعه CustomProperties را بازیابی کنید، ویژگی را بر اساس نام پیدا کنید و متد remove را فراخوانی کنید. تغییر پس از فراخوانی updateDocumentMetadata ذخیره میشود.
آیا راهی برای ویرایش دستهای متادیتا برای دهها فایل Word وجود دارد؟
SDK یک نقطه انتهایی بهروزرسانی دستهای فراهم میکند که چندین فایل را در یک درخواست میپذیرد. این کار بار شبکه را کاهش داده و سرعت پردازش را افزایش میدهد.
کجا میتوانم مثالهایی برای مدیریت دستهبندیهای متادیتا پیدا کنم؟
مستندات رسمی شامل قطعه کد برای افزودن و حذف دستهبندیها و همچنین توصیههای بهترین روش برای عملیات در مقیاس بزرگ است.