Encuéntralo, arréglalo, valídalo: Una guía completa de la API de búsqueda, reemplazo y enlaces rotos de Aspose.Cells Cloud (.NET / Python / Java / cURL)
“¿Cuál de nuestros 400 libros de presupuesto aún dice Old Vendor Ltd?” “Reemplace cada marcador de posición
{{COMPANY}}en esta plantilla.” “¿Alguno de nuestros informes todavía enlaza con ese dominio que retiramos el año pasado?” — tres preguntas muy diferentes, una respuesta compartida: una llamada REST que lee y reescribe hojas de cálculo en la nube, sin Excel instalado en ninguna parte.
Los problemas de contenido de hoja de cálculo aparecen en casi cualquier base de código intensiva en datos:
- Auditoría de contenido — encontrar cada celda, forma o hipervínculo que mencione un nombre de producto obsoleto, una dirección de oficina antigua o una entidad legal caduca;
- Renderizado de plantillas — rellenar los tokens
{{PLACEHOLDER}}en todas las hojas antes de enviar un libro de trabajo a un cliente; - Envejecimiento de enlaces — comprobar que las URL incrustadas en un libro de trabajo todavía se resuelvan, antes de que una tarea de cumplimiento o archivado lo apruebe;
- Corrección masiva — corregir un error tipográfico o un valor de columna mal escrito en docenas de hojas, o limitado a solo una región de una hoja.
Las opciones tradicionales — una biblioteca de scripts que se ejecuta en tu propio equipo, una macro de Excel o un componente COM en un servidor Windows — implican que tú eres quien aloja y escala la lógica de hojas de cálculo. Aspose.Cells Cloud lo convierte en un REST sencillo: envía un archivo (o solo el nombre del archivo), recibe coincidencias — o un archivo corregido — de vuelta.
Esta publicación recorre las API expuestas por el SearchController central en el microservicio Aspose.Cells Cloud (fuente: src/Aspose.Cells.Cloud.MicroService/Controllers/SearchController.cs), con ejemplos ejecutables en cURL y C# (.NET), además de notas para usuarios de Python y Java.
1. ¿Qué puede hacer el SearchController?
SearchController cubre tres familias de capacidades, cada una disponible en varios alcances:
| Familia | Qué hace | ¿Modifica el libro de trabajo? |
|---|---|---|
| Buscar | Devuelve los elementos de texto que coinciden con una consulta — con su hoja y posición de celda/forma/hipervínculo | No |
| Reemplazar | Sustituye el texto coincidente, y luego transmite de vuelta un archivo corregido o lo guarda en el almacenamiento en la nube | Sí |
| Enlaces rotos | Valida cada hipervínculo http(s) en el libro de trabajo y devuelve los que no se pueden resolver |
No |
Y cada familia se expone en cuatro ámbitos, que es donde la lista de puntos finales se vuelve larga:
| Alcance | Buscar | Reemplazar | Enlaces rotos |
|---|---|---|---|
| Archivo local → procesamiento en línea (carga en el cuerpo de la solicitud) | PUT /v4.0/cells/search/content |
PUT /v4.0/cells/replace/content |
PUT /v4.0/cells/search/broken-links |
| Libro completo en almacenamiento en la nube | PUT /v4.0/cells/{name}/search/content |
PUT /v4.0/cells/{name}/replace/content |
PUT /v4.0/cells/{name}/search/broken-links |
| Hoja de cálculo única en almacenamiento en la nube | 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 |
| Rango único en almacenamiento en la nube | 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 |
Más dos endpoints de bonificación que vuelcan cada elemento de texto en un libro de trabajo — vea §4:
| Objetivo | Punto final |
|---|---|
| Todos los elementos de texto en un archivo en la nube | PUT /v4.0/cells/{name}/search/content/all-textitems |
| Todos los elementos de texto en una carga local | PUT /v4.0/cells/search/content/all-textitems |
Nota de implementación: las rutas están prefijadas con
v{version:apiVersion}/cellsy este controlador es[ApiVersion("4.0")], por lo que las llamadas en vivo se ven comohttps://api.aspose.cloud/v4.0/cells/.... Todo en este controlador es unPUT— incluso las búsquedas de solo lectura — porque una búsqueda se modela como una operación enviada contra un recurso, no como unGETcacheable.
Los dos modos de operación, y por qué importan
El controlador decora cada acción, y el decorador le indica exactamente de dónde proviene el archivo:
[OnlineOperation]— sin estado. Subes el libro de trabajo en el cuerpo de la solicitud (multipart), el servidor lo procesa en memoria y no se persiste nada en el almacenamiento en la nube. Perfecto para “simplemente dime qué hay en este archivo” y para plantillas de un solo uso.[CloudFileOperation]— con respaldo de almacenamiento. El servidor recupera{name}del almacenamiento en la nube (opcionalmente bajofolder=), realiza el trabajo y — para las operaciones de reemplazo — escribe el resultado directamente de vuelta. Nada viaja a tu máquina.
Esa única distinción, junto con los segmentos de ruta {worksheet} / {cellArea}, constituye todo el modelo mental. El resto de esta publicación son solo los detalles.
2. Los modelos de respuesta que realmente analizarás
Ambas familias de búsqueda devuelven una forma pequeña, plana y fácil de enlazar. Search devuelve 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"
}
]
}
La búsqueda de enlaces rotos devuelve BrokenLinksResponse:
{
"Code": 200,
"Status": "OK",
"BrokenLinks": [
{
"Filename": "Book1.xlsx",
"Worksheet": "Links",
"Position": "Hyperlink:Sheet1!B4",
"LinkAddress": "https://retired-domain.example.com/report"
}
]
}
Dos cosas vale la pena señalar de inmediato:
-
Positiones una ubicación etiquetada, no solo una dirección de celda. Está precedida porCell:,Hyperlink:oShape:, que es como una lista plana única puede indicarte qué tipo de elemento coincidió. Esa etiqueta es la diferencia entre “arreglar la celda B7” y “arreglar el cuadro de texto que está sobre B7”. -
Ambos modelos son auto‑descriptivos para informes —
FilenameyWorksheetse devuelven en cada elemento, por lo que un escaneo a través de muchos libros de trabajo puede concatenarse en una tabla de auditoría única sin procesamiento posterior.
3. Dos cosas que necesitas antes de comenzar
- Registre una cuenta gratuita en el Aspose Cloud Dashboard y cree una aplicación para obtener un
Client IDyClient Secret(los SDK intercambian estos por un JWT automáticamente — no es necesario crear encabezados de autenticación manualmente). - Instale el SDK para el lenguaje de su elección:
<!-- .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>
¿No se requiere SDK? Todo es REST puro, por lo que cURL funciona igual de bien (ver abajo). La familia de búsqueda/reemplazo/enlaces rotos también es accesible a través de modelos de solicitud tipados del SDK —
SearchSpreadsheetContentRequest,ReplaceContentInRemoteRangeRequesty sus amigos — que es lo que usan los fragmentos de C# a continuación.
4. Escenario A: Buscar un archivo local en línea (sin persistencia)
Esto es PUT /v4.0/cells/search/content — sube el libro de trabajo, recibe de vuelta las coincidencias. Sin almacenamiento en la nube, sin limpieza, sin copia dejada atrá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"
Limítalo a una hoja, o a una región de una hoja, con dos parámetros de consulta adicionales:
# 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");
Los modelos de solicitud también exponen
password(abrir un libro protegido) yregoin(configuración de región/locale) — los mismos parámetros opcionales que verás en las variantes de cloud‑storage comostorageName. Ten en cuenta que el SDK .NET mantiene la ortografíaregoin; el SDK de Python llama a los mismos dos ajustespasswordyregion.
③ Python / Java
El SDK de Python envuelve la misma familia de endpoints, con los campos del modelo de solicitud mapeados a los de C# uno a uno, pero en 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)
El SDK de Java sigue la misma forma con objetos Request construidos mediante 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()));
}
}
Si estás usando REST sin envoltorios, el cURL anterior es el contrato completo — el campo multipart simplemente debe llevar el nombre de archivo, ya que el servicio deriva el nombre del libro de trabajo (y, por lo tanto, su formato) a partir de él.
5. Escenario B: Buscar un archivo que ya está en el almacenamiento en la nube
Cuando el libro de trabajo ya está en Aspose Cloud Storage, omita la descarga por completo — el servicio lo lee donde 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 qué tres endpoints en lugar de uno? Porque la ruta lleva el alcance. El endpoint whole-workbook recibe un nombre y una consulta; el endpoint worksheet recibe un segmento de hoja de cálculo; el endpoint range recibe una hoja de cálculo y un segmento de rango. Es una forma REST limpia y cacheable — y significa que los parámetros “narrow my search” (
worksheet,cellArea) existen solo en el endpoint local-file, lo cual vale la pena recordar al trasladar una llamada de un alcance a otro.
6. Escenario C: Obtener todos los elementos de texto en un libro de trabajo
A veces no tienes un término de búsqueda — deseas el inventario. Los endpoints all-textitems devuelven cada elemento de texto en el libro de trabajo, de modo que puedes comparar dos revisiones, crear un glosario de traducción o alimentar un 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"
La respuesta es el mismo envoltorio SearchResponse, con Content rellenado para cada cadena de celda, título de hipervínculo y texto de forma en el archivo. Esto es la primitiva “grep the whole workbook”.
7. Escenario D: Reemplazar — y los dos resultados muy diferentes
Replace es donde la API se divide en dos, y la división es deliberada:
| Carga local → descargar el archivo corregido | Archivo en la nube → guardado de nuevo en el almacenamiento | |
|---|---|---|
| Punto final | PUT /v4.0/cells/replace/content |
PUT /v4.0/cells/{name}/replace/content |
| Devuelve | Un flujo de archivo (mismo formato que subiste) | CellsCloudResponse { "Code": 200, "Status": "OK" } |
| Almacenamiento modificado | Ninguno | El archivo original está sobrescrito |
① Reemplazar en un libro de trabajo local, transmitir el resultado de vuelta
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");
También hay dos parámetros de alcance disponibles aquí — sheetname y cellarea — para que puedas renderizar marcadores de posición en una hoja sin tocar el resto de la plantilla.
② Reemplazar en un libro de trabajo en la nube, conservarlo en su lugar
# 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"));
El reemplazo en el lugar es destructivo por diseño. Las variantes en la nube sobrescriben
{name}— no se crea una copia de seguridad. Para flujos de trabajo con auditoría intensiva, mantenga una copia versionada (p. ej. cargueBook1-2026-09-11.xlsxprimero, luego reemplace) o use la variante de carga local y almacene el flujo devuelto usted mismo.
8. Escenario E: Encuentra enlaces rotos antes de que lo haga alguien más
La verificación de enlaces es la función oculta aquí — es el tipo de cosa que resulta tediosa de escribir por ti mismo y vergonzosa de omitir. Las cuatro áreas están disponibles; la variante de archivo local es la verificación de sanidad más 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}");
}
El resultado es una lista que puedes usar directamente: cada entrada indica el nombre de la hoja, la posición y el LinkAddress problemático.
9. ¿Qué se escanea realmente? (los detalles de implementación que cambian sus expectativas)
Esta es la parte que separa una integración que funciona de una que sorprende. Al leer WorkbookExtension.cs, una búsqueda recorre tres tipos de elementos distintos en cada hoja de cálculo:
| Tipo de elemento | Origen | Qué coincide | Position etiqueta |
|---|---|---|---|
| Cadenas de celdas | worksheet.Cells |
El valor de cadena de la celda | Cell:A1 |
| Hipervínculos | worksheet.Hyperlinks |
Tanto la dirección del enlace como su texto de visualización | Hyperlink:Sheet1!B4 |
| Formas | worksheet.Shapes |
shape.Text — cuadros de texto, llamadas, etiquetas |
Shape:TextBox 3 |
Y aquí están los comportamientos que vale la pena conocer antes de diseñar alrededor de ellos:
Solo se buscan celdas de tipo cadena. El escaneo filtra por CellValueType.IsString. Una celda que contiene un número, una fecha o un booleano se omite — por lo que una búsqueda de 2025 no coincidirá con una celda con formato de fecha cuyo valor serial sea 2025. Las celdas cuyas fórmulas evalúan a texto sí coinciden, porque su tipo de valor es cadena.
La sensibilidad a mayúsculas y minúsculas es la única opción de coincidencia. ignoringCase cambia entre la comparación InvariantCultureIgnoreCase y InvariantCulture — nada más. No hay modo de palabra completa, expresiones regulares o “coincidir todo el valor de la celda”, a pesar de lo que puedan sugerir los documentos de API generados. Si necesitas esas semánticas, obtén el inventario all-textitems y filtéralo por tu cuenta.
Replace es una sustitución simple, sensible a mayúsculas y minúsculas, literal. La bandera ignoringCase de Search no tiene equivalente en Replace — la ruta de reemplazo no tiene ningún parámetro de insensibilidad a mayúsculas. Y los dos caminos de código difieren internamente: un reemplazo de hoja completa delega en el método Worksheet.Replace(...) del motor, mientras que un reemplazo limitado a un rango itera el rango y reescribe cada celda de texto con cell.StringValue.Replace(...). Consecuencia práctica: el reemplazo limitado a rango solo afecta a celdas de texto, y es literal, no basado en patrones.
Las coincidencias de hipervínculo informan la dirección, no el título. Cuando una búsqueda coincide con el texto de visualización de un hipervínculo, el Content devuelto sigue siendo hyperlink.Address. Si estás generando un informe de “lo encontré aquí”, espera la URL — el título no se devuelve.
La verificación de enlaces rotos solo analiza http:// y https://. Los enlaces mailto: , rutas de archivos locales y anclajes internos #Sheet1!A1 se omiten por completo — nunca se prueban, por lo que nunca aparecerán en los resultados. También escanea hipervínculos adjuntos a formas así como a celdas, que es exactamente donde los enlaces muertos tienden a ocultarse. Tenga en cuenta que una Position de enlace roto se construye a partir del hyperlink.Area sin procesar (no del más amigable Area.ToRangName() que usan los puntos finales de búsqueda), así que no asuma que ambas familias renderizan posiciones idénticamente — analice el par Worksheet + LinkAddress si necesita una clave estable.
“Broken” significa “inaccesible”, no “código de estado incorrecto”. La comprobación envía una solicitud HTTP HEAD por cada enlace y trata cualquier respuesta — incluyendo 404 o 500 — como accesible; solo marca un enlace como roto cuando la solicitud lanza (fallo de DNS, conexión rechazada, error TLS, tiempo de espera). Así que trate la salida como “enlaces que no pudieron ser contactados”. Si lo que realmente necesita son “enlaces que no devuelven 2xx”, querrá volver a comprobar los valores LinkAddress devueltos usted mismo.
cellArea se acepta pero no se aplica en los puntos finales de enlaces rotos. La implementación BrokenLinks filtra solo por el nombre de la hoja de cálculo; el argumento de área de celda se pasa pero nunca se usa. En la práctica, eso significa que .../ranges/A1:F40/search/broken-links actualmente se comporta igual que /worksheet/search/broken-links para la misma hoja — los enlaces se validan en toda la hoja. Ajuste el alcance de sus informes en consecuencia (o filtre la lista devuelta por posición) en lugar de asumir que el rango reduce la verificación.
Ninguno de estos es un obstáculo — son la diferencia entre una característica que “funciona en la demo” y una que se comporta de forma predecible en producción.
10. Manejo de errores y notas operativas
El contrato que el controlador documenta
| Estado | Significado | Causa típica |
|---|---|---|
| 400 | Solicitud incorrecta | URL/parámetros inválidos — p. ej., un cellArea mal formado, o un searchText ausente |
| 401 | No autorizado | Falló la autenticación o no se proporcionaron credenciales válidas |
| 404 | No encontrado | El archivo de origen no es accesible en el almacenamiento en la nube |
| 500 | Error del servidor | El servicio encontró una anomalía al obtener los datos de la hoja de cálculo |
Internamente, cada acción envuelve su trabajo en un ayudante (WorkbookElementOperation, UpdateWorkbookElementOperation, UpdateWorkbookElementOperationAndSave) que captura fallos y los vuelve a lanzar como una CellsApiException con el prefijo del nombre de la operación — por ejemplo SearchContentInRemoteRange Error Message: .... Ese nombre de operación es la cadena que verás en tus registros:
| Nombre de la operación | Familia de endpoint |
|---|---|
SearchSpreadsheetContent, SearchContentInRemoteSpreadsheet |
Búsqueda local / remota |
SearchContentInRemoteWorksheet, SearchContentInRemoteRange |
Búsqueda remota con alcance |
ReplaceSpreadsheetContent |
Reemplazo local (resultado en flujo) |
ReplaceContentInRemoteSpreadsheet, ReplaceContentInRemoteWorksheet, ReplaceContentInRemoteRange |
Reemplazo remoto (guarda el resultado) |
SearchSpreadsheetBrokenLinks, SearchBrokenLinksInRemoteSpreadsheet, SearchBrokenLinksInRemoteWorksheet, SearchBrokenLinksInRemoteRange |
Validación de enlaces |
Parámetros opcionales que exponen los SDK
Más allá de los parámetros documentados, los modelos de solicitud de cloud‑storage incluyen los mismos tres ajustes opcionales:
password— abre un libro de trabajo protegido con contraseña (las búsquedas no requieren acceso de escritura, por lo que los archivos protegidos contra lectura funcionan bien);storageName— apunta a un almacenamiento en la nube personalizado/adjunto en lugar del predeterminado (Python:storage_name);regoin— la configuración de región/idioma utilizada al interpretar el libro de trabajo (Python lo escriberegion).
Autenticación
Todos los SDK se autentican automáticamente con OAuth 2.0 client_credentials y un JWT; al usar cURL sin procesar, llame a /connect/token una vez primero (ver §4, ①).
Below is the Markdown content to translate:
11. ¿Por qué Aspose.Cells Cloud para buscar y reemplazar?
- ✅ Cero dependencias locales — sin Office/Excel, sin COM, sin host de scripting. Llamable desde cualquier lenguaje, cualquier plataforma (Linux, contenedores, sin servidor);
- ✅ Más profundo que la búsqueda de texto — celdas, formas y hipervínculos son todos objetivos de coincidencia de primera clase, que es exactamente donde las hojas de cálculo reales guardan su contenido;
- ✅ Operaciones con alcance — libro de trabajo / hoja de cálculo / rango, para que puedas corregir una región de una hoja sin reescribir un archivo de 50 MB;
- ✅ Nativo en la nube o sin estado — los archivos ya en almacenamiento nunca lo abandonan; las operaciones de carga local no persisten nada en absoluto;
- ✅ Reescritura de alta fidelidad — los reemplazos se aplican a través del motor Aspose.Cells y se reserializan, por lo que fórmulas, estilos, gráficos y formato sobreviven al viaje de ida y vuelta;
- ✅ Una forma en todos los SDK — las superficies cURL, .NET, Python y Java se mapean 1:1, por lo que el patrón que copies de un lenguaje funciona en los demás.
Comienza ahora: regístrate en el Aspose Cloud Dashboard, crea una aplicación, inserta tus credenciales en cualquier fragmento anterior y apunta a uno de tus propios libros de trabajo — tendrás una auditoría de contenido funcional en minutos.
¿Te resultó útil? Marca con estrella, guarda en marcadores o compártelo — y cuéntanos en los comentarios para qué estás usando la búsqueda y reemplazo en el libro de trabajo.