ค้นหา, แก้ไข, ตรวจสอบ: คู่มือฉบับสมบูรณ์สำหรับ Aspose.Cells Cloud Search, Replace & Broken-Link API (.NET / Python / Java / cURL)

“หนังสือทำงบประมาณ 400 ฉบับของเราหนังสือใดยังแสดงว่าเป็น Old Vendor Ltd?” “แทนที่ตัวแปรตำแหน่ง {{COMPANY}} ทุกตัวในเทมเพลตนี้.” “รายงานใดของเรายังลิงก์ไปยังโดเมนที่เรายกเลิกใช้เมื่อปีที่แล้วหรือไม่?” — คำถามที่แตกต่างกันสามข้อ แต่มีคำตอบเดียว: การเรียก REST ที่อ่านและเขียนสเปรดชีตในคลาวด์ โดยไม่ต้องติดตั้ง Excel ใด ๆ

ปัญหา เนื้อหา ของ Spreadsheet ปรากฏในโค้ดเบสที่มีข้อมูลจำนวนมากเกือบทุกกรณี:

• การตรวจสอบเนื้อหา — ค้นหาเซลล์, รูปร่าง หรือไฮเปอร์ลิงก์ทุกรายการที่อ้างถึงชื่อผลิตภัณฑ์ที่เลิกใช้, ที่อยู่สำนักงานเก่า, หรือหน่วยกฎหมายที่ล้าสมัย;
• การเรนเดอร์เทมเพลต — เติมโทเคน {{PLACEHOLDER}} ทั่วแผ่นงานก่อนส่งสมุดงานให้ลูกค้า;
• ลิงก์เสีย — ตรวจสอบว่า URL ที่ฝังอยู่ในสมุดงานยังสามารถเข้าถึงได้, ก่อนที่งานตรวจสอบความสอดคล้องหรือการเก็บถาวรจะอนุมัติ;
• การแก้ไขเป็นกลุ่ม — แก้ไขข้อผิดพลาดการพิมพ์หรือค่าคอลัมน์ที่สะกดผิดทั่วหลายสิบแผ่นงาน, หรือจำกัดเฉพาะหนึ่งพื้นที่ของแผ่นงานเดียว.

ตัวเลือกแบบดั้งเดิม — ไลบรารีสคริปต์ที่ทำงานบนเครื่องของคุณ, แมโคร Excel, หรือคอมโพเนนต์ COM บนเซิร์ฟเวอร์ Windows — ทั้งหมดหมายความว่าคุณเป็นผู้โฮสต์และขยายตรรกะสเปรดชีต Aspose.Cells Cloud ทำให้เป็น REST ธรรมดา: ส่งไฟล์ (หรือเพียงชื่อไฟล์), รับผลลัพธ์ — หรือไฟล์ที่แก้ไขแล้ว — กลับมา

โพสต์นี้จะอธิบาย API ที่เปิดให้ใช้โดย SearchController หลักใน Aspose.Cells Cloud microservice (แหล่งที่มา: src/Aspose.Cells.Cloud.MicroService/Controllers/SearchController.cs), พร้อมตัวอย่างที่สามารถรันได้ใน cURL และ C# (.NET), รวมถึงหมายเหตุสำหรับผู้ใช้ Python และ Java.

1. SearchController สามารถทำอะไรได้บ้าง?

SearchController ครอบคลุม สามกลุ่มความสามารถ, แต่ละอย่างมีให้บริการในหลาย ขอบเขต:

และแต่ละครอบครัวจะเปิดเผยที่ สี่ขอบเขต, ซึ่งเป็นจุดที่รายการ endpoint ยาวขึ้น:

เพิ่มสอง endpoint โบนัสที่ดัมพ์ ทุกรายการข้อความ ใน workbook — ดูที่ §4:

