შექმნა, მართვა, შენარჩუნება: პრაქტიკული გიდი Aspose.Cells ღრუბლოვანი მენეჯმენტის API-ს

ცარიელი სამუშაო წიგნის შექმნა, ფურცლის სახელის გადარქმევა, გადატვირთული ფაილის შეკუმშვა ან დაზიანებული ფაილის შეკეთება — ეს არის პატარა, ყოველდღიური დავალებები, რომლებიც მაინც ჭამენ დეველოპერების დრო, როდესაც სწორი ინსტრუმენტი არ გაქვთ. ManagementController ისინი ერთ ხაზში გადაყავს.

თითოეული აპლიკაცია, რომელიც მუშაობს ცხრილებთან, საბოლოოდ შეხვდება იგივე არამშვენიერებულ დავალებებს:

  • შექმნა ახალი, ცარიელი სამუშაო წიგნი მყისიერად — ზოგჯერ ბრენდირებული შაბლონიდან.
  • სამუშაო ფურცლების გადალაგება — დამატება, სახელის გადარქვება, წაშლა, გადალაგება — რადგან მონაცემების ფორმა გუშინიდან შეიცვალა.
  • ფაილის ზომის დუმება — 40 მბ-ის XLSX-ს შეკუმშვა 8 მბ-ზე, ელფოსტით გაგზავნამდე.
  • დაზიანებული ფაილის გადარჩენა — ის, რომელსაც მომხმარებელმა არასწორად შეინახა, ან ინსტრუმენტი ცუდად გაიტანა.
  • სტრუქტურის შემოწმება — რომელი ფურცლები, ცხრილები, გრაფიკები და შერწყმული უჯრედის რეგიონები არიან სამუშაო წიგნის შიგნით, მისი გახსნის გარეშე.

ManagementController-ის Aspose.Cells Cloud მიკროსერვისში (წყარო: src/Aspose.Cells.Cloud.MicroService/Controllers/ManagementController.cs) ყველა ეს ფუნქცია მართავს სუფთა REST ზედაპირზე. ამ პოსტში წარმოგიდგენთ მისი 15 endpoint-ს, რომელთა შესრულებაც შესაძლებელია cURL მაგალითებით, რომლებიც შეგიძლიათ ჩასვათ თქვენს პაიპლაინში დღესვე.

1. რა აკეთებს ManagementController?

ManagementController არის კონტროლერი, რომელიც განკუთვნილია სამუშაო წიგნის სიცოცხლის ციკლისა და სახლის მოვლისთვის. განსხვავებით ConversionController (ფორმატის გადაყვანა), DataProcessingController (მასობრივი შერწყმა/გაყოფა/იმპორტი), ან CellsController (უჯრედის-დონეზე წაკითხვა/წერა), ეს კონტროლერი ეხება სამუშაო წიგნის ფორმას, ჯანმრთელობას და მეტამონაცემებს.

პასუხისმგებლობა ტიპიკური საბოლოო წერტილები
Create სამუშაო წიგნები, არასავალდებულოდ შაბლონიდან spreadsheet/create
Inspect სტრუქტურა — სამუშაო ფურცლები, შერწყმული უჯრედები, სრული სტრუქტურის JSON spreadsheet/worksheets, spreadsheet/mergedcells, spreadsheet/structure, {name}/worksheets/{worksheet}/mergedcells, {name}/structure
Modify სამუშაო ფურცლის განლაგება — დამატება, წაშლა, სახელის შეცვლა, გადატანა spreadsheet/add/worksheet, spreadsheet/delete/worksheet, spreadsheet/rename/worksheet, spreadsheet/move/worksheet
Maintain — შეკუმშვა, რეპარაცია, ცვლილებების მიღება spreadsheet/compress, spreadsheet/repair, spreadsheet/accept-all-revisions, {name}/accept-all-revisions

თითოეული endpoint იღებს სამუშაო წიგნს multipart შეყვანის სახით (ლოკალურად) ან მიმართავს უკვე ღრუბლურ შენახვაში არსებულს (დისტანსულად), და აბრუნებს შეცვლილი სამუშაო წიგნის ნაკადს, JSON payload-ს, ან მარტივი OK-ს.

2. ცხუთმეტი საბოლოო წერტილები მიმოხილვით

# HTTP Route Source What it does
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. დაწყებამდე: ორი წინაპირობა

  1. მიიღეთ ავტორიზაციის დეტალები. რეგისტრაცია Aspose Cloud Dashboard, შექმენით აპლიკაცია, მიიღეთ Client ID და Client Secret. SDK-ები მართავენ JWT გაცვლას თქვენთვის; cURL-ით თქვენ ხელით გადაყავთ ისინი ბეერერ ტოკენზე.

  2. დააყენეთ 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
Parameter Type Default Meaning
sheetType string Worksheet ახალი ფურცლის ტიპი — Worksheet, Chart, და სხვა
position int end 0-ინდექსის პოზიცია ახალი ფურცლის ჩასასვლელად
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

ამ ყველა endpoint‑ი იგივე ნიმუშს იყენებს: ატვირთეთ სამუშაო წიგნი multipart‑ში, მიიღეთ შეცვლილი სამუშაო წიგნი უკან. შეაერთეთ ისინი თქვენს pipeline‑ში, ან გამოიძახეთ ისინი ad‑hoc‑ით UI‑დან.

6. ნაკრძალი: გადატვირთული სამუშაო წიგნის შეკუმშვა

მომხმარებელმა გაგზავნა 40 მბ ზომის XLSX, რომელიც 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 დონე typical 40 MB სამუშაო წიგნზე ხშირად 6–10 MB შუალედშია. შინაარსი იდენტურია; მხოლოდ XLSX კონტეინერის ZIP შეკუმშვა გაძლიერებულია.

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 endpoint აბრუნებს სრულ JSON რუკას ფურცლების, ცხრილების, პივოტ ცხრილების, დიაგრამების და ფორმების — იდეალურია UI-ს ან ვალიდაციის პაიპლაინის მართვისთვის.
  • ნული ინფრასტრუქტურა. Excel-ის ინსტალაცია არ არის, COM არ არის, სერვერი არ არის, რომელიც უნდა მოვახდინოთ.