تبدیل صفحات گسترده را به یک خط تبدیل کنید: راهنمای کامل Aspose.Cells Cloud Convert API (.NET / Python / Java)

بدون نصب محلی Excel. بدون نیاز به نگهداری سرور تبدیل. تبدیل XLSX → PDF، Excel → CSV/JSON/تصاویر/HTML به تماس‌های ساده REST — و داشتن اولین “مبدل صفحه‌گسترده ابری” خود را در حدود سه دقیقه راه‌اندازی کنید.

“Convert that spreadsheet to a different format” یکی از رایج‌ترین نیازها در توسعه روزمره است:

• تیم‌های مالی و حقوقی یک گزارش PDF فقط‑خواندنی، مقاوم در برابر دستکاری می‌خواهند به جای یک .xlsx که هر کسی می‌تواند ویرایش کند؛
• تیم‌های داده نیاز دارند داده‌های جدولی را به سیستم‌های پایین‌دست به عنوان CSV / JSON استخراج کنند؛
• برنامه‌های وب و موبایل می‌خواهند ورق‌های کاری — و حتی نمودارها — مستقیماً به PNG / SVG تبدیل شوند؛
• پورتال‌ها اسنیپ‌کدهای تمیز HTML / HTML-Table برای جاسازی می‌خواهند؛
• کسی نیاز دارد یک انبوه از فایل‌های .xls / .xlsx / .csv / .ods را به یک فرمت واحد نرمال‌سازی کند.

پاسخ‌های سنتی — نصب محلی Excel با ماکروها، یا یک مؤلفه COM سنگین در سرور خودتان — مقیاس‌پذیر نیستند و حفظ سازگاری چندپلتفرمی را دشوار می‌کنند. Aspose.Cells Cloud تمام این‌ها را با یک REST API خالص جایگزین می‌کند: یک فایل را بارگذاری کنید، یک فایل با فرمت جدید دریافت کنید.

این پست به بررسی سه API تبدیل ارائه‌شده توسط کنترلر اصلی ConversionController در میکروسرویس Aspose.Cells Cloud می‌پردازد (منبع: src/Aspose.Cells.Cloud.MicroService/Controllers/ConversionController.cs)، همراه با مثال‌های قابل اجرا در cURL، C# (.NET)، Python و Java.

1. قابلیت Convert چه کاری می‌تواند انجام دهد؟

ConversionController کنترلری است که به تبدیل فرمت / خروجی اختصاص دارد. این کنترلر تبدیل با دقت بالا در سطح موتور را در سه مجموعه از APIهای HTTP می‌پیچاند:

تذکر پیاده‌سازی: مسیرهای منبع از پیشوند v{version}/cells با نسخه API 4.0 استفاده می‌کنند، بنابراین تماس‌های زنده به شکل https://api.aspose.cloud/v4.0/cells/... هستند.

دقت تبدیل بسیار فراتر از “کل فایل”

علاوه بر تبدیل یک کتاب‌کار کامل، کنترلر می‌تواند یک عنصر واحد را صادر کند:

• یک worksheet خاص → PDF / image / CSV / JSON / HTML
• یک cell range خاص (مثلاً A1:C12) → PDF / image / CSV / JSON / HTML
• یک table خاص → PDF / image / CSV / JSON / HTML
• یک chart خاص → PNG / JPEG / BMP / GIF / SVG / TIFF / EMF / PDF

به‌گونه‌ای که هرگز نیازی به تبدیل یک کتاب‌کار ۵۰ مگابایتی کامل فقط برای گرفتن یک نمودار نداشته باشید — فقط آنچه نیاز دارید را تبدیل کنید و پهنای باند و محاسبه را ذخیره کنید.

2. کدام فرمت‌ها پشتیبانی می‌شوند؟

بر اساس رجیستری ExportData که به‌صورت پیش‌فرض در کنترلر وجود دارد، ماتریس تبدیل به‌صورت تقریبی به این شکل است:

به‌طور خلاصه: تبدیل‌های spreadsheet-to-spreadsheet از همه نوع، به‌علاوه تمام خانواده خروجی‌های spreadsheet → PDF / تصویر / داده‌های وب — همه پشت یک سطح 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 — API برجسته “Convert” است: فایل محلی خود را در بدنه درخواست بارگذاری کنید، سرور آن را تبدیل می‌کند و فایل جدید را به‌صورت جریان بازمی‌گرداند. هیچ‌چیزی در ذخیره‌سازی ابری نگهداری نمی‌شود و هیچ نسخه بارگذاری‌شده‌ای باقی نمی‌ماند — دقیقاً برای لحظاتی که می‌گویید “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”.

③ پایتون

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 ...

④ جاوا

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. سناریو ۲: تبدیل مستقیم یک فایل ذخیره‌شده در ابر

وقتی فایلی قبلاً در 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"))

شما همچنین می‌توانید به یک عنصر واحد نفوذ کنید — به عنوان مثال، «the 3rd chart on Sheet1» را به صورت PNG (cloud‑storage flavour) رندر کنید:

# 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

نقاط انتهایی ابری دقیق در یک نگاه:

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 پاس دهید و با استفاده از پارامترهای query، نام فایل خروجی، ذخیره‌سازی خروجی، قلم‌های سفارشی، منطقه/محلی، رمز عبور و غیره را کنترل کنید — جزئیات بیشتر در بخش جزئیات مهندسی در زیر.

7. بیشتر نقاط انتهایی آماده “تبدیل آنلاین”

علاوه بر تبدیل‌های سطح‌کاربرگ که در بالا ذکر شد، کنترلر مجموعه کاملی از نقاط انتهایی اختصاصی local-file → specific-target را ارائه می‌دهد (آپلود بدنه درخواست همانند سناریو 1)، که جزئی‌تر بوده و پهنای باند کمتری مصرف می‌کنند:

به عنوان مثال، «فقط این بازه را به‌عنوان 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 استفاده می‌کنند. در SDK .NET، موارد chart دارای بسته‌های تایپی هستند که به این مسیرهای 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 تعیین می‌کند نتیجه در کجا در ذخیره‌سازی ابری ذخیره شود؛

کدهای خطا (قرارداد مستند شده توسط کنترلر)

احراز هویت

تمام 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 Dashboard ثبت‌نام کنید، یک برنامه ایجاد کنید، اعتبارنامه‌های خود را در هر کد بالا بگذارید و آن را اجرا کنید — در عرض چند دقیقه یک «مبدل Excel ابری» خود را خواهید داشت.

این را مفید یافتید؟ ستاره بزنید، بوکمارک کنید یا آن را به اشتراک بگذارید — و درباره موارد استفاده خود از تبدیل صفحات گسترده در نظرات بگویید.