Encontre, Corrija, Valide: Um Guia Completo para a API de Pesquisa, Substituição e Links Quebrados do Aspose.Cells Cloud (.NET / Python / Java / cURL)
“Qual dos nossos 400 livros‑orçamento ainda diz Old Vendor Ltd?” “Substitua cada placeholder
{{COMPANY}}neste modelo.” “Algum dos nossos relatórios ainda vincula ao domínio que descontinuamos no ano passado?” — três perguntas muito diferentes, uma resposta em comum: uma chamada REST que lê e reescreve planilhas na nuvem, sem que o Excel esteja instalado em nenhum lugar.
Problemas de conteúdo de planilha aparecem em quase todas as bases de código intensivas em dados:
- Auditoria de conteúdo — encontrando cada célula, forma ou hyperlink que menciona um nome de produto descontinuado, um endereço antigo de escritório ou uma entidade jurídica obsoleta;
- Renderização de modelo — preenchendo tokens
{{PLACEHOLDER}}em todas as planilhas antes de enviar uma pasta de trabalho ao cliente; - Link rot — verificando se os URLs incorporados em uma pasta de trabalho ainda resolvem, antes que um trabalho de conformidade ou arquivamento o aprove;
- Correção em massa — corrigindo um erro de digitação ou um valor de coluna escrito incorretamente em dezenas de planilhas, ou limitado a apenas uma região de uma planilha.
As opções tradicionais — uma biblioteca de scripts executando na sua própria máquina, uma macro do Excel ou um componente COM em um servidor Windows — tudo isso significa que você é quem hospeda e dimensiona a lógica da planilha. Aspose.Cells Cloud transforma isso em um REST simples: envie um arquivo (ou apenas o nome do arquivo), receba correspondências — ou um arquivo corrigido — de volta.
Este post percorre as APIs expostas pelo SearchController central no microserviço Aspose.Cells Cloud (fonte: src/Aspose.Cells.Cloud.MicroService/Controllers/SearchController.cs), com exemplos executáveis em cURL e C# (.NET), além de observações para usuários de Python e Java.
1. O que o SearchController pode fazer?
SearchController cobre três famílias de recursos, cada uma disponível em vários escopos:
| Família | O que faz | Altera a pasta de trabalho? |
|---|---|---|
| Search | Retorna os itens de texto que correspondem a uma consulta — com a planilha e a posição da célula/forma/hiperlink | No |
| Replace | Substitui o texto correspondente e, em seguida, transmite de volta um arquivo corrigido ou o salva no armazenamento em nuvem | Yes |
| Broken links | Valida cada hiperlink http(s) na pasta de trabalho e retorna aqueles que não conseguem ser resolvidos |
No |
E cada família é exposta em quatro escopos, que é onde a lista de endpoints fica longa:
| Escopo | Pesquisar | Substituir | Links quebrados |
|---|---|---|---|
| Arquivo local → processamento online (upload no corpo da requisição) | PUT /v4.0/cells/search/content |
PUT /v4.0/cells/replace/content |
PUT /v4.0/cells/search/broken-links |
| Pasta de trabalho inteira no armazenamento em nuvem | PUT /v4.0/cells/{name}/search/content |
PUT /v4.0/cells/{name}/replace/content |
PUT /v4.0/cells/{name}/search/broken-links |
| Planilha única no armazenamento em nuvem | 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 |
| Intervalo único no armazenamento em nuvem | 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 |
Além de dois endpoints bônus que exportam cada item de texto em uma pasta de trabalho — veja §4:
| Objetivo | Endpoint |
|---|---|
| Todos os itens de texto em um arquivo na nuvem | PUT /v4.0/cells/{name}/search/content/all-textitems |
| Todos os itens de texto em um upload local | PUT /v4.0/cells/search/content/all-textitems |
Nota de implementação: as rotas são prefixadas com
v{version:apiVersion}/cellse este controlador é[ApiVersion("4.0")], portanto as chamadas ao vivo se parecem comhttps://api.aspose.cloud/v4.0/cells/.... Tudo neste controlador é umPUT— mesmo as buscas somente de leitura — porque uma busca é modelada como uma operação submetida a um recurso, não umGETcacheável.
Os dois modos de operação e por que eles importam
O controlador decora cada ação, e o decorador informa exatamente de onde o arquivo vem:
[OnlineOperation]— sem estado. Você envia a planilha no corpo da solicitação (multipart), o servidor a processa na memória e nada é persistido no armazenamento em nuvem. Perfeito para “apenas me diga o que há neste arquivo” e para modelagem única.[CloudFileOperation]— com suporte a armazenamento. O servidor recupera{name}do armazenamento em nuvem (opcionalmente sobfolder=), realiza o trabalho e — para as operações de substituição — grava o resultado de volta diretamente. Nada viaja para sua máquina.
Essa única distinção, mais os segmentos de rota {worksheet} / {cellArea}, constitui todo o modelo mental. O resto deste post são apenas os detalhes.
2. Os modelos de resposta que você realmente analisará
Ambas as famílias de pesquisa retornam uma forma pequena, plana e fácil de vincular. Search retorna 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"
}
]
}
A pesquisa de links quebrados retorna BrokenLinksResponse:
{
"Code": 200,
"Status": "OK",
"BrokenLinks": [
{
"Filename": "Book1.xlsx",
"Worksheet": "Links",
"Position": "Hyperlink:Sheet1!B4",
"LinkAddress": "https://retired-domain.example.com/report"
}
]
}
Duas coisas valem a pena apontar imediatamente:
-
Positioné uma localização marcada, não apenas um endereço de célula. É prefixado comCell:,Hyperlink:ouShape:, que é como uma única lista plana pode dizer a você que tipo de coisa correspondeu. Essa tag é a diferença entre “corrigir a célula B7” e “corrigir a caixa de texto que está sobre B7”. -
Ambos os modelos são auto‑descritivos para relatórios —
FilenameeWorksheetsão retornados em cada item, de modo que uma varredura em várias pastas de trabalho pode ser concatenada em uma única tabela de auditoria sem pós‑processamento.
3. Duas coisas que você precisa antes de começar
- Registre uma conta gratuita no Aspose Cloud Dashboard e crie um Aplicativo para obter um
Client IDeClient Secret(os SDKs trocam esses valores por um JWT automaticamente — não é necessário criar cabeçalhos de autenticação manualmente). - Instale o SDK para a linguagem de sua escolha:
<!-- .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>
Nenhum SDK necessário? Tudo é REST puro, então o cURL funciona igualmente bem (veja abaixo). A família de busca/substituição/link quebrado também pode ser acessada através de modelos de solicitação tipados do SDK —
SearchSpreadsheetContentRequest,ReplaceContentInRemoteRangeRequeste amigos — que é o que os trechos de código C# abaixo utilizam.
4. Cenário A: Pesquisar um arquivo local online (nada persistido)
Este é PUT /v4.0/cells/search/content — faça upload da pasta de trabalho, receba as correspondências. Sem armazenamento em nuvem, sem limpeza, sem cópia deixada para trás.
① 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"
Restrinja-a a uma única planilha ou a uma região de uma única planilha, usando dois parâmetros de consulta adicionais:
# 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");
Os modelos de solicitação também expõem
password(abrir uma pasta de trabalho protegida) eregoin(configuração de região/idioma) — os mesmos parâmetros opcionais que você verá nas variantes de cloud‑storage comostorageName. Observe que o SDK .NET mantém a grafiaregoin; o SDK Python chama as mesmas duas configurações depassworderegion.
③ Python / Java
O SDK Python encapsula a mesma família de endpoints, com os campos do modelo de solicitação mapeando para os do C# um a um, mas em 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)
O SDK Java segue o mesmo formato com objetos Request construídos via setters:
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()));
}
}
Se você estiver usando REST puro, o cURL acima é o contrato completo — o campo multipart simplesmente precisa conter o nome do arquivo, pois o serviço deriva o nome da pasta de trabalho (e, portanto, seu formato) dele.
5. Cenário B: Pesquisar um arquivo que já está armazenado na nuvem
Quando a pasta de trabalho já está no Aspose Cloud Storage, pule o download completamente — o serviço a lê onde está:
# 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"));
Por que três endpoints em vez de um? Porque a rota carrega o escopo. O endpoint de todo o workbook recebe um nome e uma consulta; o endpoint da planilha recebe um segmento de planilha; o endpoint de intervalo recebe uma planilha e um segmento de intervalo. É uma forma REST limpa e armazenável em cache — e isso significa que os parâmetros “refinar minha pesquisa” (
worksheet,cellArea) existem somente no endpoint de arquivo local, o que vale a pena lembrar ao portar uma chamada de um escopo para outro.
6. Cenário C: Obter todos os itens de texto em uma pasta de trabalho
Às vezes você não tem um termo de pesquisa — você quer o inventário. Os endpoints all-textitems retornam todos os itens de texto na pasta de trabalho, para que você possa comparar duas revisões, criar um glossário de tradução ou alimentar um indexador:
# 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"
A resposta é o mesmo envelope SearchResponse, com Content preenchido para cada string de célula, legenda de hyperlink e texto de forma no arquivo. Isso é o primitivo “grep the whole workbook”.
7. Cenário D: Substituir — e os dois resultados muito diferentes
Replace é onde a API se divide em duas, e a divisão é deliberada:
| Upload local → baixe o arquivo corrigido | Arquivo na nuvem → salvo de volta ao armazenamento | |
|---|---|---|
| Endpoint | PUT /v4.0/cells/replace/content |
PUT /v4.0/cells/{name}/replace/content |
| Returns | Um fluxo de arquivo (mesmo formato que você enviou) | CellsCloudResponse { "Code": 200, "Status": "OK" } |
| Storage touched | Nenhum | O arquivo original é sobrescrito |
① Substituir em uma pasta de trabalho local, transmitir o resultado de volta
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");
Dois parâmetros de escopo também estão disponíveis aqui — sheetname e cellarea — para que você possa renderizar marcadores de posição em uma planilha sem tocar no restante do modelo.
② Substituir em uma pasta de trabalho na nuvem, persistir no local
# 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"));
A substituição no local é destrutiva por design. As variantes em nuvem sobrescrevem
{name}— nenhuma cópia de backup é criada. Para fluxos de trabalho com auditoria intensiva, mantenha uma cópia revisada (por exemplo, faça upload deBook1-2026-09-11.xlsxprimeiro, depois substitua) ou use a variante de upload local e armazene o stream retornado você mesmo.
8. Cenário E: Encontre links quebrados antes que outra pessoa o faça
Verificação de links é o recurso oculto aqui — é o tipo de coisa que é tedioso escrever por conta própria e constrangedor pular. Todos os quatro escopos estão disponíveis; a variante de arquivo local é a verificação de sanidade mais rápida:
# 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}");
}
O resultado é uma lista que você pode usar diretamente: cada entrada indica a planilha, a posição e o LinkAddress problemático.
9. O que realmente é escaneado? (os detalhes de implementação que mudam suas expectativas)
Esta é a parte que separa uma integração funcional de uma surpreendente. Ao ler WorkbookExtension.cs, uma pesquisa percorre três tipos distintos de elementos em cada planilha:
| Tipo de elemento | Fonte | O que corresponde | Position tag |
|---|---|---|---|
| Strings de célula | worksheet.Cells |
O valor de string da célula | Cell:A1 |
| Hyperlinks | worksheet.Hyperlinks |
Tanto o endereço do link e seu texto de exibição | Hyperlink:Sheet1!B4 |
| Shapes | worksheet.Shapes |
shape.Text — caixas de texto, balões, rótulos |
Shape:TextBox 3 |
E aqui estão os comportamentos que vale a pena conhecer antes de projetar em torno deles:
Somente células de string são pesquisadas. A varredura filtra em CellValueType.IsString. Uma célula que contém um número, uma data ou um booleano é ignorada — então uma pesquisa por 2025 não corresponderá a uma célula formatada como data cujo valor serial acontece ser 2025. Células cujas fórmulas avaliam para texto são correspondidas, porque seu tipo de valor é string.
A sensibilidade a maiúsculas/minúsculas é a única opção de correspondência. ignoringCase alterna entre a comparação InvariantCultureIgnoreCase e InvariantCulture — nada mais. Não há modo de palavra inteira, regex ou “correspondência de todo o valor da célula”, apesar do que a documentação da API gerada possa sugerir. Se precisar dessas semânticas, obtenha o inventário all-textitems e filtre‑o do seu lado.
Replace é uma substituição simples, sensível a maiúsculas e minúsculas, literal. A flag ignoringCase da Search não tem equivalente no Replace — o caminho de substituição não tem nenhum parâmetro de insensibilidade a maiúsculas/minúsculas. E os dois caminhos de código diferem internamente: uma substituição de planilha inteira delega ao método Worksheet.Replace(...) do mecanismo, enquanto uma substituição limitada a intervalo itera o intervalo e reescreve cada célula de texto com cell.StringValue.Replace(...). Consequência prática: a substituição limitada a intervalo só afeta células de texto, e é literal, não baseada em padrões.
Correspondências de hyperlink relatam o endereço, não a legenda. Quando uma pesquisa corresponde ao texto de exibição de um hyperlink, o Content retornado ainda é hyperlink.Address. Se você estiver gerando um relatório “found it here”, espere a URL — a legenda não é ecoada de volta.
A verificação de links quebrados verifica apenas http:// e https://. Links mailto: , caminhos de arquivos locais e âncoras internas #Sheet1!A1 são totalmente ignorados — eles nunca são testados, então nunca aparecerão nos resultados. Também verifica hiperlinks anexados a formas assim como às células, que é exatamente onde os links mortos gostam de se esconder. Observe que um Position de link quebrado é construído a partir do hyperlink.Area bruto (não do mais amigável Area.ToRangName() usado pelos endpoints de pesquisa), portanto não presuma que as duas famílias renderizam posições de forma idêntica — analise o par Worksheet + LinkAddress se precisar de uma chave estável.
“Broken” significa “inacessível”, não “código de status errado”. A verificação envia uma solicitação HTTP HEAD por link e trata qualquer resposta — incluindo 404 ou 500 — como acessível; ela só marca um link como quebrado quando a solicitação lança (falha de DNS, conexão recusada, erro TLS, tempo limite). Portanto, trate a saída como “links que não puderam ser contatados”. Se o que você realmente precisa são “links que não retornam 2xx”, você deverá re‑verificar os valores LinkAddress retornados.
cellArea é aceito, mas não é aplicado nos endpoints de link quebrado. A implementação BrokenLinks filtra apenas pelo nome da planilha; o argumento de área de célula é passado, mas nunca usado. Na prática, isso significa que .../ranges/A1:F40/search/broken-links atualmente se comporta da mesma forma que /worksheet/search/broken-links para a mesma planilha — os links são validados em toda a planilha. Defina o escopo de seus relatórios de acordo (ou filtre a lista retornada por posição) em vez de assumir que o intervalo restringe a verificação.
Nenhum desses é um bloqueador — eles são a diferença entre um recurso que “funciona na demonstração” e um que se comporta de forma previsível em produção.
10. Manipulação de erros e notas operacionais
O contrato que o controlador documenta
| Status | Meaning | Typical cause |
|---|---|---|
| 400 | Requisição Inválida | URL/parâmetros inválidos — por exemplo, um cellArea malformado ou um searchText ausente |
| 401 | Não Autorizado | Falha na autenticação ou nenhuma credencial válida foi fornecida |
| 404 | Não Encontrado | O arquivo de origem não está acessível no armazenamento em nuvem |
| 500 | Erro do Servidor | O serviço encontrou uma anomalia ao obter os dados da planilha |
Internamente, cada ação envolve seu trabalho em um helper (WorkbookElementOperation, UpdateWorkbookElementOperation, UpdateWorkbookElementOperationAndSave) que captura falhas e as relança como uma CellsApiException prefixada com o nome da operação — por exemplo SearchContentInRemoteRange Error Message: .... Esse nome de operação é a string que você verá nos seus logs:
| Nome da operação | Família de endpoint |
|---|---|
SearchSpreadsheetContent, SearchContentInRemoteSpreadsheet |
Pesquisa local / remota |
SearchContentInRemoteWorksheet, SearchContentInRemoteRange |
Pesquisa remota com escopo |
ReplaceSpreadsheetContent |
Substituição local (resultado em fluxo) |
ReplaceContentInRemoteSpreadsheet, ReplaceContentInRemoteWorksheet, ReplaceContentInRemoteRange |
Substituição remota (resultado salvo) |
SearchSpreadsheetBrokenLinks, SearchBrokenLinksInRemoteSpreadsheet, SearchBrokenLinksInRemoteWorksheet, SearchBrokenLinksInRemoteRange |
Validação de links |
Parâmetros opcionais que os SDKs expõem
Além dos parâmetros documentados, os modelos de solicitação de armazenamento em nuvem possuem os mesmos três ajustes opcionais:
password— abre uma pasta de trabalho protegida por senha (as pesquisas não exigem acesso de gravação, portanto arquivos protegidos contra leitura funcionam bem);storageName— direciona um armazenamento em nuvem personalizado/anexado em vez do padrão (Python:storage_name);regoin— a configuração de região/locale usada ao interpretar a pasta de trabalho (Python escreve isso comoregion).
Autenticação
Todos os SDKs autenticam automaticamente com OAuth 2.0 client_credentials e um JWT; ao usar cURL puro, chame /connect/token uma vez primeiro (veja §4, ①).
11. Por que Aspose.Cells Cloud para pesquisa e substituição?
- ✅ Zero dependências locais — sem Office/Excel, sem COM, sem host de script. Chamável de qualquer linguagem, qualquer plataforma (Linux, containers, serverless);
- ✅ Mais profundo que busca de texto — células, formas e hiperlinks são todos alvos de correspondência de primeira classe, que é exatamente onde as planilhas reais mantêm seu conteúdo;
- ✅ Operações com escopo — workbook / worksheet / range, para que você possa corrigir uma região de uma planilha sem reescrever um arquivo de 50 MB;
- ✅ Nativo da nuvem ou sem estado — arquivos já armazenados nunca deixam o armazenamento; operações de upload local não persistem nada;
- ✅ Reescrita de alta fidelidade — substituições são aplicadas através do motor Aspose.Cells e reserializadas, de modo que fórmulas, estilos, gráficos e formatação sobrevivem à ida e volta;
- ✅ Um formato em todos os SDKs — as superfícies cURL, .NET, Python e Java mapeiam 1:1, então o padrão que você copia de uma linguagem funciona nas outras.
Comece agora: registre‑se no Aspose Cloud Dashboard, crie um Aplicativo, insira suas credenciais em qualquer trecho de código acima e aponte para uma das suas próprias pastas de trabalho — você terá uma auditoria de conteúdo funcional em minutos.
Achou isso útil? Marque com estrela, adicione aos favoritos ou compartilhe — e nos conte nos comentários para que você está usando a pesquisa e substituição de planilhas.