بناء تقارير إكسل باستخدام قوالب العلامات الذكية – دليل واجهة Aspose.Cells Cloud API
تُنشئ هذه الواجهة البرمجية (REST API) ملف عمل باستخدام قالب علامة ذكية.
واجهة برمجة تطبيقات العلامات الذكية لملف العمل
POST https://api.aspose.cloud/v3.0/cells/{name}/smartmarker
الأمان والمصادقة
تُعد واجهات Aspose.Cells Cloud آمنة وتشترط المصادقة القائمة على رمز JWT.
ما هي العلامة الذكية؟
العلامة الذكية هي بنية موضعية تُستخدم لربط حقول البيانات في ملف XML (أو JSON) بخلايا في قالب إكسل. وفي وقت التشغيل، تستبدل مكتبة Aspose.Cells هذه العلامات بالبيانات المقابلة، مما يسمح لك بإنشاء تقارير مُعبّأة بالكامل برمجيًا.
متغيرات الاستعلام (Query Parameters)
| اسم المتغير | النوع | الوصف |
|---|---|---|
| outPath | string | المسار الوجهة حيث سيُحفظ ملف العمل الذي تم إنشاؤه. |
| folder | string | المجلد الذي يحتوي على ملف العمل الأصلي. |
| storageName | string | اسم خدمة التخزين المراد استخدامها. |
متغير جسم الطلب
| اسم المتغير | النوع | الوصف |
|---|---|---|
| xmlFile | file | ملف بيانات العلامات الذكية XML المرفوع مع الطلب. |
الاستجابة
{
"Name": "ResponseFile",
"DataType": {
"Identifier": "File",
"Reference": "Stream",
"Name": "file"
}
}
ملاحظات / قيود:
- تدعم الواجهة البرمجية ملفات إكسل بحجم يصل إلى 50 ميغابايت.
- التنسيقات المقبولة هي .xlsx و**.xlsm** و**.xlsb** فقط.
- تُطبّق قيودًا على معدل الطلبات بمقدار 20 طلبًا في الثانية لكل حساب.
رموز حالة HTTP
| الرمز | المعنى | الوصف |
|---|---|---|
| 200 | ناجح (OK) | تمت تطبيق المرشح بنجاح؛ تحتوي الاستجابة على تفاصيل العملية. |
| 400 | طلب غير صالح (Bad Request) | معلمات مفقودة أو غير صحيحة (مثل نوع ملف غير مدعوم). |
| 401 | غير مُعتمد (Unauthorized) | رمز JWT غير صالح أو مفقود. |
| 413 | حجم الحمولة كبير جدًا (Payload Too Large) | تجاوز حجم الملف المرفوع الحد المسموح به. |
| 500 | خطأ داخلي في الخادم (Internal Server Error) | خطأ غير متوقع في الخادم. |
كيفية استخدام واجهة برمجة تطبيقات العلامات الذكية لملف العمل
مواصفات واجهة برمجة تطبيقات العلامات الذكية لملف العمل
تُعرّف مواصفات OpenAPI واجهة برمجة برمجية عامة قابلة للوصول وتتيح لك إجراء تفاعلات REST مباشرة من متصفح ويب.
استخدام مكتبات Aspose.Cells Cloud SDK
يمكنك استخدام أداة سطر الأوامر cURL للوصول بسهولة إلى خدمات Aspose.Cells عبر الويب. يوضح المثال التالي كيفية إجراء مكالمات لواجهة Cloud API باستخدام cURL.
مثال سريع مكوّن من سطر واحد
curl -X POST "https://api.aspose.cloud/v3.0/cells/{name}/smartmarker?outPath={outPath}" -H "Authorization: Bearer {access_token}" -F "xmlFile=@Sample_SmartMarker_Data.xml"
معالجة الأخطاء
| حالة HTTP | الوصف | السبب الشائع |
|---|---|---|
| 400 | طلب غير صالح (Bad Request) | ملف القالب مفقود أو ملف XML معطوب أو معلمات غير صحيحة. |
| 401 | غير مُعتمد (Unauthorized) | رمز مصادقة غير صالح أو مفقود. |
| 404 | غير موجود (Not Found) | ملف العمل أو موقع التخزين المحدد غير موجود. |
| 500 | خطأ داخلي في الخادم (Internal Server Error) | فشل غير متوقع من جانب الخادم. |
مثال على استجابة خطأ (400)
{
"Code": 400,
"Message": "ملف بيانات XML مفقود أو معطوب."
}
عائلة مكتبات SDK السحابية
يُعد استخدام مكتبة SDK هو أفضل طريقة لتسريع عملية التطوير. فتتولى المكتبة معالجة التفاصيل من المستوى المنخفض، مما يسمح لك بالتركيز على مهام مشروعك. يُرجى زيارة مستودع GitHub للاطّلاع على قائمة كاملة بمكتبات Aspose.Cells Cloud SDK.
تُظهر أمثلة الكود التالية كيفية استدعاء خدمات Aspose.Cells عبر واجهات برمجة التطبيقات باستخدام مكتبات SDK مختلفة: