Đào sâu: Các mẫu nâng cao với Aspose.Cells Cloud Management API

Bạn biết cách tạo một workbook, đổi tên một sheet và nén một tệp. Nhưng ManagementController có những công cụ sắc bén hơn ẩn hiện rõ ràng — một dump JSON cấu trúc đầy đủ của workbook, kiểm tra các ô đã hợp nhất, chấp nhận phiên bản, và mẫu tạo dựa trên template giúp việc định dạng trở thành một loạt lệnh một dòng. Đây là nơi công việc bảo trì không còn là “clicking around in Excel” mà bắt đầu là programmatic workbook hygiene.

Trong Phần 1 chúng tôi đã bao phủ 15 endpoint với các hướng dẫn chi tiết. Bài viết này dành cho những tình huống thực sự gây khó khăn trong môi trường sản xuất:

Bạn cần kiểm tra một workbook trước khi xử lý — nó có bảng pivot, biểu đồ, vùng hợp nhất mà sẽ gây lỗi cho mã của bạn không?
Bạn cần chấp nhận các thay đổi được theo dõi trên hàng trăm tệp trước khi chúng đi vào quy trình lưu trữ.
Bạn muốn xây dựng một hệ thống mẫu nơi các khách thuê khác nhau nhận được các đầu ra có thương hiệu khác nhau mà không cần viết mã kiểu dáng.
Bạn cần kiểm tra các vùng ô hợp nhất để tránh ghi dữ liệu vào chúng (hoặc để hiểu bố cục của một workbook mà bạn không tạo).
Bạn muốn nối chuỗi tạo → cấu trúc → sửa đổi → nén thành một nhà máy workbook duy nhất.

Mỗi ví dụ dưới đây đều có thể chạy được. Mã được viết bằng cURL; các cuộc gọi tương tự được ánh xạ 1:1 sang các SDK .NET, Python và Java.

1. Lấy cấu trúc đầy đủ của một workbook dưới dạng JSON

PUT /v4.0/cells/spreadsheet/structure (cục bộ) và GET /v4.0/cells/{name}/structure (từ xa) trả về một tài liệu JSON duy nhất mô tả mọi thứ mà engine biết về workbook: worksheets, tables, pivot tables, charts, shapes, merged-cell regions và hơn nữa.

Cục bộ

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"

Từ xa

curl -X GET "https://api.aspose.cloud/v4.0/cells/mystery_workbook.xlsx/structure?folder=uploads" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Bạn nhận được gì

{
  "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 }
      ]
    }
  ]
}

Tại sao điều này quan trọng

Xác thực trước khi thực thi. Trước khi chạy các import của DataProcessingController trên một workbook, hãy gọi structure để xác minh rằng worksheet và bảng mục tiêu thực sự tồn tại.
Khám phá bố cục. Bạn đang làm việc với một workbook mà bạn không tạo? structure cho bạn biết chính xác những gì bên trong mà không cần tải xuống và dò dẫm trong Excel.
Kết xuất giao diện người dùng. Điều khiển bộ chọn worksheet / table / chart trong ứng dụng của bạn trực tiếp từ phản hồi của structure.

2. Kiểm tra các vùng ô đã hợp nhất

Các ô đã hợp nhất là những kẻ giết người thầm lặng trong tự động hoá bảng tính — việc ghi vào một vùng hợp nhất có thể âm thầm ghi đè lên toàn bộ khu vực hoặc gây ra các lỗi khó hiểu. ManagementController cung cấp hai endpoint để truy vấn chúng.

Bảng tính cục bộ

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"

Bảng tính từ xa

curl -X GET "https://api.aspose.cloud/v4.0/cells/my_workbook.xlsx/worksheets/Sheet1/mergedcells?folder=uploads" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Phản hồi

[
  { "StartRow": 0, "StartColumn": 0, "EndRow": 0, "EndColumn": 3 },
  { "StartRow": 5, "StartColumn": 1, "EndRow": 7, "EndColumn": 1 }
]