บันทึกการใช้งาน: เส้นทางจะมีคำนำหน้าเป็น v{version:apiVersion}/cells และคอนโทรลเลอร์นี้คือ [ApiVersion("4.0")] ดังนั้นการเรียกใช้งานจริงจะมีลักษณะเช่น https://api.aspose.cloud/v4.0/cells/.... ทุกอย่างในคอนโทรลเลอร์นี้เป็น PUT — แม้กระทั่งการค้นหาแบบอ่านอย่างเดียว — เนื่องจากการค้นหาถูกจำลองเป็น การดำเนินการที่ส่งไปยังทรัพยากร ไม่ใช่ GET ที่สามารถแคชได้

สองโหมดการทำงานและเหตุผลที่สำคัญ

คอนโทรลเลอร์ทำการตกแต่งแต่ละแอคชัน และตัวตกแต่งบอกให้คุณทราบอย่างชัดเจนว่าไฟล์มาจากที่ไหน:

• [OnlineOperation] — stateless. คุณอัปโหลดเวิร์กบุ๊กในส่วนของคำขอ (multipart) เซิร์ฟเวอร์ประมวลผลในหน่วยความจำและไม่มีการบันทึกใด ๆ ลงในคลาวด์สตอเรจ เหมาะอย่างยิ่งสำหรับ “just tell me what’s in this file” และการเทมเพลตแบบครั้งเดียว
• [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"
    }
  ]
}

การค้นหา Broken-link ส่งคืน 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. โมเดลทั้งสองเป็นแบบอธิบายตนเองสำหรับการรายงาน — Filename และ Worksheet จะถูกส่งกลับในแต่ละรายการ ดังนั้นการสแกนผ่านหลายเวิร์กบุ๊กสามารถรวมเป็นตารางตรวจสอบเดียวได้โดยไม่ต้องประมวลผลต่อ.

3. สองสิ่งที่คุณต้องการก่อนเริ่ม

1. ลงทะเบียนบัญชีฟรีบน Aspose Cloud Dashboard และสร้างแอปพลิเคชันเพื่อรับ Client ID และ Client Secret (SDK จะทำการแลกเปลี่ยนเหล่านี้เป็น JWT โดยอัตโนมัติ — ไม่จำเป็นต้องสร้างส่วนหัวการตรวจสอบด้วยตนเอง)
2. ติดตั้ง SDK สำหรับภาษาที่คุณเลือก:

<!-- .NET -->
<PackageReference Include="Aspense.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 ก็ทำงานได้เช่นกัน (ดูด้านล่าง) ครอบครัว search/replace/broken-link ยังสามารถเข้าถึงได้ผ่านโมเดลคำขอ 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"

จำกัดให้เป็นแผ่นเดียว หรือเป็นพื้นที่หนึ่งของแผ่นเดียว ด้วยพารามิเตอร์ query เพิ่มอีกสองตัว:

# 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 ห่อหุ้มชุด endpoint เดียวกัน โดยฟิลด์ของ request-model จะแมปกับฟิลด์ของ 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)

SDK ของ Java มีรูปแบบเดียวกันโดยใช้วัตถุ 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"));

