无需本地 Excel 安装。无需维护转换服务器。将 XLSX → PDF、Excel → CSV/JSON/图片/HTML 转换为普通 REST 调用 —— 并在大约三分钟内运行您的第一个“云电子表格转换器”。
“将该电子表格转换为不同的格式” 是日常开发中最常见的需求之一。
- 财务和法务团队希望获得 只读、抗篡改的 PDF 报告,而不是任何人都可以编辑的
.xlsx; - 数据团队需要将表格数据提取到下游系统,格式为 CSV / JSON;
- Web 和移动应用希望将工作表——甚至 图表——直接渲染为 PNG / SVG;
- 门户网站需要干净的 HTML / HTML-Table 代码片段以嵌入;
- 有人需要将一堆
.xls / .xlsx / .csv / .ods文件统一为一种格式。
传统的答案——本地安装带宏的 Excel,或在您自己的服务器上使用重量级 COM 组件——在扩展时困难且难以保持跨平台。Aspose.Cells Cloud 用纯 REST API 替代了所有这些:上传文件,获取新格式文件返回。
本文介绍了 Aspose.Cells Cloud 微服务中核心 ConversionController 所公开的三个转换 API(源代码:src/Aspose.Cells.Cloud.MicroService/Controllers/ConversionController.cs),并提供了 cURL、C#(.NET)、Python 和 Java 的可运行示例。
1. 转换功能能做什么?
ConversionController 是专用于 格式转换/导出 的控制器。它将引擎级的高保真转换封装为三组 HTTP API:
| # | 场景 | 典型端点 | 功能说明 |
|---|---|---|---|
| 1 | 文件已在云存储中 → 下载新格式 | GET /v4.0/cells/{name}?format=pdf |
直接在云存储中转换工作簿并将结果流式返回 — 大文件无需传输到本地机器 |
| 2 | 本地文件 → 在线转换(核心功能) | PUT /v4.0/cells/convert/spreadsheet?format=pdf |
您在请求体(multipart)中上传文件;服务器进行转换并直接返回结果文件 |
| 3 | 云文件 → 保存为新格式,回写至云存储 | PUT /v4.0/cells/{name}/saveas?format=pdf |
转换后的文件直接写回云存储 — 非常适合自动化流水线 |
实现说明:源路由使用前缀
v{version}/cells,API 版本为4.0,因此实际调用的形式类似https://api.aspose.cloud/v4.0/cells/...
转换粒度远远超出 “整个文件”
除了转换整个工作簿之外,控制器还可以导出一个 单个元素:
- 特定的 工作表 → PDF / image / CSV / JSON / HTML
- 特定的 单元格范围 (例如
A1:C12) → PDF / image / CSV / JSON / HTML - 特定的 表格 → PDF / image / CSV / JSON / HTML
- 特定的 图表 → PNG / JPEG / BMP / GIF / SVG / TIFF / EMF / PDF
这样您就永远不必为了获取一个图表而转换整整 50 MB 的工作簿 — 仅转换您需要的内容,节省带宽和计算资源。
2. 支持哪些格式?
基于控制器中内置的 ExportData 注册表,转换矩阵大致如下:
| 类型 | 格式 |
|---|---|
| 导入 和 导出(双向) | XLS, XLSX, XLSB, XLSM, CSV, TSV, ODS, TXT |
| 仅导出 | PDF, OTS, XPS, DIF, HTML / MHTML, JSON, PNG, JPEG, BMP, SVG, TIFF, EMF, NUMBERS, FODS, Markdown, DOCX, PPTX, SQL, 等等. |
简而言之:电子表格到电子表格 各种转换,以及 整个电子表格 → PDF / 图像 / Web 数据输出系列——全部统一在一个 API 接口上。
3. 开始之前需要的两件事
- 在 Aspose Cloud Dashboard 注册免费账户并创建一个应用程序,以获取
Client ID和Client Secret(SDK 会自动将它们交换为 JWT,无需自行构建身份验证标头)。 - 为您选择的语言安装 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 同样适用(见下文)。
4. 场景 1:将本地 Excel 文件在线转换(标题为 Convert API)
这是 PUT /v4.0/cells/convert/spreadsheet — 旗舰的 “Convert” API:
在请求体中上传本地文件,服务器会进行转换并将新文件流式返回。文件不会保存在云存储中,也不会留下上传副本 — 完美适用于 “just convert this for me” 场景。
① 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) XLSX -> PDF
curl -X PUT "https://api.aspose.cloud/v4.0/cells/convert/spreadsheet?format=pdf" \
-H "Authorization: Bearer $TOKEN" \
-F "file=@Book1.xlsx" \
-o Book1.pdf
将 format 替换为 csv、json、png、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");
var request = new ConvertSpreadsheetRequest(
spreadsheet: "C:/invoices/Book1.xlsx", // local file path
format: "pdf"); // target: pdf / csv / json / png ...
using Stream result = cellsApi.ConvertSpreadsheet(request); // converted file stream
using var outFile = File.Create("C:/invoices/Book1.pdf");
result.CopyTo(outFile);
// Even simpler: point the SDK at an output path and let it write the file
// cellsApi.ConvertSpreadsheet(request, "C:/invoices/Book1.pdf");
需要批处理作业吗?将其放入对目录的循环中,即可实现 “将整个文件夹的 XLSX 转换为 PDF”.
③ Python
from asposecellscloud.apis.cells_api import CellsApi
from asposecellscloud.requests import ConvertSpreadsheetRequest
import os
instance = CellsApi(
os.getenv('CellsCloudClientId'),
os.getenv('CellsCloudClientSecret'))
# Local XLSX -> PDF, result written locally
instance.convert_spreadsheet(
ConvertSpreadsheetRequest("Book1.xlsx", "pdf"),
local_outpath="Book1.pdf")
# Other formats: just change the parameter — json / csv / xlsx / png ...
④ Java
import com.aspose.cloud.cells.api.CellsApi;
import com.aspose.cloud.cells.request.ConvertSpreadsheetRequest;
import java.io.File;
public class ConvertDemo {
public static void main(String[] args) throws Exception {
CellsApi api = new CellsApi("YOUR_CLIENT_ID", "YOUR_CLIENT_SECRET");
ConvertSpreadsheetRequest req = new ConvertSpreadsheetRequest();
req.setSpreadsheet("C:/invoices/Book1.xlsx"); // local file path
req.setFormat("pdf"); // target: pdf / csv / json / png ...
File out = api.convertSpreadsheet(req); // converted result as a File
out.renameTo(new File("C:/invoices/Book1.pdf"));
System.out.println("Converted: " + out.getAbsolutePath());
}
}
四种语言,一次操作:提供路径 + 格式参数 → 返回目标文件。这就是 Convert API 的全部卖点——调用方无需 Excel 依赖,无需模板,也不需要 COM 组件。
5. 场景 2:直接转换云存储文件
当文件已经位于 Aspose Cloud Storage(或您的对象存储)中时,您无需下载/上传大文件——转换在云端完成,最小化数据传输并提升大工作簿的性能:
# cloud Book1.xlsx -> PDF, downloaded locally
curl -G "https://api.aspose.cloud/v4.0/cells/Book1.xlsx" \
-H "Authorization: Bearer $TOKEN" \
--data-urlencode "format=pdf" \
--data-urlencode "folder=Reports" \
-o Book1.pdf
from asposecellscloud.apis.cells_api import CellsApi
from asposecellscloud.requests import ExportSpreadsheetAsFormatRequest
instance = CellsApi("YOUR_CLIENT_ID", "YOUR_CLIENT_SECRET")
# Convert a cloud-stored workbook straight to PDF
instance.export_spreadsheet_as_format(
ExportSpreadsheetAsFormatRequest("Book1.xlsx", format="pdf", folder="Reports"))
您还可以深入单个元素——例如,将“Sheet1 上的第 3 个图表”渲染为 PNG(云存储版本):
# chart -> PNG
curl -G "https://api.aspose.cloud/v4.0/cells/Book1.xlsx/worksheets/Sheet1/charts/2" \
-H "Authorization: Bearer $TOKEN" \
--data-urlencode "format=png" \
-o chart.png
细粒度云端点概览:
| 目标 | 端点 | 示例 format |
|---|---|---|
| 整个工作簿 | GET /v4.0/cells/{name} |
pdf / xlsx / csv / json |
| 单个工作表 | GET /v4.0/cells/{name}/worksheets/{ws} |
pdf / png / svg |
| 单个范围 | GET /v4.0/cells/{name}/worksheets/{ws}/ranges/{range} |
pdf / csv / json / html / png |
| 单个表格 | GET /v4.0/cells/{name}/worksheets/{ws}/tables/{table} |
pdf / csv / json / html / png |
| 单个图表 | GET /v4.0/cells/{name}/worksheets/{ws}/charts/{index} |
pdf / png / jpeg / svg / tiff |
6. 场景 3:SaveAs — 将结果写回云存储
当您希望将转换后的文件 持久化回云存储(而不是下载)时,请使用 PUT /v4.0/cells/{name}/saveas。这非常适合自动化场景,例如 “导出今天的报告为 PDF 以进行归档,每天一次”:
curl -X PUT "https://api.aspose.cloud/v4.0/cells/Book1.xlsx/saveas?format=pdf" \
-H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
-d '{}'
from asposecellscloud.apis.cells_api import CellsApi
from asposecellscloud.requests import SaveSpreadsheetAsRequest
instance = CellsApi("YOUR_CLIENT_ID", "YOUR_CLIENT_SECRET")
instance.save_spreadsheet_as(
SaveSpreadsheetAsRequest("Book1.xlsx", format="pdf", folder="Reports"))
# Result is saved directly in cloud storage; returns CellsCloudResponse(Code=200, Status="OK")
您可以通过 SaveOptionsData 请求体传递细粒度的保存选项,并通过查询参数控制 输出文件名、输出存储、自定义字体、地区/语言环境、密码 等——更多细节请参见下面的 工程细节。
7. 更多现成的“online convert”端点
除了上述工作簿级别的转换外,控制器还提供了一整套专用的 local-file → specific-target 端点(与场景 1 相同的请求体上传),这些端点在粒度上更细且在带宽消耗上更低:
| 目标 | 端点(PUT,前缀 /v4.0/cells/convert/) |
|---|---|
| 工作簿 → PDF / JSON / CSV | spreadsheet/pdf, spreadsheet/json, spreadsheet/csv |
| 工作表 → PDF / JSON / CSV / HTML / HTML-Table | worksheet/pdf, worksheet/json, worksheet/csv, worksheet/html, worksheet/html-table |
| 工作表 → 图像 | worksheet/image?worksheet=Sheet1&format=png |
| 范围 → PDF / CSV / HTML / JSON / 图像 | range/pdf, range/csv, range/html, range/json, range/image?worksheet=..&range=A1:C12&format=png |
| 表格 → PDF / CSV / HTML / JSON / 图像 | table/pdf, table/csv, table/html, table/json, table/image |
| 图表 → 图像 / PDF | chart/image?worksheet=..&chartIndex=0&format=png, chart/pdf |
例如,“仅将此范围导出为下游系统的 CSV”:
curl -X PUT "https://api.aspose.cloud/v4.0/cells/convert/range/csv" \
-H "Authorization: Bearer $TOKEN" \
--data-urlencode "worksheet=Sheet1" \
--data-urlencode "range=A1:C100" \
-F "file=@data.xlsx" \
-o data.csv
这些端点使用与 convert/spreadsheet 相同的上传正文模式。在 .NET SDK 中,chart 情况有类型化的包装器映射到这些 v4.0 路由 —— ConvertChartToImage (convert/chart/image) 和 ConvertChartToPdf (convert/chart/pdf)。worksheet/*、range/* 和 table/* 变体尚未提供 v4.0 包装器,因此请像上面的 cURL 那样直接通过普通 REST 调用。
8. 工程细节与错误处理
值得了解的转换选项(查询参数)
password— 打开受密码保护的工作簿;fontsLocation/ custom-font support — 在渲染 PDF/图像时保持字形正确;- 自动调整行/列,并决定是否打印行/列标题 (
printHeadings),区域/页面设置 (region) 等; - 输出端:
outPath/outStorageName决定结果在云存储中的位置;
错误代码(控制器记录的契约)
| 状态 | 含义 | 常见原因 |
|---|---|---|
| 400 | 错误请求 | 无效的 URL / 参数,或不受支持的 format |
| 401 | 未授权 | 身份验证失败或未提供有效凭据 |
| 404 | 未找到 | 源文件在云存储中不可访问 |
| 500 | 服务器错误 | 服务在获取转换数据时出现异常 |
Authentication
所有 SDK 都会自动使用 OAuth 2.0 client_credentials 和 JWT 进行身份验证;在使用原始 cURL 时,请先调用一次 /connect/token(参见上面的场景 1,①)。
9. 为什么使用 Aspose.Cells Cloud Convert?
- ✅ 零本地依赖 — 无需 Office/Excel,无需 COM。可从任何语言和任何平台(Linux、容器、无服务器)调用;
- ✅ 高保真渲染 — 由 Aspose.Cells 引擎驱动,公式、图表、样式和分页以专业质量渲染为 PDF/图像;
- ✅ 云原生 — 文件在转换过程中可以保持在云端,避免传输大负载;纯在线转换根本不需要云存储;
- ✅ 灵活粒度 — 工作簿 / 工作表 / 区域 / 表格 / 图表:精确转换所需的部分;
- ✅ 跨 SDK 统一形态 — cURL、.NET、Python 和 Java 示例 1:1 对应,您可以直接复制喜欢的模式。
立即开始:在 Aspose Cloud 仪表板 注册,创建一个 Application,将您的凭据放入上面的任意 snippet 中,然后运行它 — 您将在几分钟内拥有自己的 “cloud Excel converter”。
觉得这有用吗?给它加星标、收藏或分享——并在评论中告诉我们您自己的电子表格转换使用案例。