იპოვეთ, გასწორეთ, გადამოწმეთ: სრული გიდი Aspose.Cells Cloud Search, Replace & Broken-Link API (.NET / Python / Java / cURL)

“რომელი ჩვენი 400 ბიუჯეტის სამუშაო წიგნია, რომელიც ჯერ კიდევ აჩვენებს Old Vendor Ltd?” “შეცვალეთ ყველა {{COMPANY}} ადგილმჭერი ამ შაბლონში.” “ჩვენი რომელიმე ანგარიში მაინც ბმულდება იმ დომენზე, რომელიც გავატოვეთ ბოლო წელს?” — სამი ძალიან განსხვავებული კითხვა, ერთი საერთო პასუხი: REST‑გამოძახება, რომელიც კითხულობს და გადაწერს ცხრილებს ღრუბელში, Excel-ის გარეშე სადაცაც.

სპრედშీట్ შინაარსის პრობლემები თითქმის ყველა მონაცემებით სავსე კოდის ბაზაში გამოჩნდება:

• შიგთავსის აუდიტი — ყველა უჯრედი, ფორმა ან ჰიპერლინკის პოვნება, რომელიც აღნიშნავს მოძველებულ პროდუქტის სახელს, ძველ ოფისის მისამართს ან მოძველებულ იურიდიულ ერთეულს;
• თარგის რენდერი — {{PLACEHOLDER}} ტოკენების შევსება ფურცლებისა მიხედვით, სანამ სამუშაო წიგნაკი მომხმარებელზე გაიგზავნება;
• ბმულის გადამრიცხვი — შემოწმება, რომ სამუშაო წიგნაკში ჩასმული URL-ები ჯერ კიდევ მუშაობენ, სანამ შესაბამისობის ან არქივის სამუშაო მასალა მასზე ხელის ცემა;
• მასობრივი კორექცია — ტიპოგრაფიული შეცდომის ან არასწორად დაწერილი სვეტის მნიშვნელობის გასწორება ათასობით ფურცლზე, ან მხოლოდ ერთი ფურცლის ერთ რეგიონის ფარგლებში.

ტრადიციული არჩევანები — თქვენი კომპიუტერში გაშვებული სკრიპტინგის ბიბლიოთეკა, Excel მაკრო, ან Windows სერვერზე COM კომპონენტი — ყველა ნიშნავს, რომ თქვენ ხართ, ვინც ჰოსტირებს და მასშტაბირებს ცხრილურ ლოგიკას. Aspose.Cells Cloud მას გარდაქმნის ჩვეულებრივ REST-ზე: გააგზავნეთ ფაილი (ან უბრალოდ ფაილის სახელი), მიიღეთ შესაბამისობები — ან შესწორებული ფაილი — უკან.

ეს პოსტში გადის API-ებზე, რომლებიც გამოყოფილია ბირთვით SearchController-ში Aspose.Cells Cloud მიკროსერვისში (წყარო: src/Aspose.Cells.Cloud.MicroService/Controllers/SearchController.cs), მუშაობის მაგალითებით cURL and C# (.NET), ასევე შენიშვნებით Python და Java მომხმარებლებისთვის.

1. SearchController-ის რა შეუძლია?

SearchController შეიცავს სამი შესაძლებლობის ოჯახს, თითოეულიც ხელმისაწვდომია რამდენიმე შუალედში:

და თითოეული ოჯახი გამოჩნდება ოთხი შუალედში, რაც არის ადგილმდებარეობა, სადაც საბოლოო ბिंदვების სია გრძელდება:

და კიდევ ორი ბონუსის საბოლოო წერტილი, რომელიც გადატვირთავს ყოველ ტექსტურ ელემენტს სამუშაო წიგნში — იხილეთ §4:

განხორციელების შენიშვნა: მარშრუტები პრეფიქსირებულია 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"
    }
  ]
}

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

1. Position არის მონიშნული მდებარეობა, არა მხოლოდ უჯრედის მისამართი. იგი პრეფიქსირებულია Cell:, Hyperlink: ან Shape:, რაც აძლევს ერთ ბრტყელ სიას შესაძლებლობას, რომ გაგაცნოთ რომელი ტიპის ელემენტი დაემატა. ეს ტეგია განსხვავებაა “გასწორეთ უჯრედი B7” და “გასწორეთ ტექსტის ყუთი, რომელიც B7‑ის თავზე დგას”.

