尋找、修復、驗證：Aspose.Cells Cloud 搜尋、取代與斷鏈接 API 完整指南（.NET / Python / Java / cURL）

“我們的 400 本預算工作簿中，哪一本仍然顯示 Old Vendor Ltd？” “將此範本中的每個 {{COMPANY}} 佔位符全部取代。” “我們的任何報告仍然連結到去年已停用的那個域名嗎？” — 三個截然不同的問題，共同的答案：一個在雲端讀寫試算表的 REST 呼叫，且不需要在任何地方安裝 Excel。

試算表 內容 問題幾乎出現在每個資料密集的程式碼庫中：

  • Content audit — 找出每個儲存格、圖形或超連結，這些項目提及已棄用的產品名稱、舊的辦公地址，或過時的法律實體；
  • Template rendering — 在將活頁簿發送給客戶之前，填入跨工作表的 {{PLACEHOLDER}} 代碼；
  • Link rot — 檢查活頁簿中嵌入的 URL 是否仍能解析，在合規或歸檔工作批准之前；
  • Bulk correction — 修正跨數十張工作表的拼寫錯誤或欄位值錯字，或僅針對單張工作表的特定區域進行修正；

傳統的選項——在您自己的機器上運行的腳本庫、Excel 宏或 Windows 伺服器上的 COM 元件——都意味著您需要自行託管和擴展試算表邏輯。Aspose.Cells Cloud 將其轉變為純粹的 REST：傳送檔案（或僅檔名），即可取得匹配結果——或修正後的檔案——返回。

本文介紹 Aspose.Cells Cloud 微服務中核心 SearchController 所公開的 API（來源：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 — even the read-only searches — because a search is modelled as 對資源提交的操作, not a cacheable GET.

兩種操作模式，以及它們的重要性

控制器為每個操作添加裝飾，而裝飾器會精確告訴您檔案的來源：

  • [OnlineOperation] — stateless. 您將工作簿上傳至請求主體（multipart），伺服器在記憶體中處理，且不會將任何資料持久化到雲端儲存。非常適合「只告訴我此檔案的內容」以及一次性範本化的情況。
  • [CloudFileOperation] — storage-backed. 伺服器從雲端儲存中取得 {name}（可選擇在 folder= 下），完成工作後——對於取代操作——直接將結果寫回。資料不會傳送到您的機器。

那唯一的區別，加上 {worksheet} / {cellArea} 路由段，就是完整的思維模型。本文的其餘部分僅是細節。

2. 您實際上會解析的回應模型

兩個搜尋系列都會返回一個小型、扁平、易於綁定的形狀。Search 返回 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. 兩個模型皆具自我描述性以供報告 — Filename 與 Worksheet 會在每個項目中返回，因而可將多個活頁簿的掃描結果串接成一個稽核表，無需後續處理。

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 也同樣適用（見下文）。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"

將其限制在單一工作表，或單一工作表的某個區域，使用另外兩個查詢參數：

# 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 采用相同的结构，使用通过 setter 构建的 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"));

為什麼要使用三個端點而不是一個？ 因為路由承載了範圍。整個工作簿端點接受名稱和查詢；工作表端點接受工作表段落；範圍端點接受工作表 以及 範圍段落。這是一個乾淨且可快取的 REST 形態——而且這表示「縮小搜尋」參數（worksheet、cellArea）僅在本機檔案端點上存在，這在將呼叫從一個範圍移植到另一個範圍時值得記住。

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 會為檔案中每個儲存格字串、超連結說明以及圖形文字填入內容。這是「在整個活頁簿中搜尋」的原始作業。

7. 情境 D：取代 — 以及兩個截然不同的結果

Replace 是 API 分成兩部分的地方，且此分割是刻意的：

本機上傳 → 下載已校正的檔案 雲端檔案 → 保存回儲存空間
Endpoint PUT /v4.0/cells/replace/content PUT /v4.0/cells/{name}/replace/content
Returns 一個 檔案串流（與您上傳的格式相同） CellsCloudResponse { "Code": 200, "Status": "OK" }
Storage touched 無 原始檔案已 覆寫

① 在本機工作簿中取代，將結果串流回傳

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

以下是值得在您設計之前了解的行為 before：

僅搜尋字串儲存格。 掃描會以 CellValueType.IsString 為過濾條件。持有 數字、日期 或 布林值 的儲存格會被跳過 — 因此搜尋 2025 不會匹配序列值恰好為 2025 的日期格式儲存格。公式計算結果為文字的儲存格 會 被匹配，因為它們的值類型是字串。

大小寫敏感性是唯一的匹配選項。 ignoringCase 在 InvariantCultureIgnoreCase 和 InvariantCulture 比較之間切換——僅此而已。儘管生成的 API 文檔可能暗示，實際上沒有 whole-word、regex，或 “match entire cell value” 模式。如果需要這些語義，請自行提取 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 組合。

