نقل نطاق مسمّى باستخدام ورقة عمل Excel عبر واجهة Aspose.Cells Cloud API

يُعد نقل النطاق المسمّى مهمة شائعة عندما تحتاج إلى إعادة تنظيم البيانات برمجيًا. يشرح هذا القسم كيفية نقل نطاق مُعرّف إلى موقع جديد على نفس ورقة العمل باستخدام واجهة Aspose.Cells Cloud REST API.

تقوم هذه الواجهة البرمجية بنقل النطاق المحدّد إلى نطاق وجهة في ورقة عمل Excel.

واجهة REST API

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

المصادقة

تتطلب الواجهة رمز Bearer JWT يُحصل عليه عبر تدفق OAuth الخاص بـ Aspose Cloud. يجب تضمين الرمز في رأس Authorization:

Authorization: Bearer <jwt token>

ويجب أن يحتوي الرمز على النطاق Cells.

المتطلبات الأساسية

يجب أن يكون المصنف مخزنًا في مساحة التخزين الخاصة بـ Aspose Cloud.
قدم اسم التخزين (storageName) ومسار المجلد (folder) إن لم يكن الملف في الدليل الجذر.
استخدم أحدث إصدار من SDK الخاص بـ Aspose.Cells Cloud الذي يدعم إصدار الواجهة v3.0.

الأمان والمصادقة

تُعدّ واجهات Aspose.Cells Cloud آمنة وتحتاج إلى مصادقة تعتمد على رمز JWT.

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

الاسم	النوع	الموقع	الوصف
name	سلسلة نصية	المسار	اسم ملف المصنف
sheetName	سلسلة نصية	المسار	اسم ورقة العمل
destRow	عدد صحيح	الاستعلام	مؤشر الصف الابتدائي لنطاق الوجهة (يبدأ من 0)
destColumn	عدد صحيح	الاستعلام	مؤشر العمود الابتدائي لنطاق الوجهة (يبدأ من 0)
range	كائن	الجسم	تعريف النطاق المصدر المراد نقله
folder	سلسلة نصية	الاستعلام	مسار المجلد حيث يُخزّن المصنف
storageName	سلسلة نصية	الاستعلام	اسم مساحة تخزين Aspose Cloud

جسم الطلب

الحقل	النوع	الإلزام	الوصف
ColumnCount	عدد صحيح	لا	عدد الأعمدة في النطاق المصدر
ColumnWidth	عدد صحيح	لا	عرض كل عمود (بالنقاط)
FirstColumn	عدد صحيح	لا	المؤشر المُعدَّ من الصفر لأول عمود في النطاق المصدر
FirstRow	عدد صحيح	لا	المؤشر المُعدَّ من الصفر لأول صف في النطاق المصدر
Name	سلسلة نصية	لا	اسم النطاق (إن كان نطاقًا مسمّى)
RefersTo	سلسلة نصية	لا	مرجع بنمط A1 يُعرّف النطاق
RowCount	عدد صحيح	لا	عدد الصفوف في النطاق المصدر
RowHeight	عدد صحيح	لا	ارتفاع كل صف (بالنقاط)
Worksheet	سلسلة نصية	لا	ورقة العمل التي تحتوي على النطاق المصدر

سير العمل

ارفع المصنف إلى مساحة تخزين Aspose Cloud (إن لم يكن موجودًا مسبقًا).
ولّد رمز JWT باستخدام نقطة نهاية OAuth.
ابنِ حمولة JSON التي تصف النطاق المصدر.
استدعِ نقطة النهاية moveto باستخدام المعاملات المطلوبة (المسار، معاملات الاستعلام وجسم JSON).
تحقق من الاستجابة؛ فاستدعاء ناجح يُعيد حالة 200 OK.

مثال على طلب/استجابة

Request

curl -v "https://api.aspose.cloud/v3.0/cells/test.xlsx/worksheets/Sheet1/ranges/moveto?destRow=20&destColumn=20" \
-X POST \
-H "Content-Type: application/json" \
-H "Accept: application/json" \
-H "Authorization: Bearer <jwt token>" \
-d '{ 
  "ColumnCount": 7,
  "ColumnWidth": 19,
  "FirstColumn": 0,
  "FirstRow": 9,
  "Name": "MyRange",
  "RefersTo": "A10:G10",
  "RowCount": 1,
  "RowHeight": 15,
  "Worksheet": "Sheet1"
}'

Response

{
  "Code": 200,
  "Status": "OK"
}

عند حدوث خطأ، تتضمن الاستجابة حقلًا اختياريًا ErrorMessage يوفّر تفاصيل إضافية حول السبب.

رموز حالة HTTP

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

مخطّط الاستجابة

الحقل	النوع	الوصف
Code	عدد صحيح	رمز حالة مشابه لـ HTTP تعيده الواجهة (مثل 200)
Status	سلسلة نصية	وصف نصي للنتيجة (مثل “OK”)
ErrorMessage	سلسلة نصية (اختياري)	تفاصيل الخطأ المقروءة من قِبل الإنسان عند فشل الاستدعاء

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

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

توضّح أمثلة الكود التالية كيفية إجراء استدعاءات لخدمات الويب Aspose.Cells باستخدام SDKs مختلفة: