حوّل تحويل الجداول إلى سطر واحد: دليل شامل لواجهة برمجة تطبيقات Aspose.Cells Cloud Convert API (.NET / Python / Java)

لا حاجة لتثبيت Excel محليًا. لا حاجة لصيانة خادم التحويل. حوّل XLSX → PDF، Excel → CSV/JSON/صور/HTML إلى استدعاءات REST بسيطة — واحصل على أول “محول جداول بيانات سحابي” يعمل في حوالي ثلاث دقائق.

“Convert that spreadsheet to a different format” هو أحد أكثر المتطلبات شيوعًا في التطوير اليومي:

• الفرق المالية والقانونية تريد تقرير read-only, tamper-resistant PDF بدلاً من .xlsx يمكن لأي شخص تحريره؛
• فرق البيانات تحتاج إلى سحب البيانات الجدولية إلى الأنظمة اللاحقة كـ CSV / JSON؛
• تطبيقات الويب والهاتف المحمول تريد أوراق عمل — وحتى charts — تُعرض مباشرةً كـ PNG / SVG؛
• البوابات تريد مقتطفات HTML / HTML-Table نظيفة لتضمينها؛
• شخص ما يحتاج إلى توحيد مجموعة من ملفات .xls / .xlsx / .csv / .ods إلى تنسيق واحد.

الإجابات التقليدية — تثبيت Excel محلي مع وحدات ماكرو، أو مكوّن COM ثقيل على الخادم الخاص بك — صعبة التوسع وصعبة الحفاظ على التوافق عبر الأنظمة. Aspose.Cells Cloud يستبدل كل ذلك بواجهة REST API نقية: حمّل ملفًا، واحصل على ملف بصيغة جديدة.

تستعرض هذه المشاركة واجهات برمجة التطبيقات الثلاثة للتحويل التي يقدمها الـ ConversionController الأساسي في خدمة Aspose.Cells Cloud الصغيرة (المصدر: src/Aspose.Cells.Cloud.MicroService/Controllers/ConversionController.cs)، مع أمثلة قابلة للتنفيذ في cURL, C# (.NET), Python, و Java.

1. ما الذي يمكن لميزة التحويل القيام به؟

ConversionController هو المتحكم المخصص لـ تحويل الصيغ / التصدير. يلتف حول محرك المستوى العالي الدقة للتحويل إلى ثلاث مجموعات من واجهات برمجة التطبيقات HTTP:

ملاحظة التنفيذ: تستخدم مسارات المصدر البادئة 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 ميغابايت فقط للحصول على مخطط واحد — حوّل فقط ما تحتاجه ووفّر النطاق الترددي والحوسبة.

2. ما الصيغ المدعومة؟

استنادًا إلى سجل ExportData المدمج في المتحكم، يبدو مصفوفة التحويل تقريبًا كما يلي:

باختصار: تحويلات جدول-إلى-جدول من جميع الأنواع، بالإضافة إلى العائلة الكاملة لمخرجات جدول البيانات → PDF / صورة / بيانات الويب — كلها خلف واجهة برمجة تطبيقات واحدة.

3. شيئان تحتاجهما قبل أن تبدأ

1. سجّل حسابًا مجانيًا على Aspose Cloud Dashboard وأنشئ تطبيقًا للحصول على Client ID و Client Secret (تقوم SDKs بتبادل هذه القيم للحصول على 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)

This is PUT /v4.0/cells/convert/spreadsheet — the flagship “Convert” API: حمّل ملفك المحلي في جسم الطلب، يقوم الخادم بتحويله ويعيد تدفق الملف الجديد. لا يتم حفظ أي شيء في التخزين السحابي ولا تبقى نسخة من التحميل — مثالي لأوقات “فقط قم بتحويل هذا لي”.

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

④ جافا

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” كصورة 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

نقاط النهاية السحابية التفصيلية لمحة سريعة:

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. المزيد من نقاط النهاية الجاهزة “تحويل عبر الإنترنت”

بالإضافة إلى التحويلات على مستوى دفتر العمل المذكورة أعلاه، يقدّم المتحكم مجموعة كاملة من نقاط النهاية المخصصة ملف محلي → هدف محدد (نفس تحميل جسم الطلب كما في السيناريو 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). لا توجد أطر v4.0 بعد للمتغيّرات worksheet/* و range/* و table/*، لذا استدعِها عبر REST العادي تمامًا كما يفعل cURL أعلاه.

8. تفاصيل الهندسة ومعالجة الأخطاء

خيارات التحويل التي تستحق المعرفة (معلمات الاستعلام)

• password — فتح دفاتر العمل المحمية بكلمة مرور؛
• fontsLocation / دعم الخطوط المخصصة — الحفاظ على صحة الحروف عند إنشاء PDF/صور؛
• ضبط تلقائي للصفوف/الأعمدة، وتحديد ما إذا كان سيتم طباعة عناوين الصف/العمود (printHeadings)، إعداد المنطقة/الصفحة (region)، إلخ؛
• جانب الإخراج: outPath / outStorageName يحددان أين يتم حفظ النتيجة في التخزين السحابي؛

رموز الأخطاء (العقد الذي يوثقه المتحكم)

المصادقة

تقوم جميع مجموعات تطوير البرمجيات (SDKs) بالمصادقة تلقائيًا باستخدام OAuth 2.0 client_credentials و JWT؛ عند استخدام cURL الخام، استدعِ /connect/token مرة واحدة أولاً (انظر السيناريو 1، ① أعلاه).

Below is the Markdown content to translate:

9. لماذا Aspose.Cells Cloud Convert؟

• ✅ عدم وجود تبعيات محلية — لا Office/Excel، لا COM. يمكن استدعاؤه من أي لغة وأي منصة (Linux، الحاويات، بدون خادم);
• ✅ عرض عالي الدقة — مدعوم بمحرك Aspose.Cells، لذا الصيغ، المخططات، الأنماط، والصفحات تُعرض بجودة احترافية إلى PDF/images;
• ✅ سحابي الأصل — يمكن للملفات البقاء في السحابة أثناء التحويل لتجنب نقل أحجام كبيرة؛ التحويل عبر الإنترنت النقي لا يحتاج إلى تخزين سحابي على الإطلاق;
• ✅ دقة مرنة — workbook / worksheet / range / table / chart: تحويل الجزء الذي تحتاجه بالضبط;
• ✅ شكل موحد عبر SDKs — أمثلة cURL، .NET، Python و Java تتطابق 1:1، لذا يمكنك نسخ النمط الذي يعجبك حرفيًا.

ابدأ الآن: سجّل في Aspose Cloud Dashboard، أنشئ تطبيقًا، ضع بيانات الاعتماد الخاصة بك في أي مقطع شفرة أعلاه، وشغّله — ستحصل على “محول Excel السحابي” الخاص بك في دقائق.

هل وجدت هذا مفيدًا؟ ضع نجمة، أو أضف إشارة مرجعية، أو شاركه — وأخبرنا عن حالات استخدامك لتحويل جداول البيانات في التعليقات.