Создание, управление, обслуживание: Практическое руководство по API управления облаком Aspose.Cells
Создание пустой рабочей книги, переименование листа, сжатие раздутого файла или восстановление повреждённого — это небольшие повседневные задачи, которые всё ещё отнимают время разработчиков, когда у вас нет подходящего инструмента.
ManagementControllerпревращает их в однострочники.
Каждое приложение, работающее с электронными таблицами, в конечном итоге сталкивается с одними и теми же непривлекательными задачами:
- Создание нового, пустого рабочего листа «на лету» — иногда из фирменного шаблона.
- Перестановка листов — добавление, переименование, удаление, изменение порядка — потому что структура данных изменилась со вчерашнего дня.
- Уменьшение размера файла — сжатие 40 МБ XLSX до 8 МБ перед отправкой по электронной почте.
- Восстановление повреждённого файла — того, который пользователь сохранил неправильно, или инструмент экспортировал с ошибками.
- Анализ структуры — определение, какие листы, таблицы, диаграммы и области объединённых ячеек находятся в рабочей книге без её открытия.
Контроллер ManagementController в микросервисе Aspose.Cells Cloud (исходный код: src/Aspose.Cells.Cloud.MicroService/Controllers/ManagementController.cs) обрабатывает всё это через чистый REST‑интерфейс. В этой статье представлены его 15 конечных точек с готовыми примерами 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 |
Каждый конечный пункт принимает книгу Excel в виде multipart‑ввода (локально) или ссылается на уже находящуюся в облачном хранилище (удалённо) и возвращает либо изменённый поток книги, JSON‑payload, либо простой OK.
2. Пятнадцать конечных точек в обзоре
| # | HTTP | Маршрут | Источник | Что делает |
|---|---|---|---|---|
| 1 | PUT | /v4.0/cells/spreadsheet/create |
— | Создать новую книгу, при необходимости из шаблона |
| 2 | PUT | /v4.0/cells/spreadsheet/worksheets |
Local | Список всех листов (имя + тип) |
| 3 | PUT | /v4.0/cells/spreadsheet/add/worksheet |
Local | Добавить лист с типом, именем, позицией |
| 4 | PUT | /v4.0/cells/spreadsheet/delete/worksheet |
Local | Удалить лист по имени |
| 5 | PUT | /v4.0/cells/spreadsheet/rename/worksheet |
Local | Переименовать лист |
| 6 | PUT | /v4.0/cells/spreadsheet/move/worksheet |
Local | Переместить лист на новый индекс |
| 7 | PUT | /v4.0/cells/spreadsheet/compress |
Local | Сжать книгу для уменьшения размера |
| 8 | PUT | /v4.0/cells/spreadsheet/repair |
Local | Восстановить повреждённую книгу |
| 9 | GET | /v4.0/cells/{name}/worksheets/{worksheet}/mergedcells |
Cloud | Список областей объединённых ячеек в удалённом листе |
| 10 | PUT | /v4.0/cells/spreadsheet/mergedcells |
Local | Список областей объединённых ячеек в локальном листе |
| 11 | PUT | /v4.0/cells/spreadsheet/accept-all-revisions |
Local | Принять все отслеживаемые изменения |
| 12 | PUT | /v4.0/cells/{name}/accept-all-revisions |
Cloud | Принять все отслеживаемые изменения в удалённом файле |
| 13 | PUT | /v4.0/cells/spreadsheet/structure |
Local | Получить полную структуру в формате JSON |
| 14 | GET | /v4.0/cells/{name}/structure |
Cloud | Получить полную структуру удалённого файла в формате 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. 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
| Parameter | Type | Default | Meaning |
|---|---|---|---|
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 MB часто приводит к размеру в диапазоне 6–10 MB. Содержимое идентично; только 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, нет сервера для обслуживания.