ทำไมต้องมีสาม endpoint แทนที่จะเป็นหนึ่ง? เพราะเส้นทางบรรจุขอบเขต. endpoint ทั้งหมดของ workbook รับชื่อและ query; endpoint ของ worksheet รับส่วนของ worksheet; endpoint ของ range รับ worksheet และ ส่วนของ range. มันเป็นรูปแบบ REST ที่สะอาดและสามารถแคชได้ — และหมายความว่าพารามิเตอร์ “narrow my search” (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 ถูกเติมค่าให้กับสตริงของเซลล์ทุกเซลล์, คำบรรยายของไฮเปอร์ลิงก์และข้อความรูปทรงในไฟล์. นี่คือ primitive ที่ “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 — ไม่มีอะไรเพิ่มเติม. ไม่มีโหมด whole-word, regex, หรือ “match entire cell value” แม้ว่าข้อกำหนด API ที่สร้างขึ้นอาจบ่งบอก. หากคุณต้องการความหมายเหล่านั้น ให้ดึง inventory all-textitems แล้วกรองด้วยตนเอง.

Replace คือการแทนที่แบบธรรมดา, แยกแยะตัวพิมพ์ใหญ่-เล็ก, การแทนที่โดยตรง. Search’s ignoringCase flag มี ไม่มีเทียบเท่าใน Replace — เส้นทางการแทนที่ไม่มีพารามิเตอร์ที่ไม่แยกแยะตัวพิมพ์ใหญ่-เล็กเลย. และเส้นทางโค้ดสองเส้นนี้แตกต่างกันภายใน: การแทนที่ทั้งแผ่นงานมอบหมายให้กับ Worksheet.Replace(...) ของเอนจิน, ในขณะที่การแทนที่แบบช่วงทำการวนซ้ำช่วงและเขียนทับแต่ละเซลล์ข้อความด้วย cell.StringValue.Replace(...). ผลที่ตามมาจากการปฏิบัติ: การแทนที่แบบช่วงจะกระทบเฉพาะเซลล์ข้อความเท่านั้น, และเป็นการแทนที่โดยตรง, ไม่ใช่แบบอิงรูปแบบ.

การจับคู่ไฮเปอร์ลิงก์รายงานที่อยู่ ไม่ใช่คำบรรยาย เมื่อการค้นหาตรงกับ ข้อความที่แสดง ของไฮเปอร์ลิงก์, ค่าที่คืนกลับ Content ยังเป็น hyperlink.Address. หากคุณกำลังสร้างรายงาน “found it here”, คาดว่าจะได้ URL — คำบรรยายจะไม่ถูกแสดงกลับ.

การตรวจสอบลิงก์เสียจะตรวจสอบเฉพาะ http:// และ https:// เท่านั้น mailto: ลิงก์, เส้นทางไฟล์ในเครื่อง, และ anchor ภายใน #Sheet1!A1 จะถูกข้ามทั้งหมด — พวกมันจะไม่ถูกทดสอบเลย, ดังนั้นจะไม่ปรากฏในผลลัพธ์. มันยังสแกนไฮเปอร์ลิงก์ที่แนบกับ shapes รวมถึงเซลล์, ซึ่งเป็นที่ที่ลิงก์เสียมักซ่อนอยู่. โปรดทราบว่า Position ของลิงก์เสียถูกสร้างจาก hyperlink.Area ดิบ (ไม่ใช่ Area.ToRangName() ที่เป็นมิตรกว่าและใช้โดย endpoint การค้นหา), ดังนั้นอย่าสมมติว่าทั้งสองกลุ่มจะแสดงตำแหน่งอย่างเหมือนกัน — ให้พาร์สคู่ Worksheet + LinkAddress หากคุณต้องการคีย์ที่คงที่.

“Broken” หมายถึง “ไม่สามารถเข้าถึงได้”, ไม่ใช่ “รหัสสถานะผิดพลาด”. การตรวจสอบจะส่งคำขอ HTTP HEAD สำหรับแต่ละลิงก์และถือว่าการตอบสนองใดๆ — รวมถึง 404 หรือ 500 — เป็นที่เข้าถึงได้; จะทำเครื่องหมายลิงก์ว่าเสียหายเฉพาะเมื่อคำขอ throws (การล้มเหลวของ DNS, การเชื่อมต่อถูกปฏิเสธ, ข้อผิดพลาด TLS, หมดเวลา). ดังนั้นให้ถือผลลัพธ์ว่าเป็น “ลิงก์ที่ไม่สามารถติดต่อได้”. หากสิ่งที่คุณต้องการจริงๆ คือ “ลิงก์ที่ไม่คืนค่า 2xx”, คุณจะต้องตรวจสอบค่า LinkAddress ที่ส่งกลับด้วยตนเอง.

cellArea ถูกยอมรับแต่ไม่ได้ใช้ในจุดสิ้นสุดของ broken-link. การทำงานของ BrokenLinks จะกรองโดยใช้ชื่อ worksheet เท่านั้น; อาร์กิวเมนต์ cell-area ถูกส่งเข้าไปแต่ไม่เคยใช้. ในการปฏิบัติจริงหมายความว่า .../ranges/A1:F40/search/broken-links ปัจจุบันทำงานเหมือนกับ /worksheet/search/broken-links สำหรับ worksheet เดียวกัน — ลิงก์จะถูกตรวจสอบทั่วทั้งแผ่นงาน. กำหนดขอบเขตของ รายงาน ของคุณให้สอดคล้อง (หรือกรองรายการที่คืนค่าตามตำแหน่ง) แทนที่จะสมมติว่าช่วงจะทำให้การตรวจสอบแคบลง.

ไม่มีข้อใดเป็นอุปสรรค — พวกมันคือความแตกต่างระหว่างฟีเจอร์ที่ “ทำงานในเดโม” กับฟีเจอร์ที่ทำงานอย่างคาดการณ์ได้ในสภาพการผลิต

10. การจัดการข้อผิดพลาดและบันทึกการดำเนินงาน

สัญญาที่คอนโทรลเลอร์บันทึก

ภายใน, ทุกการกระทำจะห่อหุ้มงานของมันในตัวช่วย (WorkbookElementOperation, UpdateWorkbookElementOperation, UpdateWorkbookElementOperationAndSave) ที่จับข้อผิดพลาดและโยนใหม่เป็น CellsApiException ที่มีคำนำหน้าด้วยชื่อการดำเนินการ — ตัวอย่างเช่น SearchContentInRemoteRange Error Message: .... ชื่อการดำเนินการนั้นคือสตริงที่คุณจะเห็นในบันทึกของคุณ:

พารามิเตอร์ทางเลือกที่ SDKs เปิดเผย

นอกเหนือจากพารามิเตอร์ที่ระบุในเอกสาร โมเดลคำขอ 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, containers, serverless);
• ✅ Deeper than text search — เซลล์, shapes และ hyperlinks ทั้งหมดเป็นเป้าหมายการจับคู่ระดับแรก, ซึ่งเป็นที่ที่สเปรดชีตจริงเก็บเนื้อหา;
• ✅ Scoped operations — workbook / worksheet / range, ดังนั้นคุณสามารถแก้ไขส่วนหนึ่งของแผ่นงานหนึ่งได้โดยไม่ต้องเขียนไฟล์ขนาด 50 MB ใหม่;
• ✅ Cloud-native or stateless — ไฟล์ที่อยู่ในที่เก็บแล้วจะไม่ออกจากที่เก็บ; การอัปโหลดแบบโลคัลไม่ทำให้ข้อมูลใด ๆ คงอยู่เลย;
• ✅ High-fidelity rewriting — การแทนที่จะถูกนำไปใช้ผ่านเอนจิน Aspose.Cells และทำการซีเรียลไลซ์ใหม่, ดังนั้นสูตร, สไตล์, แผนภูมิและการจัดรูปแบบจะคงอยู่ตลอดการเดินทางกลับ;
• ✅ One shape across SDKs — ส่วนต่อประสานของ cURL, .NET, Python และ Java จะแมป 1:1, ดังนั้นรูปแบบที่คุณคัดลอกจากภาษาหนึ่งจะทำงานในภาษาที่เหลือ.

เริ่มต้นใช้งานทันที: ลงทะเบียนที่ Aspose Cloud Dashboard, สร้างแอปพลิเคชัน, ใส่ข้อมูลประจำตัวของคุณลงในสคริปต์ใดก็ได้ข้างบน, และชี้ไปยังหนึ่งในเวิร์กบุ๊กของคุณเอง — คุณจะมีการตรวจสอบเนื้อหาใช้งานได้ในไม่กี่นาที.

พบว่ามีประโยชน์? กดดาว, เพิ่มเป็นบุ๊กมาร์ก หรือแชร์ — และบอกเราผ่านความคิดเห็นว่าคุณใช้การค้นหาและแทนที่ในเวิร์กบุ๊กเพื่ออะไร.