استخراج فراداده از فایل‌های صفحه‌گسترده یک نیاز مکرر هنگام ساخت برنامه‌های Java مبتنی بر داده است، به‌ویژه برای سناریوهای حسابرسی، ایندکس‌گذاری جستجو یا مهاجرت داده. GroupDocs.Metadata Cloud SDK for Java یک API قدرتمند فراهم می‌کند که این فرآیند را بدون نیاز به مدیریت منطق پیچیده تجزیه فایل ساده می‌سازد. در این راهنما خواهید آموخت که چگونه Metadata را از XLS در Java استخراج کنید، یک مثال کامل عملی را ببینید، تماس‌های cURL برای REST API را بررسی کنید، و بهترین روش‌ها برای عملکرد، مدیریت خطا و امنیت را اتخاذ کنید.

مراحل استخراج متادیتا از XLS در جاوا

  1. Create a MetadataApi instance - کلاینت را با client‑id و client‑secret خود مقداردهی اولیه کنید. این شی برای تمام فراخوانی‌های بعدی استفاده خواهد شد.
    MetadataApi metadataApi = new MetadataApi(clientId, clientSecret);
  2. Upload the XLS file - از Storage API برای قرار دادن فایل در فضای ذخیره‌سازی GroupDocs خود استفاده کنید.
    storageApi.uploadFile("input.xls", Files.readAllBytes(Paths.get("src/main/resources/input.xls")));
  3. Call the Get Document Metadata endpoint - متادیتای فایل بارگذاری‌شده را درخواست کنید.
    MetadataInfo metadata = metadataApi.getDocumentMetadata("input.xls");
  4. Iterate over the metadata collection - پاسخ شامل فهرستی از جفت‌های کلید‑مقدار است که می‌توانید آن‌ها را لاگ کنید یا پردازش بیشتری انجام دهید.
    for (MetadataProperty prop : metadata.getProperties()) {
    System.out.println(prop.getName() + ": " + prop.getValue());
}
  5. Handle exceptions and clean up - فراخوانی‌ها را در بلوک‌های try‑catch بپیچید و هر استریمی را ببندید. برای انواع استثناهای دقیق به API reference مراجعه کنید.

استخراج متادیتا از XLS در جاوا - مثال کامل کد

مثال زیر یک جریان کاری کامل از ابتدا تا انتها را نشان می‌دهد، از احراز هویت تا خروجی متادیتا.

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

استخراج متادیتا از طریق REST API با استفاده از cURL

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

ابتدا یک توکن دسترسی دریافت کنید:

curl -X POST "https://api.groupdocs.cloud/v2.0/connect/token" \
     -H "Content-Type: application/x-www-form-urlencoded" \
     -d "grant_type=client_credentials&client_id=YOUR_CLIENT_ID&client_secret=YOUR_CLIENT_SECRET"

سپس، فایل XLS را بارگذاری کنید:

curl -X PUT "https://api.groupdocs.cloud/v2.0/storage/file/sample.xls" \
     -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
     -H "Content-Type: application/octet-stream" \
     --data-binary "@path/to/sample.xls"

درخواست متادیتا برای فایل بارگذاری شده:

curl -X GET "https://api.groupdocs.cloud/v2.0/metadata/sample.xls" \
     -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

در نهایت، پاسخ را (اختیاری) دانلود کنید یا خروجی JSON را مستقیماً در برنامه خود پردازش کنید. برای جزئیات بیشتر، به مستندات رسمی API مراجعه کنید.

نصب و راه‌اندازی در جاوا

  1. افزودن وابستگی Maven - کتابخانه را در pom.xml خود اضافه کنید:
   <dependency>
       <groupId>com.groupdocs</groupId>
       <artifactId>groupdocs-metadata-cloud</artifactId>
       <version>latest</version>
   </dependency>
  1. نصب بسته - دستور زیر را در دایرکتوری پروژه خود اجرا کنید:
   mvn install com.groupdocs:groupdocs-metadata-cloud

  1. آخرین نسخه را دانلود کنید - همچنین می‌توانید فایل‌های JAR را از صفحه دانلود دریافت کنید.

  2. پیکربندی اعتبارها - client_id و client_secret را به‌صورت ایمن ذخیره کنید، به‌عنوان مثال در متغیرهای محیطی یا یک فایل پیکربندی محافظت‌شده.

  3. تأیید نصب - یک درخواست ساده “Hello World” به Storage API اجرا کنید تا قبل از ادامه استخراج متادیتا، اتصال را تضمین کنید.

ویژگی‌های کلیدی GroupDocs.Metadata Cloud SDK برای جاوا

  • پشتیبانی کامل دوره‌ای متادیتا برای XLS، XLSX، DOC، PDF و بسیاری از فرمت‌های دیگر.
  • پردازش مبتنی بر ابر نیاز به نصب‌های محلی Office را از بین می‌برد.
  • مدل ویژگی‌های غنی دسترسی به هر دو فیلد متادیتای استاندارد و سفارشی را فراهم می‌کند.
  • پردازش دسته‌ای امکان استخراج از چندین فایل در یک درخواست را فراهم می‌کند.
  • نقاط انتهایی امن REST با احراز هویت OAuth 2.0.

