> هیچ نصب محلی Excel. هیچ سرور تبدیل برای نگهداری. تبدیل XLSX → PDF، Excel → CSV/JSON/تصاویر/HTML به تماس‌های REST ساده تبدیل کنید — و در عرض حدود سه دقیقه “نرم‌افزار تبدیل صفحه‌گسترده ابری” خود را راه‌اندازی کنید. “تبدیل آن صفحه‌گسترده به یک فرمت دیگر” یکی از رایج‌ترین نیازها در توسعه روزمره است: - تیم‌های مالی و حقوقی می‌خواهند یک گزارش فقط خواندنی و مقاوم در برابر دستکاری به جای یک .xlsx که هر کسی می‌تواند ویرایش کند؛ - تیم‌های داده نیاز دارند داده‌های جدولی را به سیستم‌های پایین‌دستی به عنوان CSV / JSON بکشند؛ - برنامه‌های وب و موبایل می‌خواهند ورق‌ها — و حتی نمودارها — مستقیماً به PNG / SVG رندر شوند؛ - پورتال‌ها می‌خواهند قطعات تمیز HTML / HTML-Table را جاسازی کنند؛ - کسی نیاز دارد که یک دسته از فایل‌های .xls / .xlsx / .csv / .ods را به یک فرمت نرمال کند. پاسخ‌های قدیمی — یک نصب محلی Excel با ماکروها، یا یک مؤلفه COM سنگین در سرور خودتان — مقیاس‌پذیری دردناکی دارند و نگهداری آن‌ها در پلتفرم‌های مختلف دشوار است. Aspose.Cells Cloud همه این‌ها را با یک API REST خالص جایگزین می‌کند: یک فایل را آپلود کنید، یک فایل با فرمت جدید دریافت کنید. این پست به بررسی سه API تبدیل که توسط ConversionController در میکروسرویس Aspose.Cells Cloud ارائه شده است می‌پردازد (منبع: src/Aspose.Cells.Cloud.MicroService/Controllers/ConversionController.cs)، با مثال‌های قابل اجرا در cURL، C# (.NET)، Python و Java. — ## 1. ویژگی تبدیل چه کارهایی می‌تواند انجام دهد؟ ConversionController کنترلری است که به تبدیل فرمت / صادرات اختصاص داده شده است. این کنترلر تبدیل با کیفیت بالا را به سه مجموعه از API های HTTP می‌پیوندد: | # | سناریو | نقطه انتهایی معمولی | چه کاری انجام می‌دهد | | — | ———————————————————— | ———————————————— | —————————————————————————————————————————- | | 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 مگابایتی فقط برای گرفتن یک نمودار ندارید — فقط آنچه را که نیاز دارید تبدیل کنید و پهنای باند و محاسبات را صرفه‌جویی کنید. — ## 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"); > نیاز به یک کار batch دارید؟ این را در یک حلقه بر روی یک دایرکتوری قرار دهید و شما “کل پوشه 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 (یا ذخیره‌سازی شیء شما) وجود دارد، نیازی به دانلود/آپلود فایل‌های بزرگ نیست — تبدیل در ابر انجام می‌شود، که انتقال داده را به حداقل می‌رساند و عملکرد را در کاربرگ‌های بزرگ بهبود می‌بخشد: bash # cloud 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” را به عنوان 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 استفاده می‌کنند. در SDK .NET، موارد نمودار دارای پوشش‌های نوعی هستند که به این مسیرهای v4.0 نگاشته می‌شوند — ConvertChartToImage (convert/chart/image) و ConvertChartToPdf (convert/chart/pdf). واریانت‌های worksheet/*، range/* و table/* هنوز هیچ پوششی در v4.0 ندارند، بنابراین آن‌ها را به صورت خام REST دقیقاً همان‌طور که cURL بالا انجام می‌دهد فراخوانی کنید. — ## 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 1:1 نگاشته می‌شوند، بنابراین شما می‌توانید به راحتی الگوی مورد نظر خود را کپی کنید. اکنون شروع کنید: در Aspose Cloud Dashboard ثبت‌نام کنید، یک برنامه ایجاد کنید، اعتبارنامه‌های خود را در هر کدام از کدهای بالا قرار دهید و آن را اجرا کنید — شما در عرض چند دقیقه “تبدیل‌کننده Excel ابری” خود را خواهید داشت. آیا این مفید بود؟ ستاره، نشانه‌گذاری یا به اشتراک‌گذاری کنید — و در نظرات درباره موارد استفاده خود از تبدیل صفحه‌گسترده به ما بگویید.