کاوش عمیق: الگوهای پیشرفته با Aspose.Cells Cloud Management API

شما می‌دانید چگونه یک workbook ایجاد کنید، یک sheet را تغییر نام دهید و یک فایل را فشرده کنید. اما ManagementController ابزارهای تیزتری دارد که در نگاه اول پنهان نیستند — یک dump کامل ساختاری JSON از یک workbook، بررسی merged‑cell، پذیرش revision، و الگوی ایجاد مبتنی بر template که استایل‌دهی را به یک نگرانی یک‌خطی تبدیل می‌کند. اینجاست که housekeeping دیگر «کلیک کردن در Excel» نیست و به بهداشت برنامه‌نویسی workbook تبدیل می‌شود.

در قسمت 1 ما ۱۵ نقطه انتهایی را با راهنمایی‌های واضح پوشش دادیم. این پست برای موقعیت‌هایی است که در واقع در تولید مشکل‌ساز می‌شوند:

• شما باید قبل از پردازش یک کتاب‌کار audit کنید — آیا جدول‌های محوری، نمودارها، نواحی ادغام‌شده‌ای دارد که می‌تواند کد شما را دچار مشکل کند؟
• شما باید قبل از ورود به خط لوله بایگانی، accept tracked changes را بر روی صدها فایل اعمال کنید.
• شما می‌خواهید build a templating system ای داشته باشید که در آن مستأجران مختلف خروجی‌های برند شده متفاوتی دریافت کنند بدون اینکه کد استایل‌نویسی بنویسید.
• شما باید inspect merged-cell regions را بررسی کنید تا از نوشتن داده در آن‌ها جلوگیری کنید (یا برای درک چیدمان کتاب‌کاری که خودتان ننوشته‌اید).
• شما می‌خواهید عملیات create → structure → modify → compress را در یک workbook factory ترکیب کنید.

هر مثال زیر قابل اجرا است. کدها در cURL هستند؛ همان فراخوانی‌ها به صورت 1:1 به SDKهای .NET، Python و Java نقشه‌برداری می‌شوند.

1. دریافت ساختار کامل یک دفتر کار به صورت JSON

PUT /v4.0/cells/spreadsheet/structure (محلی) و GET /v4.0/cells/{name}/structure (دور) یک سند JSON تک را برمی‌گردانند که همه چیز را که موتور دربارهٔ کتاب‌کار می‌داند توصیف می‌کند: ورق‌های کاری، جداول، جداول محوری، نمودارها، اشکال، نواحی ادغام‌شدهٔ سلول‌ها، و موارد دیگر.

محلی

curl -X PUT "https://api.aspose.cloud/v4.0/cells/spreadsheet/structure" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: multipart/form-data" \
  -F "file=@mystery_workbook.xlsx"

دور

curl -X GET "https://api.aspose.cloud/v4.0/cells/mystery_workbook.xlsx/structure?folder=uploads" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

آنچه دریافت می‌کنید

{
  "FileName": "mystery_workbook.xlsx",
  "FileFormat": "Xlsx",
  "Worksheets": [
    {
      "Name": "Sheet1",
      "Type": "Worksheet",
      "Tables": [{ "Name": "SalesData", "Range": "A1:D120" }],
      "PivotTables": [{ "Name": "Pivot1", "Range": "F1:H20" }],
      "Charts": [{ "Name": "Chart1", "Type": "Column" }],
      "MergedCells": [
        { "StartRow": 0, "StartColumn": 0, "EndRow": 0, "EndColumn": 3 }
      ]
    }
  ]
}

چرا این مهم است

• اعتبارسنجی پیش‌پروازی. قبل از اجرای واردات DataProcessingController بر روی یک کتاب‌کار، structure را فراخوانی کنید تا وجود واقعی برگه هدف و جدول را تأیید کنید.
• کشف طرح‌بندی. با کتاب‌کاری که خودتان آن را نساخته‌اید کار می‌کنید؟ structure دقیقاً به شما می‌گوید داخل آن چه چیزی است بدون اینکه آن را دانلود کنید و در اکسل جستجو کنید.
• رندر UI. یک انتخابگر برگه / جدول / نمودار را در برنامه خود مستقیماً از پاسخ structure هدایت کنید.