2. ორივე მოდელი თვითგანმარტებითა report‑ისათვის — Filename და Worksheet დაბრუნდება ყოველ ელემენტზე, ამიტომ ბევრი სამუშაო წიგნის სკანირება შეიძლება შეერთდეს ერთ აუდიტის ცხრილში post‑processing‑ის გარეშე.

3. დაწყებამდე საჭირო ორი რამ

1. რეგისტრირდით უფასო ანგარიშზე Aspose Cloud Dashboard და შექმენით აპლიკაცია, რათა მიიღოთ Client ID და Client Secret (SDK-ები ავტომატურად გაცვლიან ისინი JWT-ით — არ გჭირდებათ ავტორიზაციის ჰედერების შექმნა).
2. დააყენეთ 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 (რეგიონის/ლოკალის პარამეტრი) — იგივე არჩევითი პარამეტრები, რომლებიც ნახავთ ღრუბლოვანი-საცავის ვარიანტებში, როგორც storageName. გაითვალისწინეთ, რომ .NET SDK დატოვებს regoin მართლწერას; Python SDK კი იგივე ორი პარამეტრი ეწოდება password და region.

③ Python / Java

Python SDK იგივე endpoint ოჯახს გადაფარავს, მოთხოვნის მოდელის ველები 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()));
    }
}

თუ თქვენ იყოთ raw 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"));

რატომ სამი endpoint-ის ნაცვლად ერთი? რადგან გზამიკით გადმოცემულია შუალედი. მთლიანი სამუშაო წიგნის endpoint იღებს სახელს და მოთხოვნას; worksheet-ის endpoint იღებს worksheet-ის სეგმენტს; range-ის endpoint იღებს worksheet-ს და range-ის სეგმენტს. ეს არის სუფთა, ქეშირებადი REST ფორმა — და ნიშნავს, რომ “ჩემი ძიების შემოკლება” პარამეტრები (worksheet, cellArea) არსებობს მხოლოდ ლოკალური ფაილის endpoint-ზე, რაც მნიშვნელოვანია, როდესაც გადმავთვლით გამოძახებას ერთი შუალედიდან მეორეზე.

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 ორი ნაწილად იყოფა, და ეს გაყოფა მიზნობრივია:

① ლოკალურ სამუშაო წიგნაკში ჩანაცვლება, შედეგის ნაკადის დაბრუნება

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-ის წაკითხვით, ძიება ყოველ ცხრილში სამ განსხვავებული ელემენტის ტიპს გადის:

და აქ არიან ქცევები, რომლებიც ღირს იცოდეთ წინ თქვენ მათი გარშემო დიზაინის შექმნისას:

მხოლოდ სტრინგის უჯრედები იძებნება. სკანირება ფილტრებს CellValueType.IsString-ზე. უჯრედი, რომელიც შეიცავს რიცხვს, თარიღს ან ლოგიკურ მნიშვნელობას, გამოტოვებულია — ამიტომ 2025-ის ძიება არ დაემატება თარიღის ფორმატში არსებულ უჯრედს, რომლის სერიული მნიშვნელობა შემთხვევით 2025 არის. უჯრედები, რომლებშიც ფორმულები ტექსტად ივლება, დაემატება, რადგან მათი მნიშვნელობის ტიპი სტრინგია.

რეგისტრაციის მგრძნობიარობა არის ერთადერთი დამთხვევის არჩევანი. ignoringCase გადართავს InvariantCultureIgnoreCase და InvariantCulture შედარებას — მეტი არაფერია. არ არსებობს მთელი-სიტყვის, რეგექსის, ან “match entire cell value” რეჟიმი, მიუხედავად იმისა, რაც გენერირებული API დოკუმენტაციამ შეიძლება შემოთავაზოს. თუ თქვენ გჭირდებათ ეს სემანტიკა, გადმოწერეთ all-textitems ინვენტარი და გაფილტვრთეთ იგი თქვენს მხარეს.

