Знайдіть, виправте, перевірте: Повний посібник з API пошуку, заміни та перевірки битих посилань Aspose.Cells Cloud (.NET / Python / Java / cURL)
“Яка з наших 400 бюджетних робочих книг все ще містить Old Vendor Ltd?” “Замініть кожен заповнювач
{{COMPANY}}у цьому шаблоні.” “Чи залишилися якісь наші звіти, які все ще посилаються на той домен, який ми вивели з експлуатації минулого року?” — три дуже різні питання, одна спільна відповідь: REST‑виклик, який читає та переписує електронні таблиці в хмарі, без встановленого Excel ніде.
Проблеми зі вмістом електронних таблиць з’являються майже в кожній кодовій базі, що містить багато даних:
- Content audit — знаходження кожної клітинки, форми або гіперпосилання, які згадують застарілу назву продукту, стару адресу офісу або застарілу юридичну особу;
- Template rendering — заповнення токенів
{{PLACEHOLDER}}по всіх листах перед надсиланням робочої книги клієнту; - Link rot — перевірка того, чи URLs, вбудовані у робочу книгу, все ще працюють, перед тим як завдання з відповідності або архівування його затвердить;
- Bulk correction — виправлення помилки або неправильно написаного значення стовпця у десятках листів, або обмежено лише одним регіоном одного листа.
Традиційні варіанти — бібліотека скриптів, що працює на вашій машині, макрос Excel або COM‑компонент на Windows‑сервері — всі означають, що саме ви розміщуєте та масштабуєте логіку електронних таблиць. Aspose.Cells Cloud перетворює це на простий REST: надішліть файл (або лише його назву), отримайте збіги — або виправлений файл — назад.
У цьому дописі розглядаються API, які надає основний SearchController у мікросервісі Aspose.Cells Cloud (джерело: src/Aspose.Cells.Cloud.MicroService/Controllers/SearchController.cs), з робочими прикладами у cURL та C# (.NET), а також примітки для користувачів Python і Java.
1. Що може робити SearchController?
SearchController охоплює три сімейства можливостей, кожне доступне на декількох областях:
| Сім’я | Що воно робить | Змінює робочу книгу? |
|---|---|---|
| Search | Повертає текстові елементи, що відповідають запиту, — разом з їх аркушем та позицією клітинки/форми/гіперпосилання | Ні |
| Replace | Замінює знайдений текст, а потім або передає виправлений файл у потоці назад, або зберігає його в хмарному сховищі | Так |
| Broken links | Перевіряє кожне http(s) гіперпосилання у робочій книзі та повертає ті, які не вдалося розв’язати |
Ні |
І кожна сім’я доступна у чотирьох областях, що є причиною довгого списку кінцевих точок:
| Область | Пошук | Замінити | Зламані посилання |
|---|---|---|---|
| Локальний файл → онлайн обробка (завантаження в тіло запиту) | PUT /v4.0/cells/search/content |
PUT /v4.0/cells/replace/content |
PUT /v4.0/cells/search/broken-links |
| Повна робоча книга у хмарному сховищі | PUT /v4.0/cells/{name}/search/content |
PUT /v4.0/cells/{name}/replace/content |
PUT /v4.0/cells/{name}/search/broken-links |
| Один лист у хмарному сховищі | PUT /v4.0/cells/{name}/worksheets/{worksheet}/search/content |
PUT /v4.0/cells/{name}/worksheets/{worksheet}/replace/content |
PUT /v4.0/cells/{name}/worksheets/{worksheet}/search/broken-links |
| Один діапазон у хмарному сховищі | PUT /v4.0/cells/{name}/worksheets/{worksheet}/ranges/{cellArea}/search/content |
PUT /v4.0/cells/{name}/worksheets/{worksheet}/ranges/{cellArea}/replace/content |
PUT /v4.0/cells/{name}/worksheets/{worksheet}/ranges/{cellArea}/search/broken-links |
Плюс два бонусних кінцевих точки, які виводять кожен текстовий елемент у робочій книзі — дивіться §4:
| Мета | Кінцева точка |
|---|---|
| Усі текстові елементи у хмарному файлі | PUT /v4.0/cells/{name}/search/content/all-textitems |
| Усі текстові елементи у локальному завантаженні | PUT /v4.0/cells/search/content/all-textitems |
Примітка щодо реалізації: маршрути мають префікс
v{version:apiVersion}/cellsі цей контролер має[ApiVersion("4.0")], тому живі виклики виглядають якhttps://api.aspose.cloud/v4.0/cells/.... У цьому контролері все єPUT— навіть пошуки лише для читання — тому що пошук моделюється як операція, подана проти ресурсу, а не кешованеGET.
Два режими роботи та чому вони важливі
Контролер декорує кожну дію, а декоратор точно вказує, звідки походить файл:
[OnlineOperation]— stateless. Ви завантажуєте робочий лист у тіло запиту (multipart), сервер обробляє його в пам’яті, і нічого не зберігається у хмарному сховищі. Ідеально підходить для «просто скажи, що в цьому файлі» та для одноразового шаблонізування.[CloudFileOperation]— storage-backed. Сервер отримує{name}з хмарного сховища (за потреби вfolder=), виконує роботу і — для операцій заміни — записує результат безпосередньо назад. Нічого не передається на ваш комп’ютер.
Це єдине розрізнення, разом із сегментами маршруту {worksheet} / {cellArea}, становить всю ментальну модель. Решта цього допису — лише деталі.
2. Моделі відповіді, які ви фактично будете розбирати
Обидві сімейства пошуку повертають невелику, плоску, легко прив’язувану форму. Пошук повертає SearchResponse:
{
"Code": 200,
"Status": "OK",
"TextItems": [
{
"Filename": "Book1.xlsx",
"Worksheet": "Q3 Forecast",
"Position": "Cell:B7",
"Content": "Old Vendor Ltd"
},
{
"Filename": "Book1.xlsx",
"Worksheet": "Q3 Forecast",
"Position": "Shape:TextBox 3",
"Content": "Prepared by Old Vendor Ltd"
}
]
}
Пошук пошкоджених посилань повертає BrokenLinksResponse:
{
"Code": 200,
"Status": "OK",
"BrokenLinks": [
{
"Filename": "Book1.xlsx",
"Worksheet": "Links",
"Position": "Hyperlink:Sheet1!B4",
"LinkAddress": "https://retired-domain.example.com/report"
}
]
}
Дві речі варто відразу зазначити:
Position— це позначене розташування, а не лише адреса клітини. Воно має префіксCell:,Hyperlink:абоShape:, що дозволяє одному плоскому списку повідомляти, який тип об’єкта збігся. Цей тег — різниця між «виправити клітину B7» і «виправити текстове поле, що знаходиться над B7».- Обидві моделі самодокументуються для звітності —
FilenameіWorksheetповертаються для кожного елементу, тому сканування багатьох робочих книг можна об’єднати в одну таблицю аудиту без постобробки.
3. Дві речі, які вам потрібні перед початком
- Зареєструйте безкоштовний обліковий запис на Aspose Cloud Dashboard і створіть застосунок, щоб отримати
Client IDтаClient Secret(SDK автоматично обмінює їх на JWT — не потрібно самостійно створювати заголовки авторизації). - Встановіть SDK для обраної вами мови:
<!-- .NET -->
<PackageReference Include="Aspose.Cells-Cloud" Version="25.x" />
# Python
pip install asposecellscloud
<!-- Java (Maven) — note: NOT on Maven Central, so the Aspose repo below is required -->
<repositories>
<repository>
<id>AsposeJavaAPI</id>
<name>Aspose Java API</name>
<url>https://repository.aspose.cloud/repo/</url>
</repository>
</repositories>
<dependency>
<groupId>com.aspose</groupId>
<artifactId>aspose-cells-cloud</artifactId>
<version>26.8</version>
</dependency>
Не потрібен SDK? Все — простий REST, тому cURL працює так само (дивіться нижче). Сімейство пошуку/заміни/зламаних посилань також доступне через типізовані моделі запитів SDK —
SearchSpreadsheetContentRequest,ReplaceContentInRemoteRangeRequestта їхні друзі — що використовується у наведених нижче фрагментах C#.
4. Сценарій A: Пошук локального файлу в інтернеті (нічого не зберігається)
Це PUT /v4.0/cells/search/content — завантажте книгу, отримайте збіги. Немає хмарного сховища, немає очищення, жодної копії не залишилося.
① cURL
# 1) First, get a 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) Find "Old Vendor Ltd" anywhere in a local workbook
curl -X PUT "https://api.aspose.cloud/v4.0/cells/search/content" \
-H "Authorization: Bearer $TOKEN" \
--data-urlencode "searchText=Old Vendor Ltd" \
--data-urlencode "ignoringCase=true" \
-F "file=@Book1.xlsx"
Обмежте його одним листом або однією областю одного листа, використовуючи ще два параметри запиту:
# Only "Q3 Forecast", only the range A1:F40
curl -X PUT "https://api.aspose.cloud/v4.0/cells/search/content" \
-H "Authorization: Bearer $TOKEN" \
--data-urlencode "searchText=Old Vendor Ltd" \
--data-urlencode "worksheet=Q3 Forecast" \
--data-urlencode "cellArea=A1:F40" \
-F "file=@Book1.xlsx"
② C# / .NET
using Aspose.Cells.Cloud.SDK.Api;
using Aspose.Cells.Cloud.SDK.Request;
var cellsApi = new CellsApi("YOUR_CLIENT_ID", "YOUR_CLIENT_SECRET");
// Local file, whole workbook
var request = new SearchSpreadsheetContentRequest(
spreadsheet: "C:/audit/Book1.xlsx", // local file path
searchText: "Old Vendor Ltd",
ignoringCase: true);
SearchResponse response = cellsApi.SearchSpreadsheetContent(request);
foreach (var item in response.TextItems)
{
Console.WriteLine($"{item.Worksheet} | {item.Position} | {item.Content}");
}
// Same call, scoped to one sheet and one range
var scoped = new SearchSpreadsheetContentRequest(
spreadsheet: "C:/audit/Book1.xlsx",
searchText: "Old Vendor Ltd",
ignoringCase: true,
sheetname: "Q3 Forecast",
cellarea: "A1:F40");
Моделі запитів також містять
password(відкриття захищеної книги) таregoin(налаштування регіону/локалі) — ті ж самі необов’язкові параметри, які ви побачите у варіантах cloud-storage якstorageName. Зауважте, що .NET SDK зберігає написанняregoin; Python SDK називає ті ж два параметриpasswordіregion.
③ Python / Java
Python SDK обгортає ту ж сімейство кінцевих точок, причому поля моделі запиту відображаються на поля C# один до одного, але у snake_case:
from asposecellscloud.apis.cells_api import CellsApi
from asposecellscloud.requests import (
SearchSpreadsheetContentRequest,
SearchContentInRemoteRangeRequest,
)
instance = CellsApi("YOUR_CLIENT_ID", "YOUR_CLIENT_SECRET")
# Local upload — returned items carry Worksheet / Position / Content
local = instance.search_spreadsheet_content(
SearchSpreadsheetContentRequest(
"Book1.xlsx", "Old Vendor Ltd",
ignoring_case=True, worksheet="Q3 Forecast", cell_area="A1:F40"))
# Range-scoped search of a file already in cloud storage
remote = instance.search_content_in_remote_range(
SearchContentInRemoteRangeRequest(
"Book1.xlsx", "Q3 Forecast", "A1:F40", "Old Vendor Ltd",
ignoring_case=True, folder="Reports"))
for item in remote.text_items:
print(item.worksheet, item.position, item.content)
Java SDK має таку ж структуру, де об’єкти Request створюються за допомогою сеттерів:
import com.aspose.cloud.cells.api.CellsApi;
import com.aspose.cloud.cells.model.SearchResponse;
import com.aspose.cloud.cells.request.SearchContentInRemoteRangeRequest;
public class SearchDemo {
public static void main(String[] args) throws Exception {
CellsApi api = new CellsApi("YOUR_CLIENT_ID", "YOUR_CLIENT_SECRET");
SearchContentInRemoteRangeRequest req = new SearchContentInRemoteRangeRequest();
req.setName("Book1.xlsx");
req.setWorksheet("Q3 Forecast");
req.setCellArea("A1:F40");
req.setSearchText("Old Vendor Ltd");
req.setIgnoringCase(true);
req.setFolder("Reports");
SearchResponse response = api.searchContentInRemoteRange(req);
response.getTextItems().forEach(i ->
System.out.println(i.getWorksheet() + " | " + i.getPosition() + " | " + i.getContent()));
}
}
Якщо ви працюєте з чистим REST, наведений вище cURL є повним контрактом — поле multipart просто має містити ім’я файлу, оскільки сервіс визначає назву робочої книги (а отже її формат) за ним.
5. Сценарій B: Пошук файлу, який вже знаходиться в хмарному сховищі
Коли робоча книга вже знаходиться в Aspose Cloud Storage, повністю пропустіть завантаження — сервіс читає її там, де вона розташована:
# Whole workbook
curl -X PUT "https://api.aspose.cloud/v4.0/cells/Book1.xlsx/search/content" \
-H "Authorization: Bearer $TOKEN" \
--data-urlencode "searchText=Old Vendor Ltd" \
--data-urlencode "ignoringCase=true" \
--data-urlencode "folder=Reports"
# Just one worksheet
curl -X PUT "https://api.aspose.cloud/v4.0/cells/Book1.xlsx/worksheets/Q3%20Forecast/search/content" \
-H "Authorization: Bearer $TOKEN" \
--data-urlencode "searchText=Old Vendor Ltd"
# Just one range of one worksheet
curl -X PUT "https://api.aspose.cloud/v4.0/cells/Book1.xlsx/worksheets/Q3%20Forecast/ranges/A1:F40/search/content" \
-H "Authorization: Bearer $TOKEN" \
--data-urlencode "searchText=Old Vendor Ltd"
// Whole workbook in storage
var response = cellsApi.SearchContentInRemoteSpreadsheet(
new SearchContentInRemoteSpreadsheetRequest(
name: "Book1.xlsx",
searchText: "Old Vendor Ltd",
ignoringCase: true,
folder: "Reports"));
// One worksheet
var sheetHits = cellsApi.SearchContentInRemoteWorksheet(
new SearchContentInRemoteWorksheetRequest(
name: "Book1.xlsx",
sheetname: "Q3 Forecast",
searchText: "Old Vendor Ltd",
folder: "Reports"));
// One range
var rangeHits = cellsApi.SearchContentInRemoteRange(
new SearchContentInRemoteRangeRequest(
name: "Book1.xlsx",
sheetname: "Q3 Forecast",
cellArea: "A1:F40",
searchText: "Old Vendor Ltd",
ignoringCase: true,
folder: "Reports"));
Чому три кінцеві точки замість однієї? Тому що маршрут несе область. Кінцева точка whole-workbook приймає ім’я та запит; кінцева точка worksheet приймає сегмент листа; кінцева точка range приймає лист і сегмент діапазону. Це чиста, кешована форма REST — і це означає, що параметри «звузити пошук» (
worksheet,cellArea) існують лише на кінцевій точці local-file, що варто пам’ятати, коли ви переносите виклик з однієї області в іншу.
6. Сценарій C: Отримати кожен текстовий елемент у робочій книзі
Інколи у вас немає пошукового запиту — вам потрібен інвентар. Кінцеві точки all-textitems повертають кожен текстовий елемент у робочій книзі, тому ви можете порівняти дві ревізії, створити глосарій перекладів або передати дані індексатору:
# Cloud file — every text item
curl -X PUT "https://api.aspose.cloud/v4.0/cells/Book1.xlsx/search/content/all-textitems" \
-H "Authorization: Bearer $TOKEN" \
--data-urlencode "folder=Reports"
# Local upload — every text item
curl -X PUT "https://api.aspose.cloud/v4.0/cells/search/content/all-textitems" \
-H "Authorization: Bearer $TOKEN" \
-F "file=@Book1.xlsx"
Відповідь має той самий SearchResponse конверт, у якому Content заповнено для кожного рядка клітинки, підпису гіперпосилання та тексту форми у файлі. Це примітив “grep the whole workbook”.
7. Сценарій D: Замінити — і два зовсім різних результати
Replace — це місце, де API розділяється на дві частини, і розділення навмисне:
| Локальне завантаження → завантажити виправлений файл | Файл у хмарі → збережено назад у сховище | |
|---|---|---|
| Кінцева точка | PUT /v4.0/cells/replace/content |
PUT /v4.0/cells/{name}/replace/content |
| Повертає | Потік файлу (той самий формат, який ви завантажили) | CellsCloudResponse { "Code": 200, "Status": "OK" } |
| Сховище змінено | Немає | Оригінальний файл перезаписано |
① Замінити у локальній робочій книзі, потоково повернути результат
curl -X PUT "https://api.aspose.cloud/v4.0/cells/replace/content" \
-H "Authorization: Bearer $TOKEN" \
--data-urlencode "searchText={{COMPANY}}" \
--data-urlencode "replaceText=Northwind Traders" \
-F "file=@template.xlsx" \
-o template-rendered.xlsx
using Aspose.Cells.Cloud.SDK.Request;
var request = new ReplaceSpreadsheetContentRequest(
spreadsheet: "C:/templates/template.xlsx",
searchText: "{{COMPANY}}",
replaceText: "Northwind Traders");
// Option A: get the corrected workbook as a Stream
using Stream corrected = cellsApi.ReplaceSpreadsheetContent(request);
using var outFile = File.Create("C:/templates/template-rendered.xlsx");
corrected.CopyTo(outFile);
// Option B: let the SDK write it for you (.NET overload with an output path)
// cellsApi.ReplaceSpreadsheetContent(request, "C:/templates/template-rendered.xlsx");
Тут також доступні два параметри області — sheetname і cellarea — так що ви можете рендерити заповнювачі в одному листі, не торкаючись решти шаблону.
② Замінити у хмарній робочій книзі, зберегти на місці
# Whole workbook, saved back to storage
curl -X PUT "https://api.aspose.cloud/v4.0/cells/Book1.xlsx/replace/content" \
-H "Authorization: Bearer $TOKEN" \
--data-urlencode "searchText=Old Vendor Ltd" \
--data-urlencode "replaceText=Northwind Traders" \
--data-urlencode "folder=Reports"
# One worksheet
curl -X PUT "https://api.aspose.cloud/v4.0/cells/Book1.xlsx/worksheets/Q3%20Forecast/replace/content" \
-H "Authorization: Bearer $TOKEN" \
--data-urlencode "searchText=Old Vendor Ltd" \
--data-urlencode "replaceText=Northwind Traders" \
--data-urlencode "folder=Reports"
# One range
curl -X PUT "https://api.aspose.cloud/v4.0/cells/Book1.xlsx/worksheets/Q3%20Forecast/ranges/A1:F40/replace/content" \
-H "Authorization: Bearer $TOKEN" \
--data-urlencode "searchText=Old Vendor Ltd" \
--data-urlencode "replaceText=Northwind Traders" \
--data-urlencode "folder=Reports"
// Whole workbook — result saved back into cloud storage
cellsApi.ReplaceContentInRemoteSpreadsheet(
new ReplaceContentInRemoteSpreadsheetRequest(
name: "Book1.xlsx",
searchText: "Old Vendor Ltd",
replaceText: "Northwind Traders",
folder: "Reports"));
// Range-scoped
cellsApi.ReplaceContentInRemoteRange(
new ReplaceContentInRemoteRangeRequest(
name: "Book1.xlsx",
searchText: "Old Vendor Ltd",
replaceText: "Northwind Traders",
worksheet: "Q3 Forecast",
cellarea: "A1:F40",
folder: "Reports"));
Заміну на місці за задумом є руйнівною. Варіанти в хмарі перезаписують
{name}— копія резервної копії не створюється. Для робочих процесів з великим навантаженням аудиту зберігайте копію з версією (наприклад, спочатку завантажтеBook1-2026-09-11.xlsx, а потім замініть) або використовуйте варіант локального завантаження та зберігайте повернутий потік самостійно.
8. Сценарій E: Знайти биті посилання, перш ніж хтось інший їх знайде
Перевірка посилань — це прихована функція тут, це те, що втомлює писати самому і соромно пропускати. Доступні всі чотири області; варіант з локальним файлом — найшвидша перевірка на здоровий глузд:
# Local workbook, whole file
curl -X PUT "https://api.aspose.cloud/v4.0/cells/search/broken-links" \
-H "Authorization: Bearer $TOKEN" \
-F "file=@Book1.xlsx"
# Cloud workbook, whole file
curl -X PUT "https://api.aspose.cloud/v4.0/cells/Book1.xlsx/search/broken-links" \
-H "Authorization: Bearer $TOKEN" \
--data-urlencode "folder=Reports"
# Cloud workbook, one worksheet
curl -X PUT "https://api.aspose.cloud/v4.0/cells/Book1.xlsx/worksheets/Links/search/broken-links" \
-H "Authorization: Bearer $TOKEN" \
--data-urlencode "folder=Reports"
var broken = cellsApi.SearchSpreadsheetBrokenLinks(
new SearchSpreadsheetBrokenLinksRequest(
spreadsheet: "C:/audit/Book1.xlsx"));
foreach (var link in broken.BrokenLinks)
{
Console.WriteLine($"{link.Worksheet} {link.Position} -> {link.LinkAddress}");
}
Результат — це список, з яким можна працювати безпосередньо: кожен запис містить назву листа, позицію та проблемний LinkAddress.
9. Що саме сканується? (деталі реалізації, які змінюють ваші очікування)
Це частина, яка розрізняє успішну інтеграцію від несподіваної. Читаючи WorkbookExtension.cs, пошук проходить три різні типи елементів у кожному листі:
| Тип елементу | Джерело | Що збігається | Position тег |
|---|---|---|---|
| Рядки клітинок | worksheet.Cells |
Рядкове значення клітинки | Cell:A1 |
| Гіперпосилання | worksheet.Hyperlinks |
Обидва — адреса посилання і його текст відображення | Hyperlink:Sheet1!B4 |
| Фігури | worksheet.Shapes |
shape.Text — текстові блоки, підказки, мітки |
Shape:TextBox 3 |
І ось поведінки, які варто знати перед тим, як ви їх проєктуєте:
Шукаються лише клітинки-рядки. Сканування фільтрує за CellValueType.IsString. Клітинка, що містить число, дату або логічне значення, пропускається — тому пошук 2025 не збігатиметься з клітинкою, відформатованою як дата, чия серійна величина випадково дорівнює 2025. Клітинки, формули яких обчислюються у текст, збігаються, оскільки їх тип значення — рядок.
Чутливість до регістру — єдина опція збігу. ignoringCase перемикає між порівняннями InvariantCultureIgnoreCase і InvariantCulture — нічого більше. Немає режиму «ціле слово», regex або «збіг усієї клітинки», незважаючи на те, що можуть вказувати згенеровані API‑документи. Якщо вам потрібна така семантика, отримайте інвентар all-textitems і відфільтруйте його самостійно.
Replace — просте, чутливе до регістру, буквальне підстановлення. Прапорець ignoringCase у Search не має еквіваленту у Replace — шлях заміни взагалі не має параметра нечутливості до регістру. І два кодових шляхи відрізняються внутрішньо: заміна всього листа делегується до методу Worksheet.Replace(...) движка, тоді як заміна в межах діапазону проходить по діапазону і переписує кожну текстову клітинку за допомогою cell.StringValue.Replace(...). Практичний наслідок: заміна в межах діапазону торкається лише текстових клітинок, і вона буквальна, а не основана на шаблонах.
Гіперпосилання, що збігаються, повідомляють адресу, а не підпис. Коли пошук збігається з текстом відображення гіперпосилання, повернене Content все ще є hyperlink.Address. Якщо ви формуєте звіт “знайдено тут”, очікуйте URL — підпис не повертається.
Перевірка битих посилань розглядає лише http:// та https://. mailto: посилання, локальні шляхи до файлів та внутрішні якорі #Sheet1!A1 повністю пропускаються — їх ніколи не тестують, тому вони ніколи не з’являться у результатах. Він також сканує гіперпосилання, прикріплені до форм та клітинок, саме там, де мертві посилання схильні ховатися. Зверніть увагу, що Position битого посилання створюється з необробленого hyperlink.Area (а не з більш зручного Area.ToRangName(), який використовують кінцеві точки пошуку), тому не варто припускати, що два підходи відображають позиції ідентично — розберіть пару Worksheet + LinkAddress, якщо потрібен стабільний ключ.
“Broken” означає “недоступний”, а не “неправильний код статусу”. Перевірка надсилає HTTP HEAD запит для кожного посилання і розглядає будь-яку відповідь — включаючи 404 або 500 — як доступну; вона позначає посилання як broken лише коли запит викидає (невдача DNS, відхилене з’єднання, помилка TLS, тайм-аут). Тому сприймайте результат як “посилання, які не вдалося зв’язатися”. Якщо вам дійсно потрібні “посилання, які не повертають 2xx”, вам слід самостійно перевірити повернуті значення LinkAddress yourself.
cellArea приймається, але не застосовується на кінцевих точках broken-link. Реалізація BrokenLinks фільтрує лише за назвою листа; аргумент cell-area передається, але ніколи не використовується. На практиці це означає, що .../ranges/A1:F40/search/broken-links наразі поводиться так само, як /worksheet/search/broken-links для того ж листа — посилання перевіряються по всьому листу. Визначайте область своїх звітів відповідно (або фільтруйте повернутий список за позицією), а не припускайте, що діапазон звужує перевірку.
Ні одне з цих не є блокувальниками — це різниця між функцією, яка «працює у демонстрації», і тією, яка передбачувано працює у продакшені.
10. Обробка помилок та оперативні нотатки
Контракт, який документує контролер
| Status | Meaning | Typical cause |
|---|---|---|
| 400 | Неправильний запит | Недійсний URL/параметри — напр., некоректний cellArea, або відсутній searchText |
| 401 | Неавторизовано | Не вдалося автентифікація або не надано дійсних облікових даних |
| 404 | Не знайдено | Вихідний файл недоступний у хмарному сховищі |
| 500 | Помилка сервера | Сервіс зіткнувся з аномалією під час отримання даних електронної таблиці |
Внутрішньо кожна дія обгортає свою роботу у допоміжний (WorkbookElementOperation, UpdateWorkbookElementOperation, UpdateWorkbookElementOperationAndSave), який перехоплює помилки і повторно викидає їх як CellsApiException з префіксом назви операції — наприклад SearchContentInRemoteRange Error Message: .... Ця назва операції — це рядок, який ви побачите у своїх журналах:
| Operation name | Endpoint family |
|---|---|
SearchSpreadsheetContent, SearchContentInRemoteSpreadsheet |
Локальний / віддалений пошук |
SearchContentInRemoteWorksheet, SearchContentInRemoteRange |
Обмежений віддалений пошук |
ReplaceSpreadsheetContent |
Локальна заміна (результат у потоках) |
ReplaceContentInRemoteSpreadsheet, ReplaceContentInRemoteWorksheet, ReplaceContentInRemoteRange |
Віддалена заміна (зберігає результат) |
SearchSpreadsheetBrokenLinks, SearchBrokenLinksInRemoteSpreadsheet, SearchBrokenLinksInRemoteWorksheet, SearchBrokenLinksInRemoteRange |
Перевірка посилань |
Необов’язкові параметри, які SDK надає
Окрім задокументованих параметрів, моделі запитів cloud‑storage мають однакові три необов’язкові налаштування:
password— відкриває книгу, захищену паролем (пошук не потребує доступу на запис, тому файли, захищені лише для читання, працюють нормально);storageName— вказує власне/приєднане хмарне сховище замість сховища за замовчуванням (Python:storage_name);regoin— параметр регіону/локалі, що використовується при інтерпретації книги (Python називає цеregion).
Аутентифікація
Усі SDK автоматично автентифікуються за допомогою OAuth 2.0 client_credentials та JWT; при використанні чистого cURL спочатку один раз викличте /connect/token (див. §4, ①).
11. Чому Aspose.Cells Cloud для пошуку та заміни?
- ✅ Zero local dependencies — без Office/Excel, без COM, без хосту скриптів. Викликається з будь-якої мови, будь-якої платформи (Linux, контейнери, безсерверні середовища);
- ✅ Deeper than text search — комірки, shapes і hyperlinks є першокласними об’єктами пошуку, саме там, де реальні електронні таблиці зберігають свій вміст;
- ✅ Scoped operations — workbook / worksheet / range, тому ви можете виправити одну область одного листа без переписування 50 MB файлу;
- ✅ Cloud-native or stateless — файли, що вже зберігаються, ніколи не залишають сховище; локальні операції завантаження нічого не зберігають;
- ✅ High-fidelity rewriting — заміни застосовуються через Aspose.Cells engine і повторно серіалізуються, тому формули, стилі, діаграми та форматування зберігаються під час циклу;
- ✅ One shape across SDKs — cURL, .NET, Python і Java поверхні відображаються 1:1, тому шаблон, скопійований з однієї мови, працює в інших.
Почніть зараз: зареєструйтесь на Aspose Cloud Dashboard, створіть застосунок, вставте ваші облікові дані у будь‑який фрагмент коду вище та вкажіть один зі своїх робочих зошитів — ви отримаєте працюючий аудит вмісту за кілька хвилин.
Знайшли це корисним? Поставте зірочку, додайте в закладки або поділіться — і розкажіть у коментарях, для чого ви використовуєте пошук і заміну в робочій книзі.