استكشاف متعمق: الأنماط المتقدمة مع Aspose.Cells Cloud Management API

أنت تعرف كيف تنشئ دفتر عمل، وتعيد تسمية ورقة، وتضغط ملفًا. لكن ManagementController يحتوي على أدوات أكثر حدة مخفية في العلن — تفريغ JSON كامل للهيكلية لدفتر العمل، فحص الخلايا المدمجة، قبول المراجعات، ونمط الإنشاء القائم على القالب الذي يحول التنسيق إلى مسألة سطر واحد. هنا يتوقف التنظيم عن كونه “clicking around in Excel” ويبدأ كـ نظافة دفتر العمل برمجياً.

في الجزء 1 غطينا 15 نقطة نهاية مع شروحات واضحة. هذه المشاركة مخصصة للمواقف التي تسبب مشاكل فعلية في الإنتاج:

• تحتاج إلى audit مصنف قبل معالجته — هل يحتوي على جداول محورية، مخططات، مناطق مدمجة قد تتسبب في أخطاء في الكود الخاص بك؟
• تحتاج إلى accept tracked changes على مئات الملفات قبل أن تدخل إلى خط أنابيب الأرشفة الخاص بك.
• تريد build a templating system حيث يحصل المستأجرون المختلفون على مخرجات ذات علامة تجارية مختلفة دون كتابة كود تنسيق.
• تحتاج إلى inspect merged-cell regions لتجنب كتابة البيانات فيها (أو لفهم تخطيط المصنف الذي لم تقم بإنشائه).
• تريد ربط إنشاء → بنية → تعديل → ضغط في workbook factory واحدة.

كل مثال أدناه قابل للتنفيذ. الكود مكتوب بـ cURL؛ نفس الاستدعاءات تتطابق 1:1 مع .NET و Python و Java SDKs.

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 يخبرك بالضبط ما يحتويه دون الحاجة إلى تنزيله والتنقيب في Excel.
• عرض واجهة المستخدم. قم بتوجيه محدد ورقة العمل / الجدول / المخطط في تطبيقك مباشرةً من استجابة 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. قبول التغييرات المتتبعة (المراجعات)

عندما يقوم المتعاونون بتفعيل “Track Changes” في Excel، يصبح كل تعديل مراجعة — تغيير معلق يتضمن المؤلف، والطابع الزمني، وحالة القبول/الرفض. إذا كان خط أنابيبك يستهلك مثل هذه الملفات ويحتاج إلى إصدارات نظيفة ومُنهية، لديك خياران:

• محلي: 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

بعد هذه الاستدعاء، لم يعد المستند يظهر علامات التغييرات المتعقبة. جميع التعديلات مدمجة كما لو أنها كُتبت مباشرةً في النسخة النهائية.

سير عمل جماعي

اجمع مع واجهات برمجة التطبيقات الخاصة بقائمة الملفات على موفر التخزين الخاص بك لمعالجة كل ملف في مجلد:

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

كل مستأجر يحصل على مخرجات دقيقة بالبكسل وفق علامته التجارية الخاصة — صفر منطق تنسيق في الشيفرة الخاصة بك.

نمط: مصنع التقارير

تحتاج مهمة ليلية إلى إنتاج 30 تقريرًا إقليميًا، جميعها بنفس التخطيط ولكن ببيانات مختلفة:

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 واحد. يتناسب المصنع بأكمله داخل حلقة shell.

5. ضغط بنية

PUT /v4.0/cells/spreadsheet/compress?level=N يقبل أي مستوى من 0 إلى 9. اختيار المستوى الصحيح هو قرار صغير له تأثيرات لاحقة.

ضغط بمستوى 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            # فهم ما بداخلها
[2] GET {name}/worksheets/X/mergedcells  # اعرف أين لا تكتب
[3] DataProcessing/...              #

تكلفة استدعاءات الفحص الاثنين تكاد تكون لا شيء، لكنها تمنع الأخطاء المكلفة في التصحيح التي تنشأ من الكتابة في مناطق مدمجة أو استهداف جداول غير موجودة.

8. اعتبارات الأداء

• structure رخيص. إنّه يتجول عبر البيانات الوصفية، وليس محتويات الخلايا. آمن للاستدعاء على دفاتر عمل كبيرة.
• mergedcells رخيص. نفس السبب.
• compress يعتمد على وحدة المعالجة المركزية. المستويات الأعلى تكلف أكثر. استخدم المستوى 6 كإعداد افتراضي ما لم يكن لديك سبب للانتقال إلى مستوى أعلى.
• repair هو إعادة تسلسل كاملة. أكثر تكلفة من compress. نفّذها عند الاستيعاب، وليس على كل طلب.
• accept-all-revisions يتدرّج مع عدد المراجعات. مئات المراجعات في ملف واحد لا مشكلة؛ عشرات الآلاف ستستغرق لحظة.
• البدائل البعيدة تتفوق على الرحلات المحلية. عندما تكون الملفات موجودة بالفعل في التخزين السحابي، GET {name}/structure يتجنب تنزيل الملف إلى جهازك فقط لتفقده.

9. استكشاف المشكلات الشائعة

10. جمع كل شيء معًا

نقاط النهاية ManagementController صغيرة كل على حدة. قوتها تأتي من التركيب:

• إنشاء دفتر عمل من قالب → استيراد البيانات عبر DataProcessingController → إعادة تسمية الأوراق → ضغط → تسليم. هذه عملية تقارير SaaS كاملة في خمس طلبات HTTP.
• الهيكل + mergedcells + خلايا → طبقة فحص تفهم أي دفتر عمل تطرحه عليها، بدون Excel.
• إصلاح عند الاستيعاب → accept-all-revisions → بقية خط أنابيبك لا يرى سوى دفاتر عمل نظيفة ومُنهية.

لا تحتاج إلى مزرعة خوادم. لا تحتاج إلى تثبيت Excel. تحتاج إلى curl وخطة.