「Broken」表示「無法連線」，而非「錯誤的狀態碼」。 檢查會對每個連結發送 HTTP HEAD 請求，並將 任何 回應（包括 404 或 500）視為可存取；只有當請求 拋出（DNS 失敗、連線被拒絕、TLS 錯誤、逾時）時才會將連結標記為斷開。 因此請將輸出視為 「無法聯繫的連結」。 如果您實際需要的是「不返回 2xx 的連結」，則需要自行重新檢查返回的 LinkAddress 值。

cellArea 已被接受，但未在 broken-link 端點上套用。 BrokenLinks 實作僅依工作表名稱過濾；傳入的 cell-area 參數卻從未使用。實際上，這表示 .../ranges/A1:F40/search/broken-links 目前在相同工作表下的行為與 /worksheet/search/broken-links 相同 — 連結會在整個工作表範圍內驗證。請相應地調整您的 報告 範圍（或依位置過濾返回的列表），而不要假設範圍會縮小檢查範圍。

這些都不是阻礙——它們是「works in the demo」的功能與在生產環境中可預測運作的功能之間的差異。

10. 錯誤處理與操作說明

控制器文件的合約

Status 說明 常見原因
400 錯誤的請求 無效的 URL/參數 — 例如格式錯誤的 cellArea，或缺少 searchText
401 未授權 驗證失敗或未提供有效的憑證
404 未找到 來源檔案在雲端儲存中無法存取
500 伺服器錯誤 服務在取得試算表資料時發生異常

在内部，每个操作都会将其工作包装在一个帮助类（WorkbookElementOperation、UpdateWorkbookElementOperation、UpdateWorkbookElementOperationAndSave）中，该帮助类捕获失败并将其重新抛出为 CellsApiException 并在前缀中包含操作名称 ——例如 SearchContentInRemoteRange Error Message: ...。该操作名称就是您在日志中看到的字符串：

操作名稱 端點族
SearchSpreadsheetContent, SearchContentInRemoteSpreadsheet 本機/遠端搜尋
SearchContentInRemoteWorksheet, SearchContentInRemoteRange 範圍遠端搜尋
ReplaceSpreadsheetContent 本機取代（串流結果）
ReplaceContentInRemoteSpreadsheet, ReplaceContentInRemoteWorksheet, ReplaceContentInRemoteRange 遠端取代（儲存結果）
SearchSpreadsheetBrokenLinks, SearchBrokenLinksInRemoteSpreadsheet, SearchBrokenLinksInRemoteWorksheet, SearchBrokenLinksInRemoteRange 連結驗證

SDK 所公開的可選參數

除了已記錄的參數外，雲端儲存請求模型還包含相同的三個可選設定：

  • password — 開啟受密碼保護的活頁簿（搜尋不需要寫入權限，因此只讀保護的檔案也能正常使用）;
  • storageName — 指定自訂/附加的雲端儲存，而非預設儲存（Python：storage_name）;
  • regoin — 解析活頁簿時使用的區域/語系設定（Python 中寫作 region）。

驗證

所有 SDK 都會自動使用 OAuth 2.0 client_credentials 和 JWT 進行驗證；在使用原始 cURL 時，請先呼叫一次 /connect/token（見第 4 節，①）。

11. 為什麼 Aspose.Cells Cloud 用於搜尋與取代？

  • ✅ 零本機依賴 — 無 Office/Excel，無 COM，無腳本主機。可從任何語言、任何平台（Linux、容器、無伺服器）呼叫；
  • ✅ 比文字搜尋更深入 — 單元格、形狀和超連結皆為第一級匹配目標，正是實際試算表保存內容的地方；
  • ✅ 範圍操作 — 工作簿/工作表/範圍，讓您能在不重新寫入 50 MB 檔案的情況下修正單一工作表的某個區域；
  • ✅ 雲原生或無狀態 — 已在儲存中的檔案永不離開；本機上傳操作不會保留任何資料；
  • ✅ 高保真重寫 — 取代透過 Aspose.Cells 引擎套用並重新序列化，因而公式、樣式、圖表與格式在往返過程中得以保留；
  • ✅ 跨 SDK 的單一形態 — cURL、.NET、Python 與 Java 介面 1:1 對映，讓您從一種語言複製的模式可直接在其他語言使用。

立即開始：在 Aspose Cloud Dashboard 註冊，建立一個應用程式，將您的憑證放入上述任意程式碼片段，並指向您自己的工作簿 — 您將在幾分鐘內擁有可運作的內容稽核。

覺得這很有用嗎？給它加星標、加入書籤或分享——並在評論中告訴我們您使用工作簿搜尋與取代的目的。