无需本地 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. 开始之前需要的两件事

  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 同样适用(见下文)。

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”。

觉得这有用吗?给它加星标、收藏或分享——并在评论中告诉我们您自己的电子表格转换使用案例。