ایجاد، مدیریت، نگهداری: راهنمای عملی برای API مدیریت Aspose.Cells Cloud
ایجاد یک کتاب‌کار خالی، تغییر نام یک شیت، فشرده‌سازی یک فایل حجیم، یا تعمیر یک فایل خراب — این‌ها کارهای کوچک روزمره‌ای هستند که هنوز زمان توسعه‌دهندگان را می‌گیرند وقتی ابزار مناسب ندارید.
ManagementControllerآنها را به یک‌خطی‌ها تبدیل می‌کند.
هر برنامه‌ای که با صفحات گسترده کار می‌کند در نهایت با همان کارهای کسل‌کننده مواجه می‌شود:
- ایجاد یک کتاب‌کار جدید و خالی به‌صورت لحظه‌ای — گاهی از یک قالب برند شده.
- بازآرایی برگه‌ها — افزودن، تغییر نام، حذف، بازچینش — زیرا شکل داده‌ها از دیروز تغییر کرده است.
- کنترل اندازه فایل — فشرده‌سازی یک فایل XLSX ۴۰ مگابایتی به ۸ مگابایت قبل از ارسال ایمیل.
- بازیابی فایل خراب — فایلی که کاربر به‌اش به‌درستی ذخیره نکرده یا ابزار به‌درستی صادر نکرده است.
- بازرسی ساختار — تعیین اینکه کدام برگه‌ها، جدول‌ها، نمودارها و نواحی سلول‌های ادغام‌شده در یک کتاب‌کار وجود دارند بدون اینکه آن را باز کنید.
ManagementController در میکروسرویس Aspose.Cells Cloud (منبع: src/Aspose.Cells.Cloud.MicroService/Controllers/ManagementController.cs) تمام این موارد را پشت یک سطح REST تمیز مدیریت می‌کند. این پست 15 نقطه انتهایی آن را با مثال‌های قابل اجرا cURL معرفی می‌کند که می‌توانید امروز در خط لوله خود بچسبانید.
1. ManagementController چه کاری انجام می‌دهد؟
ManagementController کنترلری است که به دوره حیات و نگهداری کتاب کار اختصاص دارد. برخلاف ConversionController (تبدیل فرمت)، DataProcessingController (ادغام/تقسیم/واردات دسته‌جمعی)، یا CellsController (خواندن/نوشتن در سطح سلول)، این کنترلر درباره شکل، سلامت و متادیتا خود کتاب کار است.
| مسئولیت | پایانه‌های معمولی |
|---|---|
| ایجاد کتاب‌کارها، به‌صورت اختیاری از یک الگو | spreadsheet/create |
| بازرسی ساختار — worksheets، merged cells، full structure JSON | spreadsheet/worksheets, spreadsheet/mergedcells, spreadsheet/structure, {name}/worksheets/{worksheet}/mergedcells, {name}/structure |
| ویرایش چیدمان worksheet — add، delete، rename، move | spreadsheet/add/worksheet, spreadsheet/delete/worksheet, spreadsheet/rename/worksheet, spreadsheet/move/worksheet |
| نگهداری — compress، repair، accept revisions | spreadsheet/compress, spreadsheet/repair, spreadsheet/accept-all-revisions, {name}/accept-all-revisions |
هر نقطه انتهایی یک کتاب‌کار را به‌عنوان ورودی چندبخشی (local) یا به‌یک کتاب‌کار موجود در ذخیره‌سازی ابری (remote) ارجاع می‌دهد و یا یک جریان کتاب‌کار اصلاح‌شده، یک بارگذاری JSON یا یک پیام ساده OK را برمی‌گرداند.
2. پانزده نقطه پایانی در یک نگاه
| # | HTTP | مسیر | منبع | عملکرد |
|---|---|---|---|---|
| 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/...هستند.
۳. قبل از شروع: دو پیش‌نیاز
- دریافت اعتبارها. در Aspose Cloud Dashboard ثبت‌نام کنید، یک برنامه ایجاد کنید،
Client IDوClient Secretرا بگیرید. SDKها تبادل 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، دریافت کتاب‌کار تغییر یافته. آنها را در خط لوله خود زنجیره کنید یا به‌صورت ad‑hoc از یک UI فراخوانی کنید.
6. راهنما: فشرده‌سازی یک کتاب‌کار پرحجم
یک کاربر یک فایل XLSX 40 MB که 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
| Parameter | Type | Meaning |
|---|---|---|
level |
int | شدت فشرده‌سازی. 0 = بدون فشرده‌سازی، 9 = حداکثر. |
سطح 9 در یک کتاب‌کار معمولی ۴۰ مگابایتی اغلب در بازه ۶ تا ۱۰ مگابایت قرار می‌گیرد. محتوا یکسان است؛ فقط فشرده‌سازی 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 از شیت‌ها، جدول‌ها، جدول‌های محوری، نمودارها و اشکال باز می‌گرداند — ایده‌آل برای رانده شدن یک UI یا خط لوله اعتبارسنجی. - بدون زیرساخت. نصب Excel نیست، COM نیست، سروری برای نگهداری نیست.