2. بررسی نواحی سلول‌های ادغام‌شده

سلول‌های ترکیب‌شده قاتل‌های ساکت خودکارسازی صفحات‌گسترده هستند — نوشتن در یک ناحیه ترکیب‌شده می‌تواند به‌صورت ساکت کل ناحیه را بازنویسی کند یا خطاهای رمزآلودی ایجاد کند. ManagementController دو نقطه انتهایی برای پرس‌و‌جو دربارهٔ آن‌ها ارائه می‌دهد.

کاربرگ محلی

curl -X PUT "https://api.aspose.cloud/v4.0/cells/spreadsheet/mergedcells?worksheet=Sheet1" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -F "file=@my_workbook.xlsx"

کاربرگ از راه دور

curl -X GET "https://api.aspose.cloud/v4.0/cells/my_workbook.xlsx/worksheets/Sheet1/mergedcells?folder=uploads" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

پاسخ

[
  { "StartRow": 0, "StartColumn": 0, "EndRow": 0, "EndColumn": 3 },
  { "StartRow": 5, "StartColumn": 1, "EndRow": 7, "EndColumn": 1 }
]

هر ورودی یک CellArea است — یک مستطیل در مختصات ردیف/ستون. اولین ناحیه در بالا یک سرصفحه است که در بازه A1–D1 ادغام شده است؛ دومین ناحیه یک ادغام عمودی در B6–B8 است.

از آن برای جلوگیری از مین‌های زمینی استفاده کنید

قبل از نوشتن داده‌ها در یک برگه کاری (از طریق وارد کردن CellsController یا DataProcessingController)، این نقطهٔ انتهایی را فراخوانی کنید و هر مقدار startcell که در داخل یک ناحیهٔ ادغام‌شده قرار دارد فیلتر کنید. یا به‌عکس، از نواحی ادغام‌شده برای کشف ردیف‌های سرصفحه و عناوین بخش به‌صورت برنامه‌نویسی استفاده کنید.

3. پذیرش تغییرات ردیابی‌شده (بازنگری‌ها)

وقتی همکاران در Excel گزینه “Track Changes” را فعال می‌کنند، هر ویرایش به یک revision تبدیل می‌شود — تغییری در انتظار با نویسنده، زمان‌مهر و وضعیت پذیرش/رد. اگر خط لوله شما این فایل‌ها را پردازش می‌کند و به نسخه‌های تمیز و نهایی نیاز دارد، دو گزینه دارید:

• محلی: PUT /v4.0/cells/spreadsheet/accept-all-revisions
• دور: PUT /v4.0/cells/{name}/accept-all-revisions

محلی

curl -X PUT "https://api.aspose.cloud/v4.0/cells/spreadsheet/accept-all-revisions" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -F "file=@collaborative_draft.xlsx" \
  --output finalized.xlsx

دور

curl -X PUT "https://api.aspose.cloud/v4.0/cells/collaborative_draft.xlsx/accept-all-revisions?folder=drafts" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  --output finalized.xlsx

پس از این فراخوانی، سند دیگر علامت‌گذاری تغییرات ردیابی‌شده را نشان نمی‌دهد. تمام ویرایش‌ها به‌گونه‌ای ترکیب می‌شوند که گویی مستقیماً در نسخه نهایی تایپ شده‌اند.

جریان کار انبوه

با استفاده از APIهای فهرست‌گذاری فایل در ارائه‌دهندهٔ ذخیره‌سازی خود، هر فایل در یک پوشه را پردازش کنید:

for name in $(list_files_in drafts/); do
  curl -X PUT "https://api.aspose.cloud/v4.0/cells/$name/accept-all-revisions?folder=drafts" \
    -H "Authorization: Bearer $TOKEN"
done

(کد تولید واقعی از SDK استفاده می‌کند و با async/await به صورت موازی اجرا می‌شود — فراخوانی REST یکسان است.)

