> 无需本地安装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. Convert功能可以做什么？
ConversionController是专门用于_格式转换/导出_的控制器。它将引擎级的高保真转换封装为三组HTTP API：
| # | 场景 | 典型端点 | 功能 |
| — | ———————————————————— | ———————————————— | —————————————————————————————————————————- |
| 1 | 云存储中的文件 → 下载新格式 | GET /v4.0/cells/{name}?format=pdf | 直接在云存储中转换工作簿并流回结果——大型文件无需传输到您的机器 |
| 2 | 本地文件 → 在线转换（主要功能） | PUT /v4.0/cells/convert/spreadsheet?format=pdf | 您在请求体中上传文件（多部分）；服务器转换并直接返回结果文件 |
| 3 | 云文件 → 另存为新格式，回写云存储 | PUT /v4.0/cells/{name}/saveas?format=pdf | 转换后的文件直接写回云存储——非常适合自动化管道 |
> 实现说明：源路由使用前缀v{version}/cells，API版本为4.0，因此实时调用看起来像https://api.aspose.cloud/v4.0/cells/...。
### 转换粒度远超“整个文件”
除了转换整个工作簿，控制器还可以导出_单个元素_：
- 特定工作表 → PDF / 图像 / CSV / JSON / HTML
- 特定单元格范围（例如A1:C12） → PDF / 图像 / CSV / JSON / HTML
- 特定表格 → PDF / 图像 / 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 / 图像 / 网络数据输出的整个系列——所有这些都在一个API接口后面。
—
## 3. 开始之前需要的两件事
1. 在Aspose Cloud Dashboard上注册一个免费账户并创建一个应用程序，以获取Client ID和Client Secret（SDK会自动将其交换为JWT——无需自己构建身份验证头）。
2. 安装您选择的语言的SDK：
xml
<!-- .NET -->
<PackageReference Include="Aspose.Cells-Cloud" Version="25.x" />
bash
# Python
pip install asposecellscloud
xml
<!-- Java（Maven）——注意：不在Maven Central上，因此需要下面的Aspose仓库 -->
<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文件（主要转换API）
这是PUT /v4.0/cells/convert/spreadsheet——旗舰“转换”API：
在请求体中上传您的本地文件，服务器转换并流回新文件。没有任何内容保留在云存储中，也没有上传副本残留——非常适合“只需为我转换这个”的时刻。
### ① cURL
bash
# 1) 首先，获取令牌
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
csharp
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", // 本地文件路径
format: "pdf"); // 目标：pdf / csv / json / png ...
using Stream result = cellsApi.ConvertSpreadsheet(request); // 转换后的文件流
using var outFile = File.Create("C:/invoices/Book1.pdf");
result.CopyTo(outFile);
// 更简单：将SDK指向输出路径，让它写入文件
// cellsApi.ConvertSpreadsheet(request, "C:/invoices/Book1.pdf");
> 需要批处理作业？将其放入循环中，您就可以实现“将整个文件夹转换为XLSX → PDF”。
### ③ Python
python
from asposecellscloud.apis.cells_api import CellsApi
from asposecellscloud.requests import ConvertSpreadsheetRequest
import os
instance = CellsApi(
os.getenv('CellsCloudClientId'),
os.getenv('CellsCloudClientSecret'))
# 本地XLSX -> PDF，结果写入本地
instance.convert_spreadsheet(
ConvertSpreadsheetRequest("Book1.xlsx", "pdf"),
local_outpath="Book1.pdf")
# 其他格式：只需更改参数——json / csv / xlsx / png ...
### ④ Java
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"); // 本地文件路径
req.setFormat("pdf"); // 目标：pdf / csv / json / png ...
File out = api.convertSpreadsheet(req); // 转换结果作为文件
out.renameTo(new File("C:/invoices/Book1.pdf"));
System.out.println("已转换: " + out.getAbsolutePath());
}
}
四种语言，一项操作：给出路径 + 格式参数 → 获取目标文件。这就是转换API的全部卖点——调用方侧零Excel依赖，无需模板，无需COM组件。
—
## 5. 场景2：直接转换云存储的文件
当文件已经存在于Aspose Cloud Storage（或您的对象存储）中时，您无需下载/上传大型文件——转换发生在云中，最小化数据传输并提高大型工作簿的性能：
bash
# 云Book1.xlsx -> PDF，下载到本地
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
python
from asposecellscloud.apis.cells_api import CellsApi
from asposecellscloud.requests import ExportSpreadsheetAsFormatRequest
instance = CellsApi("YOUR_CLIENT_ID", "YOUR_CLIENT_SECRET")
# 将云存储的工作簿直接转换为PDF
instance.export_spreadsheet_as_format(
ExportSpreadsheetAsFormatRequest("Book1.xlsx", format="pdf", folder="Reports"))
您还可以深入到单个元素——例如，将“Sheet1上的第3个图表”渲染为PNG（云存储版本）：
bash
# 图表 -> 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以进行归档”：
bash
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 '{}'
python
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"))
# 结果直接保存在云存储中；返回CellsCloudResponse(Code=200, Status="OK")
您可以通过SaveOptionsData请求体传递细粒度的保存选项，并通过查询参数控制输出文件名、输出存储、自定义字体、区域/区域、密码等——更多内容将在下面的_工程细节_中介绍。
—
## 7. 更多现成的“在线转换”端点
除了上述工作簿级转换，控制器还提供了一整套专用的本地文件 → 特定目标端点（与场景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以供下游系统使用”：
bash
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中，图表案例具有映射到这些v4.0路由的类型包装器——ConvertChartToImage（convert/chart/image）和ConvertChartToPdf（convert/chart/pdf）。worksheet/*、range/*和table/*变体尚未有v4.0包装器，因此请像上面的cURL一样通过纯REST调用它们。
—
## 8. 工程细节与错误处理
### 值得了解的转换选项（查询参数）
- password — 打开受密码保护的工作簿；
- fontsLocation / 自定义字体支持 — 在渲染PDF/图像时保持字形正确；
- 自动调整行/列，以及是否打印行/列标题（printHeadings）、区域/页面设置（region）等；
- 输出侧：outPath / outStorageName决定结果在云存储中的位置。
### 错误代码（控制器文档的合同）
| 状态 | 意义 | 典型原因 |
| ——- | ———— | ———————————————————– |
| 400 | 错误请求 | 无效的URL / 参数，或不支持的format |
| 401 | 未授权 | 身份验证失败或未提供有效凭据 |
| 404 | 未找到 | 源文件在云存储中不可访问 |
| 500 | 服务器错误 | 服务在获取转换数据时遇到异常 |
### 身份验证
所有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示例一一对应，因此您可以直接复制您喜欢的模式。
立即开始：在Aspose Cloud Dashboard上注册，创建一个应用程序，将您的凭据放入上面的任何代码片段中，然后运行——您将在几分钟内拥有自己的“云Excel转换器”。
觉得这有用吗？给我们点赞、收藏或分享——并在评论中告诉我们您自己的电子表格转换用例。
将电子表格转换变为一行代码：Aspose.Cells Cloud Convert API（.NET / Python / Java）完整指南
将电子表格转换变为一行代码