Mỗi mục là một CellArea — một hình chữ nhật trong tọa độ hàng/cột. Vùng đầu tiên ở trên là tiêu đề được hợp nhất qua A1–D1; vùng thứ hai là việc hợp nhất dọc ở B6–B8.

Sử dụng nó để tránh bẫy mìn

Trước khi ghi dữ liệu vào một worksheet (qua CellsController hoặc DataProcessingController’s import), gọi endpoint này và lọc bỏ bất kỳ giá trị startcell nào nằm trong một vùng đã hợp nhất. Hoặc, ngược lại, sử dụng các vùng hợp nhất để khám phá các hàng tiêu đề và tiêu đề phần một cách lập trình.

3. Chấp nhận các thay đổi được theo dõi (sửa đổi)

Khi các cộng tác viên bật tính năng “Track Changes” trong Excel, mỗi chỉnh sửa sẽ trở thành một revision — một thay đổi đang chờ xử lý kèm theo tác giả, thời gian và trạng thái chấp nhận/từ chối. Nếu quy trình của bạn tiếp nhận các tệp như vậy và cần các phiên bản sạch, đã hoàn thiện, bạn có hai lựa chọn:

Cục bộ: PUT /v4.0/cells/spreadsheet/accept-all-revisions
Từ xa: PUT /v4.0/cells/{name}/accept-all-revisions

Cục bộ

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

Từ xa

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

Sau cuộc gọi này, tài liệu sẽ không còn hiển thị đánh dấu thay đổi đã theo dõi. Tất cả các chỉnh sửa sẽ được gộp lại như thể chúng đã được gõ trực tiếp vào phiên bản cuối cùng.

Quy trình hàng loạt

Kết hợp với các API liệt kê tệp trên nhà cung cấp lưu trữ của bạn để xử lý mọi tệp trong một thư mục:

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

(Mã sản xuất thực tế sẽ sử dụng SDK và thực hiện song song với async/await — cuộc gọi REST là giống nhau.)

4. Tạo dựa trên mẫu ở quy mô lớn

Tham số template trên spreadsheet/create không chỉ là một tiện ích — nó là nền tảng của một hệ thống mẫu. Máy chủ tải workbook mẫu, sao chép giao diện, kiểu dáng, các phạm vi có tên và bất kỳ bảng đã định dạng trước nào, và trả về một workbook mới mà bạn có thể ngay lập tức điền dữ liệu thông qua DataProcessingController/import/data.

Mẫu: một mẫu cho mỗi tenant

Lưu trữ mẫu trong bộ nhớ đám mây dưới đường dẫn được phân theo khóa thuê bao:

templates/tenant_acme/invoice.xlsx
templates/tenant_globex/invoice.xlsx
templates/tenant_initech/invoice.xlsx

Khi hệ thống của người thuê tạo ra một hoá đơn:

# 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

Mỗi tenant nhận được đầu ra pixel-perfect trong thương hiệu riêng của họ — không có logic định dạng nào trong mã của bạn.

Mẫu: nhà máy báo cáo

Một công việc hàng đêm cần tạo ra 30 báo cáo khu vực, tất cả có cùng bố cục nhưng dữ liệu khác nhau:

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

Mỗi giai đoạn pipe là một lời gọi API. Toàn bộ nhà máy có thể được đặt trong một vòng lặp shell.

5. Nén có mục đích

PUT /v4.0/cells/spreadsheet/compress?level=N chấp nhận bất kỳ mức nào từ 0 đến 9. Việc chọn mức phù hợp là một quyết định nhỏ nhưng có ảnh hưởng tới các bước tiếp theo.

Level	Typical use case
0	Gỡ lỗi — xuất workbook mà không nén gì cả
1–3	Các pipeline gần thời gian thực, nơi chi phí CPU quan trọng hơn kích thước
4–6	Khuyến nghị mặc định. Nén tốt cho CPU vừa phải.
7–9	Lưu trữ, tệp đính kèm email, tài liệu giao nhận — kích thước quan trọng hơn tốc độ