4. ایجاد مبتنی بر قالب در مقیاس

template پارامتر در spreadsheet/create بیش از یک راحتی است — این پایهٔ یک سیستم قالب‌سازی است. سرور قالب کتاب‌کار را بارگذاری می‌کند، تم، سبک‌ها، محدوده‌های نام‌گذاری‌شده و هر جدول پیش‌فرمت‌شده‌ای را کپی می‌کند و یک کتاب‌کار تازه برمی‌گرداند که می‌توانید بلافاصله با داده‌ها از طریق DataProcessingController/import/data پر کنید.

الگو: یک قالب برای هر مستاجر

قالب‌ها را در ذخیره‌سازی ابری در مسیر کلید‌دار مستأجر ذخیره کنید:

templates/tenant_acme/invoice.xlsx
templates/tenant_globex/invoice.xlsx
templates/tenant_initech/invoice.xlsx

وقتی سیستم یک مستأجر فاکتور تولید می‌کند:

# 1) Create from tenant template
curl -X PUT "https://api.aspose.cloud/v4.0/cells/spreadsheet/create\
?format=xlsx\
&template=templates/tenant_acme/invoice.xlsx" \
  -H "Authorization: Bearer $TOKEN" \
  --output blank_acme.xlsx

# 2) Hydrate with this invoice's line items
curl -X PUT "https://api.aspose.cloud/v4.0/cells/import/data/json\
?worksheet=Items\
&startcell=A10\
&insert=true" \
  -H "Authorization: Bearer $TOKEN" \
  -F "file=@blank_acme.xlsx" \
  -F "file=@line_items.json" \
  --output invoice_ACME_2026_09_001.xlsx

هر مستأجر خروجی پیکسل‌دقیق در برند خود دریافت می‌کند — بدون منطق استایل در کد شما.

الگو: کارخانه گزارش

یک کار شبانه باید ۳۰ گزارش منطقه‌ای تولید کند، همه با همان طرح اما داده‌های متفاوت:

for region in north south east west ...; do
  create(template=regional_template.xlsx) |
  import(data=region_$region.csv, worksheet=Data, startcell=A2) |
  compress(level=6) |
  save("reports/2026/09/$region.xlsx")
done

هر مرحلهٔ لوله یک فراخوانی API است. کل کارخانه در یک حلقهٔ شل جای می‌گیرد.

5. فشرده‌سازی با هدف

PUT /v4.0/cells/spreadsheet/compress?level=N هر سطحی از ۰ تا ۹ را می‌پذیرد. انتخاب سطح مناسب تصمیم کوچکی است که اثرات بعدی دارد.

یک فشرده‌سازی سطح‑6 بر روی یک فایل XLSX 30 مگابایتی معمولاً به حدود 8 تا 12 مگابایت می‌رسد. سطح 9 اغلب حدود 10 تا 15٪ دیگر را استخراج می‌کند، با هزینه تقریباً دو برابر پردازنده. برای اکثر برنامه‌ها، level=6 نقطهٔ بهینه است.

6. تعمیر: آنچه واقعاً انجام می‌دهد

PUT /v4.0/cells/spreadsheet/repair به‌طور عمدی ساده است — بدون پارامتر، بدون پیکربندی. در پشت صحنه این کار:

1. کاربرگ را از طریق خوانندهٔ سخت‌گیرانهٔ موتور تجزیه می‌کند.
2. قسمت‌های ساختاری نامعتبر (روابط یتیم، XML خراب، ارجاعات سلول نامعتبر) را حذف می‌کند.
3. به‌صورت جدید به یک محفظهٔ XLSX تازه سریال‌سازی می‌کند.