بهینه‌سازی عملکرد برای استخراج متادیتا

  • استفاده مجدد از کلاینت API در چندین فراخوانی برای جلوگیری از درخواست‌های توکن مکرر.
  • فعال‌سازی بارگذاری استریمینگ برای فایل‌های بزرگ XLS به منظور کاهش مصرف حافظه.
  • محدود کردن فیلدهای بازگشتی با تعیین فیلتر ویژگی وقتی که فقط به زیرمجموعه‌ای از متادیتا نیاز دارید.
  • همزمان‌سازی درخواست‌ها با استفاده از Java’s CompletableFuture برای پردازش همزمان چندین فایل، با رعایت محدودیت‌های نرخ API.

مدیریت خطاها و عیب‌یابی

  • Authentication failures - بررسی کنید که client_id و client_secret صحیح هستند و نقطهٔ انتهای توکن در دسترس است.
  • File not found - اطمینان حاصل کنید مسیر فایل در درخواست ذخیره‌سازی با نام بارگذاری شده مطابقت دارد، از جمله حساسیت به حروف بزرگ و کوچک.
  • Unsupported format - API کد وضعیت 415 را برمی‌گرداند؛ تأیید کنید که فایل یک کتاب کار XLS معتبر است.
  • Rate limiting - اگر پاسخ 429 دریافت کردید، قبل از تلاش مجدد از روش بازگشت نمایی استفاده کنید.

بهترین روش‌ها برای کار با فایل‌های XLS بزرگ

  • بارگذاری قطعه‌ای - فایل‌های بزرگ‌تر از ۵۰ مگابایت را به بخش‌های کوچکتر تقسیم کنید با استفاده از API بارگذاری چندبخشی.
  • کش کردن متادیتا - متادیتای استخراج‌شده را در یک پایگاه داده محلی ذخیره کنید تا از فراخوانی‌های مکرر API برای همان فایل جلوگیری شود.
  • اعتبارسنجی ورودی - قبل از بارگذاری، اعتبارسنجی پایه نوع فایل را انجام دهید تا از ترافیک غیرضروری شبکه جلوگیری شود.
  • نظارت بر استفاده - از داشبورد GroupDocs برای ردیابی مصرف API استفاده کنید و هشدارهایی برای افزایش غیرعادی تنظیم کنید.

Security Considerations When Processing XLS Metadata

  • امنیت انتقال - تمام تماس‌های API از طریق HTTPS انجام می‌شوند؛ هرگز به HTTP کاهش ندهید.
  • اعتبارهای کم‌سطح - یک کلاینت اختصاصی با فقط دامنه Metadata.Read ایجاد کنید.
  • اقامت داده - برای رعایت مقررات حفاظت از داده‌های محلی، منطقه ذخیره‌سازی مناسب را انتخاب کنید.
  • پاک‌سازی خروجی - متادیتای استخراج‌شده را به عنوان ورودی غیرقابل اعتماد در نظر بگیرید؛ قبل از رندر در اجزای UI، هر مقدار را Escape کنید.

نتیجه‌گیری

استخراج متادیتا از XLS در جاوا با استفاده از GroupDocs.Metadata Cloud SDK for Java ساده می‌شود. با دنبال کردن راهنمای گام‌به‌گام، می‌توانید استخراج متادیتا را در هر خط لوله پردازش سند مبتنی بر جاوا یکپارچه کنید، از مقیاس‌پذیری ابری بهره‌مند شوید و برنامه خود را ایمن نگه دارید. به‌خاطر داشته باشید که برای استفاده در محیط تولید، یک لایسنس مناسب تهیه کنید؛ می‌توانید یک پلن خریداری کنید یا لایسنس موقت را از صفحه لایسنس موقت دریافت کنید. کدنویسی خوش!

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

چگونه می‌توانم متادیتا را از فایل XLS در جاوا استخراج کنم بدون نوشتن کدهای تکراری زیاد؟
SDK فراخوانی‌های HTTP سطح پایین را انتزاع می‌کند. پس از مقداردهی اولیه MetadataApi با اعتبارهای خود، یک فراخوانی واحد متد (getDocumentMetadata) تمام متادیتاهای فایل XLS مشخص شده را برمی‌گرداند.

آیا می‌توانم متادیتا را از فایل‌های XLS رمزگذاری‌شده استخراج کنم؟
بله، API از کتاب‌کارهای محافظت‌شده با رمز عبور پشتیبانی می‌کند. رمز عبور را به‌عنوان پارامتر در درخواست متادیتا ارسال کنید؛ برای نام دقیق فیلد به مستندات مراجعه کنید.

چه محدودیتی برای تعداد فایل‌هایی که می‌توانم در روز پردازش کنم اعمال می‌شود؟
محدودیت‌ها به سطح اشتراک شما بستگی دارد. داشبورد استفاده، سهمیه‌های فعلی را نشان می‌دهد و می‌توانید از طریق کانال فروش GroupDocs درخواست محدودیت‌های بالاتر کنید.

آیا می‌توان فقط فیلدهای متادیتای سفارشی را بازیابی کرد؟
می‌توانید پاسخ را با مشخص کردن فهرستی از نام‌های ویژگی در بار درخواست فیلتر کنید. این کار اندازه بار را کاهش داده و پردازش اسناد بزرگ را سرعت می‌بخشد.

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