სიღრმისეული შესწავლა: გაფართოებული შაბლონები Aspose.Cells ღრუბლოვანი მართვის API-ით

თქვენ იცით, როგორ შექმნათ სამუშაო წიგნი, გადარქვით ფურცელს, და შეკუმშოთ ფაილი. მაგრამ ManagementController‑ს აქვს უფრო მკვეთრი ინსტრუმენტები, რომლებიც ბრტყელად ხილულია — სამუშაო წიგნის სრულ სტრუქტურალურ JSON გამოტანა, შერეული უჯრედების შემოწმება, რევიზიის მიღება, და შაბლონზე დაფუძნებული შექმნის მოდელი, რომელიც სტილიზაციას ქმნის ერთ-სტრიქონიან საკითხად. აქ არის ადგილი, სადაც სახლის მოვლა აღარ არის “clicking around in Excel” და იწყება პროგრამული სამუშაო წიგნის ჰიგინეა.

ნაწილი 1-ში ჩვენ გავიცნეთ 15 საბოლოო წერტილი სუფთა გზამკვლევებით. ეს პოსტი განკუთვნილია იმ სიტუაციებისთვის, რომლებიც რეალურ სამუშაო გარემოში ნამდვილი პრობლემები ქმნიან:

• თქვენ უნდა გადამოწმოთ სამუშაო წიგნი მისი დამუშავებამდე — აქვს თუ არა პივოტის ცხრილები, დიაგრამები, შერწყმული რეგიონები, რომლებიც შეიძლება შეცდომას გამოიწვიონ თქვენს კოდში?
• თქვენ უნდა მიღოთ ტრეკირებული ცვლილებები ასობით ფაილზე, სანამ ისინი თქვენს არქივურ პაიპლაინში გადადის.
• თქვენ გსურთ შექმნათ შაბლონების სისტემა, სადაც სხვადასხვა ქირაობის მომხმარებლებს მიიღება განსხვავებული ბრენდირებული შედეგები სტილიზაციის კოდის დაწერის გარეშე.
• თქვენ უნდა განიხილოთ შერწყმული უჯრედის რეგიონები, რათა თავიდან აიცილოთ მონაცემების ჩაწერა მათში (ან რომ გაიგოთ სამუშაო წიგნის განლაგება, რომელსაც თქვენ არ შექმენით).
• თქვენ გსურთ შერლათ შექმნა → სტრუქტურირება → მოდიფიკაცია → შეკუმშვა ერთიან სამუშაო წიგნის ქარხანაში.

ქვემოთ მოცემული ყველა მაგალითი შესრულებადია. კოდი არის cURL-ში; იგივე გამოძახებები 1:1 მიბმულია .NET, Python და Java SDK-ებზე.

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-ში ნახვის გარეშე.
• UI-ის რენდერი. მართეთ სამუშაო ფურცლის / ცხრილის / გრაფიკის სელექტორი თქვენს აპლიკაციაში პირდაპირ structure პასუხიდან.

2. შერწყმული უჯრედის რეგიონების შემოწმება

შერეული უჯრედები არის ელექტრონული ცხრილების ავტომატიზაციის ჩუმი მოკვლევები — შერეულ რეგიონალში დაწერა შეიძლება ჩუმად გადააწეროს მთელი ტერიტორია ან გამოიწვიოს კრიპტიკური შეცდომები. ManagementController აჩვენებს ორ endpoint-ს, რომლებსაც შეიძლება მოთხოვნა.

ლოკალური სამუშაო ფურცელი

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-ში.

გამოიყენეთ, რათა თავიდან აიცილოთ მიწის ღრუბლები

სამუშაო ფურცელში მონაცემების ჩაწერამდე (via CellsController ან DataProcessingController-ის იმპორტით), გამოიძახეთ ეს endpoint და გაფილტვრა ყველა 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

თითოეულ ქირაობის მომხმარებელს მიიღება პიქსელ-დამახასიათებელი შედეგი თავისი ბრენდის მიხედვით — ნული სტილიზაციის ლოგიკა თქვენს კოდში.

ნიმუში: ანგარიშის ფაბრიკა

ღამით შესრულებული სამუშაო უნდა შექმნას 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 გამოძახება. მთელი ქარხანა შედის შელის ციკლში.

5. შეკუმშვა მიზნის მიხედვით