نتیجه یک فایل است که به‌راحتی در Excel باز می‌شود. آنچه نمی‌تواند اصلاح کند: فساد در سطح داده (یک سلول که مقدار آن #REF! است به‌دلیل فرمول خراب)، تصاویر از دست رفته (اگر جریان تصویر خود خراب باشد)، یا ماکروهای VBA از دست رفته (اگر vbaProject.bin قابل خواندن نباشد). اما برای 80٪ موارد — “Excel می‌گوید این فایل خراب است و پیشنهاد می‌دهد آن را تعمیر کند” — این نقطه انتهایی همان تعمیر را به‌صورت سرور‑ساید، بدون رابط گرافیکی انجام می‌دهد.

زمان اجرای تعمیر

• در زمان دریافت. اگر برنامه شما بارگذاری‌های کاربر را می‌پذیرد، قبل از هر پردازش دیگری repair را اجرا کنید. هزینه‌ی یک تماس اضافی است، اما از بروز خطاهای زنجیره‌ای در ادامه‌ی خط لوله جلوگیری می‌کند.
• در صورت شکست‌های خروجی. اگر یک تبدیل پایین‌دستی (ConversionController) با خطای مبهمی شکست بخورد، ابتدا repair را اجرا کنید، سپس تبدیل را دوباره امتحان کنید.

7. الگوهای یکپارچه‌سازی

الگو: کارخانه کتاب‌کار

تمام قابلیت‌های ManagementController را در یک نقطهٔ کارخانه‌ای در برنامهٔ خود ترکیب کنید:

POST /api/reports/{tenantId}
  1. Create from template: templates/{tenantId}/report.xlsx
  2. Import data into the "Data" sheet starting at A2
  3. Rename "Sheet1" → "Cover"
  4. Accept all revisions (in case template had tracked changes)
  5. Compress level 6
  6. Return final XLSX

هر مرحله یک فراخوانی API به ManagementController یا DataProcessingController است. نقطه انتهای شما یک هماهنگ‌کننده نازک است.

الگو: audit-before-process

قبل از اجرای عملیات پرهزینه در سطح سلول:

[1] GET {name}/structure            # understand what's inside
[2] GET {name}/worksheets/X/mergedcells  # know where NOT to write
[3] DataProcessing/...              # run the real work

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

8. ملاحظات عملکرد

• structure ارزان است. متادیتا را پیمایش می‌کند، نه محتوای سلول‌ها. در کتاب‌های کاری بزرگ به‌صورت ایمن قابل فراخوانی است.
• mergedcells ارزان است. همان دلیل.
• compress وابسته به CPU است. سطوح بالاتر هزینه بیشتری دارند. سطح ۶ را به‌عنوان پیش‌فرض استفاده کنید مگر اینکه دلیلی برای افزایش داشته باشید.
• repair یک بازسری کامل است. نسبت به compress گران‌تر است. آن را در زمان ورود داده اجرا کنید، نه در هر درخواست.
• accept-all-revisions با تعداد بازنگری‌ها مقیاس می‌شود. صدها بازنگری در یک فایل مشکلی نیست؛ ده‌ها هزار بازنگری کمی زمان می‌برد.
• نسخه‌های راه دور از رفت و برگشت‌های محلی پیشی می‌گیرند. وقتی فایل‌ها از پیش در ذخیره‌سازی ابری هستند، GET {name}/structure از دانلود فایل به ماشین شما فقط برای بررسی آن جلوگیری می‌کند.

9. عیب‌یابی مشکلات رایج

10. جمع‌بندی همه موارد

پایان‌نقاط ManagementController به‌صورت جداگانه کوچک هستند. قدرت آن‌ها از ترکیب ناشی می‌شود:

• ایجاد یک workbook از یک template → وارد کردن data via DataProcessingController → تغییر نام sheets → فشرده‌سازی → deliver. این یک full SaaS report pipeline در پنج HTTP call است.
• ساختار + mergedcells + cells → یک لایه بازرسی که هر workbook را که به آن می‌اندازید، بدون Excel می‌فهمد.
• تعمیر on ingest → accept-all-revisions → بقیه pipeline شما فقط workbookهای تمیز و نهایی را می‌بیند.

به یک سرور فارم نیازی ندارید. به نصب Excel نیازی ندارید. به curl و یک برنامه نیاز دارید.