الحصول على بيانات الخلايا بناءً على النطاق المسماة – Aspose.Cells Cloud API

المتطلبات المسبقة

  • رمز وصول JWT صالح مع النطاق (scope) المناسب.
  • يجب تحميل ملف المصنف إلى مساحة التخزين في Aspose Cloud (أو إلى مجلد مُحدَّد).
  • تأكد من تزويده باسم مساحة التخزين المستهدفة إذا كنت تستخدم مساحة تخزين غير افتراضية.

تُعيد هذه الواجهة البرمجية REST قائمة خلايا ضمن النطاق المُعرَّف إما بواسطة نطاق مسمّى أو بواسطة مؤشّرات الصف والعمود.

يتيح هذا الإجراء للمطوّرين استرجاع قيم الخلايا التي تنتمي إلى نطاق مسمّى معيّن في ورقة عمل Excel برمجيًا. وبتقديم مُعرَّف namedRange أو المؤشّران الصريحان للصف والعمود، تُعيد الواجهة البرمجية قائمة مفصّلة بالخلايا، بما في ذلك عنوانها، ورقم الصف، ورقم العمود، والقيمة، ونوع البيانات، ومعلومات التنسيق. ويمكن استخدام الاستجابة لتشغيل تطبيقات مبنية على البيانات، وإنشاء تقارير، أو إجراء عمليات حسابية إضافية على الخادم. تدعم خدمة Aspose.Cells Cloud لغات برمجة متعددة عبر SDKs الخاصة بها، مما يضمن دمجًا سلسًا بغض النظر عن منصة التطوير. ويضمن استخدام HTTPS نقل البيانات بشكل آمن، وتوافق الواجهة البرمجية مبادئ REST، حيث تُعيد رموز حالة HTTP القياسية لحالات النجاح والأخطاء.

واجهة REST API

GET https://api.aspose.cloud/v3.0/cells/{name}/worksheets/{sheetName}/ranges/value

مُعاملات الطلب

اسم المُعامل النوع الموقع الوصف
name string path اسم ملف المصنف.
sheetName string path اسم ورقة العمل داخل المصنف.
namedRange string query النطاق المسماة المراد استرجاعه، مثال: A1:B2 أو range_name1.
firstRow integer query المؤشر المُعدّ من الصفر لصف النطاق الأول (يُستخدم عند عدم تزويد namedRange).
firstColumn integer query المؤشر المُعدّ من الصفر لعمود النطاق الأول (يُستخدم عند عدم تزويد namedRange).
rowCount integer query عدد الصفوف المراد تضمينها في النطاق.
columnCount integer query عدد الأعمدة المراد تضمينها في النطاق.
folder string query المجلد الذي يحتوي على المصنف.
storageName string query اسم مساحة التخزين السحابية التي يوجد فيها المصنف.

تُعرّف مواصفات OpenAPI واجهة برمجة تفاعلية مُتاحة عمومًا، وتسمح لك بإجراء تفاعلات REST مباشرة من متصفح الويب.

يمكنك استخدام أداة سطر الأوامر cURL لاستدعاء خدمات Aspose.Cells بسهولة. يُظهر المثال التالي كيفية طلب قيم الخلايا من نطاق مسمّى.

ملاحظة أمنية: استخدم HTTPS دائمًا عند استدعاء الواجهة البرمجية. لا تدعم الخدمة بروتوكول HTTP العادي؛ ويضمن استخدام HTTPS تشفير الطلب والامتثال لأفضل الممارسات الأمنية.

رموز حالة HTTP

الرمز المعنى الوصف
200 OK تم تطبيق المرشّح بنجاح؛ وتحتوي الاستجابة على تفاصيل العملية.
400 Bad Request مُعاملات مفقودة أو غير صالحة (مثل: نوع ملف غير مدعوم).
401 Unauthorized رمز JWT غير صالح أو مفقود.
413 Payload Too Large تجاوز حجم الملف المرفوع الحد المسموح به.
500 Internal Server Error خطأ غير متوقع في الخادم.

مثال على استجابة خطأ (400 Bad Request)

{
  "Code": 400,
  "Status": "Bad Request",
  "Message": "المُعامل 'namedRange' مفقود أو غير صالح."
}

نصيحة: تستخدم الواجهة البرمجية مؤشّرات تبدأ من الصفر لـ firstRow وfirstColumn. فمثالً، يُمثّل الصف الأول في ورقة العمل القيمة 0.

عائلة SDK السحابية

استخدام SDK هو الطريقة الأكثر كفاءة لتسريع عملية التطوير. وتُجرّد SDK التفاصيل منخفضة المستوى، مما يتيح لك التركيز على منطق الأعمال. راجع مستودع GitHub للحصول على قائمة كاملة بـ SDKs الخاصة بـ Aspose.Cells Cloud.

تُظهر أمثلة الكود التالية كيفية استدعاء خدمات Aspose.Cells عبر SDKs متنوعة:

الحصول على النطاقات المسماة في مصنف إكسل