Replace არის მარტივი, რეგისტრისგან დამოკიდებული, ლიტერალური ჩანაცვლება. Search-ის ignoringCase ალამს არ აქვს თანასწორი Replace-ზე — ჩანაცვლების გზას არ აქვს რეგისტრისგან დამოუკიდებელი პარამეტრი. და ორი კოდის გზა შიდა დონეზე განსხვავდება: მთლიანი სამუშაო ფურცლის ჩანაცვლება გადაგზავნილია ძრავის Worksheet.Replace(...), ხოლო დიაპაზონზე დაფუძნებული ჩანაცვლება იტერირებს დიაპაზონს და გადაწერს თითოეულ სტრინგის უჯრედს cell.StringValue.Replace(...). პრაქტიკული შედეგია: დიაპაზონზე დაფუძნებული ჩანაცვლება ეხება მხოლოდ სტრინგის უჯრედებს, და იგი ლიტერალურია, არა შაბლონზე დაფუძნებული.

ჰიპერლინკის დამთხვევები ანგარიშში აჩვენებენ მისამართს, არა სათაურს. როდესაც ძიება ემთხვევა ჰიპერლინკის ჩვენების ტექსტს, დაბრუნებული Content მაინც არის hyperlink.Address. თუ თქვენ ქმნით “მოვიძიეთ აქ” ანგარიშს, დაელოდეთ URL — სათაური არ გამოჩნდება.

გათიშული ბმულის შემოწმება მხოლოდ http:// და https://-ზე ეცდება. mailto: ბმულები, ადგილობრივი ფაილის გზები და შიდა #Sheet1!A1 ანკრები სრულად გამოტოვებულია — ისინი არასოდეს ტესტირებულია, ამიტომ ისინი არასოდეს გამოჩნდებიან შედეგებში. ის ასევე სკანირებს ჰიპერბმულებს, რომლებიც მიმაგრებულია ფორმებზე და უჯრედებზე, რაც ზუსტად იქაა, სადაც მყარი ბმულები უჯრედში დაიმალება. დაიმახსოვრეთ, რომ გატეხილი ბმულის Position შექმნილია ნედლეული hyperlink.Area-დან (არა უფრო მეგობრულ Area.ToRangName()-ის, რომელსაც საძიებო წერტილები იყენებენ), ამიტომ არ უნდა დაითვალოთ, რომ ორი ოჯახი პოზიციებს იდენტურად აჩვენებს — გაანალიზეთ Worksheet + LinkAddress წყვილი, თუ სტაბილური გასაღები გჭირდებათ.

“გათიშული” ნიშნავს “მიუღებლურ”, არა “არასწორ სტატუს კოდს”. შემოწმება თითოეულ ბმულზე HTTP HEAD მოთხოვნის შესრულებას ახდენს და ნებისმიერი პასუხს — მათ შორის 404 ან 500 — ხელმისაწვდომად ითვლის; ბმული მხოლოდ მაშინ ითვალისწინება გათიშული, როდესაც მოთხოვნა გადატარდება (DNS-ის შეცდომა, კავშირის უარყოფა, TLS-ის შეცდომა, დროის გასვლა). ამიტომ გამონატანისგან უნდა ითვლოს “ბმულები, რომლებსაც ვერ დაეკავშირეთ”. თუ თქვენ რეალურად გჭირდებათ “ბმულები, რომლებსაც 2xx არ აბრუნებენ”, თქვენ უნდა გადამოწმოთ დაბრუნებული LinkAddress მნიშვნელობები თვითონ.

cellArea მიღებულია, მაგრამ არ გამოიყენება broken-link საბოლოო წერტილებზე. BrokenLinks განხორციელება ფილტრებს მხოლოდ სამუშაო ფურცლის სახელით; cell-area არგუმენტი გადაეცემა, მაგრამ არასდროს გამოიყენება. პრაქტიკულად ეს ნიშნავს, რომ .../ranges/A1:F40/search/broken-links ამჟამად იმოქმედებს იგივე როგორც /worksheet/search/broken-links იმავე სამუშაო ფურცლისთვის — ბმულები გადამოწმდება მთელი ფურცლის მიხედვით. განსაზღვრეთ თქვენი reports შესაბამისად (ან გაფილტვრა დაბრუნებული სია პოზიციით) ნაცვლად toho, რომ მიიჩნიოთ, რომ დიაპაზონი შემოწმებას შუჭდება.

ამებიდან არცერთი არ არის ბლოკერი — ისინი განსხვავებაა ფუნქციისა, რომელიც “მუშაობს დემოში”, და იმაზე, რომელიც პროგნოზირებად მოქმედებს წარმოებაში.

10. შეცდომის დამუშავება & ოპერაციული შენიშვნები