PUT /v4.0/cells/spreadsheet/compress?level=N იღებს ნებისმიერი დონეს 0‑დან 9‑მდე. სწორი დონის არჩევა პატარა გადაწყვეტილებაა, რომელიც downstream ეფექტებს იწვევს.

30 მბ-ის XLSX-ზე level-6 შეკუმშვა ჩვეულებრივ 8–12 მბ-ის შუალედშია. Level 9 ხშირად კიდევ 10–15% სიწმინდის, დაახლოებით ორჯერ მეტი CPU ღირებულებით. უმეტეს აპლიკაციებისთვის level=6 არის საუკეთესო არჩევანი.

6. შეკეთება: რა აკეთებს რეალურად

PUT /v4.0/cells/spreadsheet/repair განაპიროვნებით მარტივი — პარამეტრები არ არსებობს, კონფიგურაცია არ არსებობს. შიდა დონეზე იგი:

1. ანალიზებს სამუშაო წიგნაკს ძრავის მკაცრ მკითხველის საშუალებით.
2. მოიცილებს სტრუქტურული არასწორ ნაწილებს (მიტოვებული ურთიერთობები, დაზიანებული XML, არასწორი უჯრედის ბმულები).
3. თავიდან სერიალიზდება ახალი XLSX კონტეინერში.

შედეგი არის ფაილი, რომელიც Excel-ში სუფთა გახსნილია. რას ვერ შეუძლია გასწორება: მონაცემთა-დონის დაზიანება (უჯრედი, რომლის მნიშვნელობა #REF! არის, რადგან ფორმულა დაზიანებულია), დაკარგული სურათები (თუ სურათის ნაკადი თვითონ დაზიანებულია), ან დაკარგული VBA მაკროები (თუ vbaProject.bin-ი არ არის წაკითხვადი). თუმცა 80% შემთხვევისთვის — “Excel ამბობს, რომ ეს ფაილი დაზიანებულია და გთავაზობთ მისი შეკეთებას” — ეს endpoint აკეთებს იგივე შეკეთებას, სერვერის მხარეს, GUI-ის გარეშე.

რეპარაციის გაშვების დრო

• შემოტანისას. თუ თქვენი აპლიკაცია იღებს მომხმარებლის ატვირთულ ფაილებს, გაუშვით 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. თქვენი endpoint არის თხელი ორგანიზატორი.

ნიმუში: 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-ზე დამოკიდებულია. უფრო მაღალი დონეები უფრო ძვირია. გამოიყენეთ დონე 6 როგორც ნაგულისხმევი, თუ არ გაქვთ მიზეზი უფრო მაღალ დონეზე გასაყვანად.
• repair სრულად გადამუშავებულია. უფრო ძვირია, ვიდრე compress. გაუშვით იგი შეყვანისას, არა ყოველ მოთხოვნაზე.
• accept-all-revisions მასშტაბირდება ვერსიების რაოდენობით. ასობით ვერსია ერთ ფაილში კარგად მუშაობს; ათასობით კი გარკვეული დროით.
• დისტანციური ვარიანტები აძლიერებს ადგილობრივ რაუნდ‑ტრიპებს. როდესაც ფაილები უკვე ღრუბლოვან შენახვაში არიან, GET {name}/structure აცილებს ფაილის თქვენს მანქანაზე ჩამოტვირთვას, მხოლოდ მისი შემოწმებისთვის.

9. საერთო პრობლემების გადაჭრა

10. ყველა​ფრის შეჯამება

ManagementController endpoint-ები ინდივიდუალურად პატარაა. მათი ძალა შედგენიდან მოდის:

• შექმნა სამუშაო წიგნი შაბლონიდან → იმპორტირება მონაცემები via DataProcessingController → სახელის გადარქმევა ფურცლები → შეკუმშვა → მიწოდება. ეს სრულყოფილი SaaS ანგარიშის პაიპლაინია ხუთ HTTP მოთხოვნის მიხედვით.
• სტრუქტურა + mergedcells + უჯრედები → ინსპექციის ფენა, რომელიც იცის ნებისმიერი სამუშაო წიგნი, რომელიც მას აყენებთ, Excel-ის გარეშე.
• გასწორება შეყვანისას → accept-all-revisions → თქვენი პაიპლაინის დარჩენილი ნაწილი ყოველთვის ხედავს სუფთა, დასრულებულ სამუშაო წიგნებს.

სერვერის ფარმის საჭიროება არ გაქვთ. Excel-ის დაყენება არ გჭირდებათ. თქვენ გჭირდებათ curl და გეგმა.