Một mức nén level-6 trên tệp XLSX 30 MB thường cho ra khoảng 8–12 MB. Level 9 thường ép thêm 10–15 % nữa, với chi phí CPU gấp đôi. Đối với hầu hết các ứng dụng, level=6 là lựa chọn tối ưu.

6. Sửa chữa: những gì nó thực sự làm

PUT /v4.0/cells/spreadsheet/repair được thiết kế cố ý đơn giản — không có tham số, không có cấu hình. Trong nội bộ, nó:

Phân tích workbook thông qua trình đọc nghiêm ngặt của engine.
Loại bỏ các phần không hợp lệ về cấu trúc (các mối quan hệ bị rời rạc, XML sai định dạng, tham chiếu ô không hợp lệ).
Tái tuần tự hóa vào một container XLSX mới.

Kết quả là một tệp mở sạch sẽ trong Excel. Những gì nó không thể sửa: hỏng dữ liệu ở mức ô (một ô có giá trị #REF! do công thức bị hỏng), mất hình ảnh (nếu luồng hình ảnh tự nó bị hỏng), hoặc mất macro VBA (nếu tệp vbaProject.bin không đọc được). Nhưng trong trường hợp 80% — “Excel thông báo tệp này bị hỏng và đề nghị sửa chữa” — endpoint này thực hiện cùng một quá trình sửa chữa, phía máy chủ, mà không cần giao diện người dùng.

Khi nào nên chạy sửa chữa

Khi nhập dữ liệu. Nếu ứng dụng của bạn chấp nhận tải lên của người dùng, hãy chạy repair trước bất kỳ xử lý nào khác. Chi phí là một lần gọi thêm, nhưng nó ngăn ngừa các lỗi lan truyền sau này trong quy trình.
Khi xuất thất bại. Nếu một chuyển đổi hạ nguồn (ConversionController) thất bại với lỗi khó hiểu, hãy chạy repair trước, sau đó thử lại việc chuyển đổi.

7. Mẫu tích hợp

Mẫu: nhà máy workbook

Kết hợp tất cả các khả năng của ManagementController vào một endpoint nhà máy duy nhất trong ứng dụng của bạn:

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

Mỗi bước là một lời gọi API tới ManagementController hoặc DataProcessingController. Điểm cuối của bạn là một bộ điều phối mỏng.

Mẫu: audit-before-process

Trước khi thực hiện các thao tác tốn kém ở mức ô:

[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

Hai lời gọi kiểm tra này gần như không tốn gì, nhưng chúng ngăn ngừa các lỗi tốn kém để gỡ lỗi phát sinh khi ghi vào các vùng đã hợp nhất hoặc nhắm tới các bảng không tồn tại.

8. Các cân nhắc về hiệu suất

structure có chi phí thấp. Nó duyệt siêu dữ liệu, không phải nội dung ô. An toàn để gọi trên các workbook lớn.
mergedcells có chi phí thấp. Cùng lý do.
compress phụ thuộc vào CPU. Các mức cao hơn tốn nhiều hơn. Sử dụng mức 6 làm mặc định trừ khi bạn có lý do để tăng lên.
repair là việc tái tuần tự hoá toàn bộ. Đắt hơn compress. Thực hiện nó khi nhập dữ liệu, không phải trên mỗi yêu cầu.
accept-all-revisions mở rộng theo số lượng phiên bản. Hàng trăm phiên bản trong một tệp là ổn; hàng chục nghìn sẽ mất một chút thời gian.
Các biến thể từ xa vượt trội hơn các vòng quay nội bộ. Khi các tệp đã có trong lưu trữ đám mây, GET {name}/structure tránh việc tải tệp về máy của bạn chỉ để kiểm tra.

9. Khắc phục các vấn đề thường gặp

Triệu chứng	Nguyên nhân	Cách khắc phục
`400` on `add/worksheet`	Tên sheet đã tồn tại hoặc để trống	Chọn một tên duy nhất, hoặc để máy chủ tự gán tên
`400` on `rename/worksheet`	`sourceName` không khớp với bất kỳ sheet nào hiện có	Tên phân biệt chữ hoa chữ thường; gọi `worksheets` trước để liệt kê chúng
`500` on `compress` with `level=10`	Mức phải nằm trong khoảng 0–9	Sử dụng `level=9` để nén tối đa
`repair` returns a file that still won’t open	Sự hỏng nằm trong luồng image/VBA, không phải trong XML cấu trúc	`repair` không thể sửa hỏng ở mức dữ liệu; yêu cầu người dùng xuất bản sạch
`structure` returns empty `Worksheets` array	Tệp đã tải lên không phải là một workbook hợp lệ	Kiểm tra phần mở rộng và nội dung tệp; chạy `repair` trước
`accept-all-revisions` is a no-op	Workbook không bật tính năng theo dõi	Không sao — không có revision nghĩa là không có gì để chấp nhận
`mergedcells` returns empty array	Không có vùng hợp nhất nào trong worksheet	Sử dụng tín hiệu này để ghi an toàn ở bất kỳ vị trí nào

10. Kết hợp tất cả lại

Các endpoint của ManagementController là các endpoint nhỏ riêng lẻ. Sức mạnh của chúng đến từ việc kết hợp:

Tạo một workbook từ mẫu → nhập dữ liệu qua DataProcessingController → đổi tên các sheet → nén → giao. Đó là một quy trình báo cáo SaaS đầy đủ trong năm cuộc gọi HTTP.
Cấu trúc + mergedcells + ô → một lớp kiểm tra hiểu bất kỳ workbook nào bạn đưa vào, mà không cần Excel.
Sửa chữa khi nhập → accept-all-revisions → phần còn lại của quy trình của bạn chỉ bao giờ thấy các workbook sạch sẽ, đã hoàn thiện.

Bạn không cần một cụm máy chủ. Bạn không cần cài đặt Excel. Bạn chỉ cần curl và một kế hoạch.

Đào sâu: Các mẫu nâng cao với Aspose.Cells Cloud Management API#

1. Lấy cấu trúc đầy đủ của một workbook dưới dạng JSON#

Cục bộ#

Từ xa#

Bạn nhận được gì#

Tại sao điều này quan trọng#

2. Kiểm tra các vùng ô đã hợp nhất#

Bảng tính cục bộ#

Bảng tính từ xa#

Phản hồi#

Sử dụng nó để tránh bẫy mìn#

3. Chấp nhận các thay đổi được theo dõi (sửa đổi)#

Cục bộ#

Từ xa#

Quy trình hàng loạt#

4. Tạo dựa trên mẫu ở quy mô lớn#

Mẫu: một mẫu cho mỗi tenant#

Mẫu: nhà máy báo cáo#

5. Nén có mục đích#

6. Sửa chữa: những gì nó thực sự làm#

Khi nào nên chạy sửa chữa#

7. Mẫu tích hợp#

Mẫu: nhà máy workbook#

Mẫu: audit-before-process#

8. Các cân nhắc về hiệu suất#

9. Khắc phục các vấn đề thường gặp#

10. Kết hợp tất cả lại#

Đào sâu: Các mẫu nâng cao với Aspose.Cells Cloud Management API

1. Lấy cấu trúc đầy đủ của một workbook dưới dạng JSON

Cục bộ

Từ xa

Bạn nhận được gì

Tại sao điều này quan trọng

2. Kiểm tra các vùng ô đã hợp nhất

Bảng tính cục bộ

Bảng tính từ xa

Phản hồi

Sử dụng nó để tránh bẫy mìn

3. Chấp nhận các thay đổi được theo dõi (sửa đổi)

Cục bộ

Từ xa

Quy trình hàng loạt

4. Tạo dựa trên mẫu ở quy mô lớn

Mẫu: một mẫu cho mỗi tenant

Mẫu: nhà máy báo cáo

5. Nén có mục đích

6. Sửa chữa: những gì nó thực sự làm

Khi nào nên chạy sửa chữa

7. Mẫu tích hợp

Mẫu: nhà máy workbook

Mẫu: audit-before-process

8. Các cân nhắc về hiệu suất

9. Khắc phục các vấn đề thường gặp

10. Kết hợp tất cả lại