კონტროლერის დოკუმენტირებული კონტრაქტი

შიდა დონეზე, ყველა მოქმედება თავისი მუშაობა გადატავს დამხმარე (WorkbookElementOperation, UpdateWorkbookElementOperation, UpdateWorkbookElementOperationAndSave)-ში, რომელიც იჭერს შეცდომებს და თავიდან აცილებს მათ როგორც CellsApiException ოპერაციის სახელით პრეფიქსირებული — მაგალითად SearchContentInRemoteRange Error Message: .... იმ ოპერაციის სახელი არის სტრინგი, რომელსაც თქვენ ნახავთ თქვენს ლოგებში:

SDK-ების მიერ გამოყოფილი არასავალდებულო პარამეტრები

დოკუმენტირებულ პარამეტრებს გარდა, ღრუბლოვანი-საცავის მოთხოვნის მოდელებს ყველა ერთნაირი სამი არასავალდებულო პარამეტრი აქვთ:

• password — პაროლით დაცული სამუშაო წიგნის გახსნა (ძიება არ ითხოვს წერილის წვდომას, ამიტომ წაკითხვადი ფაილები კარგად მუშაობენ);
• storageName — მიზნად მიიღეთ მომხმარებლის/მიერთებული ღრუბლოვანი საცავი ნაგულისხმევის ნაცვლად (Python: storage_name);
• regoin — რეგიონ/ლოკალი, რომელიც გამოიყენება სამუშაო წიგნის ინტერპრეტაციისას (Python-ში ეს არის region).

ავთენტიკაცია

ყველა SDK ავტომატურად აუტენთიფიკაციას ახდენს OAuth 2.0 client_credentials და JWT-ით; როდესაც იყენებთ raw cURL-ს, პირველ რიგში გამოიძახეთ /connect/token (იხილეთ §4, ①).

11. რატომ Aspose.Cells Cloud ძიება & ჩანაცვლებისთვის?

• ✅ შესრულებული ადგილობრივი დამოკიდებულებების გარეშე — Office/Excel, COM, სკრიპტინგის ჰოსტის გარეშე. გამოძახება ნებისმიერი ენისგან, ნებისმიერი პლატფორმისგან (Linux, კონტეინერები, სერვერლესი);
• ✅ ტექსტის ძებნისგან ღრმა — უჯრედები, ფორმები და ჰიპერლინკები ყველა პირველადი შესატყვისი მიზანია, რაც ზუსტად არის იმ ადგილას, სადაც რეალური ცხრილები თავიანთი შინაარსი ინახავენ;
• ✅ მოცულობით ოპერაციები — სამუშაო წიგნი / სამუშაო ფურცელი / დიაპაზონი, ასე რომ შეგიძლიათ გასწოროთ ერთი რეგიონალი ერთი ფურცლზე 50 MB ფაილის გადაწერის გარეშე;
• ✅ ღრუბლზე-ნატიური ან stateless — ფაილები, რომლებიც უკვე შენახულია, არასოდეს დატოვებენ მას; ლოკალური ატვირთვის ოპერაციები არაფერს შენარჩუნებენ;
• ✅ მაღალი სიზუსტის გადაწერა — ჩანაცვლებები გადატარდება Aspose.Cells ძრავით და თავიდან სერიალიზდება, ამიტომ ფორმულები, სტილები, დიაგრამები და ფორმატირება გადადის ციკლიდან გადარჩენენ;
• ✅ ერთ ფორმა ყველა SDK-ში — cURL, .NET, Python და Java ზედაპირები 1:1 ასახავენ, ამიტომ ნიმუში, რომელიც ასქრიბთ ერთი ენისგან, მუშაობს სხვაებში.

დაიწყეთ ახლავე: რეგისტრირდით Aspose Cloud Dashboard-ზე, შექმენით Application, ჩასვით თქვენი ავტორიზაციის დეტალები რომელიმე snippet-ზე ზემოთ, და მიუთითეთ იგი თქვენს ერთ-ერთი workbook-ზე — რამდენიმე წუთში მიიღებთ მუშაობას შემცველობის აუდიტს.

მოგეწონათ ეს? დაამატეთ ვარსკვლავი, ჩანიშვნა ან გააზიარეთ — და კომენტარებში გვაცნობეთ, რა მიზნებით იყენებთ სამუშაო წიგნის ძიება და შეცვლა.