العمل مع مرشحات الجداول المحورية – وثائق Aspose.Cells Cloud
تُضيف هذه الواجهة البرمجية REST مرشحًا جذريًا (Pivot Filter) إلى الجدول المحوري الموجود عند الفهرس المحدد.
المتطلبات المسبقة
قبل استدعاء هذه النقطة النهائية (endpoint)، يجب أن:
- تولّد رمز وصول OAuth/JWT صالحًا وتضمينه في رأس
Authorization. - تتأكد من أن ملف المصنف المستهدف محفوظ في مجلد سحابي يمكنك الوصول إليه (حدد
folderواختياريًاstorageName). - تستخدم إصدار 3.0 أو أحدث من واجهة برمجة تطبيقات Aspose.Cells Cloud.
واجهة PutWorksheetPivotTableFilter البرمجية
PUT https://api.aspose.cloud/v3.0/cells/{name}/worksheets/{sheetName}/pivottables/{pivotTableIndex}/PivotFilters
الأمان والمصادقة
تُقدّم واجهات برمجة تطبيقات Aspose.Cells Cloud بشكل آمن وتتطلب مصادقة مبنية على رمز JWT.
معلمات الطلب
| اسم المعلمة | النوع | الموقع | الوصف |
|---|---|---|---|
| name | نص (string) | المسار (path) | اسم ملف Excel. |
| sheetName | نص (string) | المسار (path) | الورقة التي تحتوي على الجدول المحوري. |
| pivotTableIndex | عدد صحيح (integer) | المسار (path) | فهرس الجدول المحوري (يبدأ من الصفر) الذي سيتم تطبيق المرشح عليه. |
| filter | كائن (object) | الجسم (body) | كائن JSON يُعرّف إعدادات المرشح. انظر جدول مخطط المرشح أدناه. |
| needReCalculate | منطقي (boolean) | الاستعلام (query) | عند القيمة true، يُجبر المصنف على إعادة الحساب بعد إضافة المرشح. القيمة الافتراضية: false. |
| folder | نص (string) | الاستعلام (query) | المجلد في التخزين السحابي حيث يوجد الملف. |
| storageName | نص (string) | الاستعلام (query) | اسم خدمة التخزين السحابي. |
مخطط المرشح (filter schema)
| الخاصية | النوع | الوصف |
|---|---|---|
| AutoFilter | كائن (object) | إعدادات المرشح التلقائي (AutoFilter)؛ يمكن تجاهلها إن لم تُستخدم. |
| EvaluationOrder | عدد صحيح (integer) | ترتيب تقييم المرشح. |
| FieldIndex | عدد صحيح (integer) | فهرس الحقل (يبدأ من الصفر) الذي يطبّق عليه المرشح. |
| FilterType | نص (string) | نوع المرشح (مثل: Value، Count، Label). |
| MeasureFldIndex | عدد صحيح (integer) | فهرس حقل القياس، إن وُجد. |
| MemberPropertyFieldIndex | عدد صحيح (integer) | فهرس حقل خاصية العضو، إن وُجد. |
| Name | نص (string) | اسم اختياري للمرشح. |
| Value1 | نص (string) | القيمة الأولى المستخدمة في المرشح (مثل: الحد الأدنى للنطاق). |
| Value2 | نص (string) | القيمة الثانية المستخدمة في المرشح (مثل: الحد الأقصى للنطاق). |
| CustomFilters | مصفوفة (array) | مجموعة كائنات المرشح المخصصة (كل منها يحتوي على FilterOperatorType، Value1، Value2). |
| DynamicFilter | كائن (object) | إعدادات المرشح الديناميكي (مثل: Top10، Bottom10). |
| IconFilter | كائن (object) | إعدادات المرشح القائم على الأيقونات. |
| Top10Filter | كائن (object) | إعدادات مرشح Top10/Bottom10. |
| ColorFilter | كائن (object) | إعدادات المرشح القائم على اللون. |
| Visibledropdown | منطقي (boolean) | يُشير إلى ظهور القائمة المنسدلة للمرشح. |
ملاحظة: جميع المعلمات المذكورة أعلاه إجبارية ما لم يُشار صراحةً إلى كونها اختيارية في وثائق الواجهة البرمجية.
أكواد الاستجابة
| الكود | المعنى |
|---|---|
| 200 | تمت إضافة المرشح بنجاح. |
| 400 | طلب غير صالح – معلمات غير صحيحة. |
| 401 | غير مصرّح – رمز مفقود أو غير صالح. |
| 404 | غير موجود – المصنف أو الجدول المحوري مفقود. |
| 500 | خطأ داخلي في الخادم. |
أفضل الممارسات
- حافظ على صغر حجم كائنات المرشح قدر الإمكان؛ فالتعريفات الكبيرة للمرشحات قد تزيد من زمن الاستجابة.
- تكون المكالمات مُتكررة (Idempotent) — إضافة نفس المرشح مرتين لن تُنتِج نسخًا مكررة.
- التزم بحدّ معدل طلبات الواجهة البرمجية: 100 طلب في الدقيقة لكل حساب.
ملاحظات إضافية:
- الحد الأقصى لحجم تعريف المرشح هو 1 ميغابايت؛ سيتم رفض الحمولات الأكبر بخطأ 400.
- عند استخدام
needReCalculate=true، قد يؤدي إعادة الحساب إلى زيادة زمن الاستجابة، خاصةً مع المصنفات الكبيرة.
يمكنك استكشاف تعريف OpenAPI الكامل هنا:
مواصفات OpenAPI
مثال على طلب cURL
عائلة SDK السحابية
استخدام SDK هو أسرع طريقة لتطوير تطبيقاتك ضد Aspose.Cells Cloud. فالمكتبات البرمجية تتعامل مع التفاصيل منخفضة المستوى، مما يتيح لك التركيز على منطق تطبيقك. راجع مستودع GitHub للحصول على قائمة كاملة بـ SDKs الخاصة بـ Aspose.Cells Cloud.
توضح الأمثلة التالية كيفية إجراء مكالمات لخدمات الويب Aspose.Cells باستخدام مكتبات SDK مختلفة.