إنشاء، إدارة، صيانة: دليل عملي لواجهة برمجة تطبيقات إدارة سحابة Aspose.Cells
إنشاء دفتر عمل فارغ، وإعادة تسمية ورقة، وضغط ملف منتفخ، أو إصلاح ملف تالف — هذه هي المهام الصغيرة اليومية التي لا تزال تستنزف وقت المطور عندما لا تتوفر الأداة المناسبة.
ManagementControllerيحولها إلى سطر واحد.
كل تطبيق يعمل مع جداول البيانات يواجه في النهاية نفس المهام غير المثيرة:
- إنشاء مصنف جديد وفارغ في الوقت الفعلي — أحيانًا من قالب يحمل علامة تجارية.
- إعادة ترتيب أوراق العمل — الإضافة، إعادة التسمية، الحذف، إعادة الترتيب — لأن شكل البيانات تغير منذ الأمس.
- تقليل حجم الملف — ضغط ملف XLSX بحجم 40 ميغابايت إلى 8 ميغابايت قبل إرساله عبر البريد الإلكتروني.
- إنقاذ ملف تالف — الملف الذي حفظه المستخدم بشكل خاطئ، أو الذي صدّره أداة بشكل سيء.
- فحص الهيكل — معرفة أي الأوراق، الجداول، المخططات، ومناطق الخلايا المدمجة الموجودة داخل المصنف دون فتحه.
يتعامل ManagementController في خدمة Aspose.Cells Cloud الصغيرة (المصدر: src/Aspose.Cells.Cloud.MicroService/Controllers/ManagementController.cs) مع كل هذه عبر واجهة REST نظيفة. تُقدِّم هذه المقالة 15 نقطة نهاية مع أمثلة cURL قابلة للتنفيذ يمكنك لصقها في خط أنابيبك اليوم.
1. ما الذي يفعله ManagementController؟
ManagementController هو المتحكم المخصص لـ دورة حياة دفتر العمل والصيانة. على عكس ConversionController (تحويل الصيغ)، DataProcessingController (دمج/تقسيم/استيراد جماعي)، أو CellsController (قراءة/كتابة على مستوى الخلية)، هذا المتحكم يتعلق بـ الشكل، الصحة، والبيانات الوصفية للدفتر نفسه.
| المسؤولية | نقاط النهاية النموذجية |
|---|---|
| إنشاء دفاتر عمل، اختياريًا من قالب | spreadsheet/create |
| فحص الهيكل — أوراق العمل، الخلايا المدمجة، JSON كامل للهيكل | spreadsheet/worksheets, spreadsheet/mergedcells, spreadsheet/structure, {name}/worksheets/{worksheet}/mergedcells, {name}/structure |
| تعديل تخطيط ورقة العمل — إضافة، حذف، إعادة تسمية، نقل | spreadsheet/add/worksheet, spreadsheet/delete/worksheet, spreadsheet/rename/worksheet, spreadsheet/move/worksheet |
| صيانة — ضغط، إصلاح، قبول التعديلات | spreadsheet/compress, spreadsheet/repair, spreadsheet/accept-all-revisions, {name}/accept-all-revisions |
كل نقطة نهاية تستقبل دفتر عمل كإدخال متعدد الأجزاء (محلي) أو تشير إلى واحد موجود بالفعل في التخزين السحابي (عن بُعد)، وتعيد إما تدفق دفتر عمل معدل، أو حمولة JSON، أو مجرد OK بسيط.
2. خمسة عشر نقطة النهاية في لمحة سريعة
| # | HTTP | Route | المصدر | ما الذي يفعله |
|---|---|---|---|---|
| 1 | PUT | /v4.0/cells/spreadsheet/create |
— | إنشاء مصنف جديد، اختياريًا من قالب |
| 2 | PUT | /v4.0/cells/spreadsheet/worksheets |
محلي | قائمة بجميع أوراق العمل (الاسم + النوع) |
| 3 | PUT | /v4.0/cells/spreadsheet/add/worksheet |
محلي | إضافة ورقة عمل مع النوع والاسم والموضع |
| 4 | PUT | /v4.0/cells/spreadsheet/delete/worksheet |
محلي | إزالة ورقة عمل بالاسم |
| 5 | PUT | /v4.0/cells/spreadsheet/rename/worksheet |
محلي | إعادة تسمية ورقة عمل |
| 6 | PUT | /v4.0/cells/spreadsheet/move/worksheet |
محلي | نقل ورقة عمل إلى فهرس جديد |
| 7 | PUT | /v4.0/cells/spreadsheet/compress |
محلي | ضغط المصنف لتقليل الحجم |
| 8 | PUT | /v4.0/cells/spreadsheet/repair |
محلي | إصلاح مصنف تالف |
| 9 | GET | /v4.0/cells/{name}/worksheets/{worksheet}/mergedcells |
سحابي | قائمة مناطق الخلايا المدمجة في ورقة عمل عن بُعد |
| 10 | PUT | /v4.0/cells/spreadsheet/mergedcells |
محلي | قائمة مناطق الخلايا المدمجة في ورقة عمل محلية |
| 11 | PUT | /v4.0/cells/spreadsheet/accept-all-revisions |
محلي | قبول جميع التغييرات المتتبعة |
| 12 | PUT | /v4.0/cells/{name}/accept-all-revisions |
سحابي | قبول جميع التغييرات المتتبعة في ملف عن بُعد |
| 13 | PUT | /v4.0/cells/spreadsheet/structure |
محلي | الحصول على البنية الكاملة بصيغة JSON |
| 14 | GET | /v4.0/cells/{name}/structure |
سحابي | الحصول على البنية الكاملة لملف عن بُعد بصيغة JSON |
| 15 | PUT | /v4.0/cells/spreadsheet/create |
— | (اسم مستعار — انظر #1) |
تفترض المسارات المضيف
https://api.aspose.cloud. تبدو المكالمات الحية مثلhttps://api.aspose.cloud/v4.0/cells/....
3. قبل أن تبدأ: متطلبان
- احصل على بيانات الاعتماد. سجّل في Aspose Cloud Dashboard، أنشئ تطبيقًا، واحصل على
Client IDوClient Secret. تتعامل SDKs مع تبادل JWT نيابةً عنك؛ مع cURL، تقوم بتبديلها للحصول على رمز حامل يدويًا. - قم بتثبيت SDK — أو استخدم cURL فقط. كل شيء هو REST بسيط.
<!-- .NET -->
<PackageReference Include="Aspose.Cells-Cloud" Version="25.x" />
# Python
pip install asposecellscloud
4. بدء سريع: إنشاء مصنف جديد
PUT /v4.0/cells/spreadsheet/create هو أبسط شيء يفعله المتحكم — وهو أحد أكثر الأشياء فائدة. إنه يُعيد ملف دفتر عمل جديد تمامًا.
cURL
# 1) Get a bearer token
curl -X POST "https://api.aspose.cloud/connect/token" \
-d "grant_type=client_credentials" \
-d "client_id=YOUR_CLIENT_ID" \
-d "client_secret=YOUR_CLIENT_SECRET"
# 2) Create an empty XLSX
curl -X PUT "https://api.aspose.cloud/v4.0/cells/spreadsheet/create?format=xlsx" \
-H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
--output new_workbook.xlsx
| المعامل | النوع | القيمة الافتراضية | المعنى |
|---|---|---|---|
format |
string | xlsx |
تنسيق ملف الإخراج — xlsx, xlsm, xlsb, ods، إلخ. |
template |
string | null |
مسار ملف القالب (اختياري). عند توفيره، يتم تهيئة دفتر العمل الجديد بمحتوى القالب وتنسيقه. |
استخدام قالب
إذا كان لديك قالب يحمل علامتك التجارية — شعار في الرأس، ألوان العلامة في السمة، جدول “Invoice” مُنسق مسبقًا — قم بتحميله مرة واحدة إلى التخزين السحابي، ثم مرّر مساره كـ template:
curl -X PUT "https://api.aspose.cloud/v4.0/cells/spreadsheet/create?format=xlsx&template=templates/invoice_branded.xlsx" \
-H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
--output invoice_2026_09_001.xlsx
الآن يمكن لتطبيقك إنشاء فواتير جديدة تبدو صحيحة بالفعل، دون الحاجة إلى تضمين أي منطق تنسيق.
5. دليل خطوة بخطوة: إدارة أوراق العمل في دفتر العمل
تتعامل هذه النقاط الأربع مع الشكل اليومي لدفتر العمل. دعنا نتبع تسلسلًا واقعيًا: لقد قمت بتحميل دفتر عمل، وتحتاج إلى سرد أوراقه، وإضافة ورقة جديدة، وإعادة تسمية ورقة موجودة، وحذف ورقة ثالثة.
5a. قائمة أوراق العمل
curl -X PUT "https://api.aspose.cloud/v4.0/cells/spreadsheet/worksheets" \
-H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
-H "Content-Type: multipart/form-data" \
-F "file=@my_workbook.xlsx"
Response:
[
{ "WorksheetName": "Sheet1", "SheetType": "Worksheet" },
{ "WorksheetName": "Data", "SheetType": "Worksheet" },
{ "WorksheetName": "Chart1", "SheetType": "Chart" }
]
5b. إضافة ورقة عمل جديدة
curl -X PUT "https://api.aspose.cloud/v4.0/cells/spreadsheet/add/worksheet?sheetType=Worksheet&position=1&sheetName=Summary" \
-H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
-F "file=@my_workbook.xlsx" \
--output updated.xlsx
| المعامل | النوع | القيمة الافتراضية | المعنى |
|---|---|---|---|
sheetType |
string | Worksheet |
نوع الورقة الجديدة — Worksheet, Chart, إلخ. |
position |
int | end | الموضع المفهرس من الصفر لإدراج الورقة الجديدة |
sheetName |
string | auto | الاسم الذي سيُعطى للورقة الجديدة |
5c. إعادة تسمية ورقة عمل
curl -X PUT "https://api.aspose.cloud/v4.0/cells/spreadsheet/rename/worksheet?sourceName=Sheet1&targetName=Overview" \
-H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
-F "file=@my_workbook.xlsx" \
--output updated.xlsx
5d. حذف ورقة عمل
curl -X PUT "https://api.aspose.cloud/v4.0/cells/spreadsheet/delete/worksheet?sheetName=Chart1" \
-H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
-F "file=@my_workbook.xlsx" \
--output updated.xlsx
5e. نقل ورقة عمل
# Move "Data" to position 0 (front of the workbook)
curl -X PUT "https://api.aspose.cloud/v4.0/cells/spreadsheet/move/worksheet?worksheet=Data&position=0" \
-H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
-F "file=@my_workbook.xlsx" \
--output updated.xlsx
كل من هذه النقاط النهائية يتبع نفس النمط: تحميل دفتر العمل بصيغة multipart، والحصول على دفتر العمل المعدل مرة أخرى. قم بربطها في خط أنابيبك، أو استدعها بشكل غير متزامن من واجهة المستخدم.
6. دليل خطوة بخطوة: ضغط مصنف منتفخ
أرسل لك مستخدم ملف XLSX بحجم 40 ميغابايت يحتوي على 90 ٪ من XML غير الضروري. PUT /v4.0/cells/spreadsheet/compress يقلص حجمه.
curl -X PUT "https://api.aspose.cloud/v4.0/cells/spreadsheet/compress?level=9" \
-H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
-F "file=@bloated.xlsx" \
--output slim.xlsx
| المعامل | النوع | المعنى |
|---|---|---|
level |
int | شدة الضغط. 0 = بدون ضغط، 9 = أقصى ضغط. |
مستوى 9 في مصنف بحجم 40 ميغابايت عادةً ما يقترب من نطاق 6–10 ميغابايت. المحتوى هو نفسه؛ فقط ضغط ZIP لحاوية XLSX تم تشديده.
7. دليل خطوة بخطوة: إصلاح مصنف تالف
في بعض الأحيان تتلقى ملفًا يرفض Excel فتحه. PUT /v4.0/cells/spreadsheet/repair يقوم بتشغيل روتين الاستعادة للمحرك ويعيد نسخة نظيفة.
curl -X PUT "https://api.aspose.cloud/v4.0/cells/spreadsheet/repair" \
-H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
-F "file=@broken.xlsx" \
--output repaired.xlsx
بدون معلمات. يقوم المتحكم بإعادة تسلسل دفتر العمل عبر المحرك، الذي يتخلص من الأجزاء التالفة ويكتب ملفًا صالحًا من الناحية الهيكلية. ليس كل الفساد قابلًا للاسترداد، لكن هذا يتعامل مع الحالات الشائعة — إدخالات ZIP المقتطعة، مراجع الخلايا غير الصالحة، سلاسل المشاركة المشوهة.
8. ملخص الفوائد الرئيسية
- متحكم واحد لعمليات دورة الحياة. إنشاء، إعادة هيكلة، ضغط، إصلاح، فحص — كل ذلك تحت نموذج مصادقة واحد وعقد خطأ واحد.
- إنشاء واعٍ بالقالب. لا تعيد تنفيذ التنسيق في تطبيقك؛ دع الخادم يدمج قالبًا في كل دفتر عمل جديد.
- متغيرات محلية وعن بُعد. نفس المنطق سواء كانت الملفات في متصفح المستخدم أو موجودة بالفعل في التخزين السحابي.
- استكشاف بنية. نقطة النهاية
structureتُرجع خريطة JSON كاملة للأوراق، الجداول، جداول المحور، المخططات، والأشكال — مثالية لتوجيه واجهة المستخدم أو خط أنابيب التحقق. - صفر بنية تحتية. لا تثبيت Excel، لا COM، لا خادم للصيانة.