مستقبِل OData في SAP CPI: ‏$select و$filter و$expand و$orderby بلا أخطاء إملائية

يحوّل محوّل مستقبِل OData في SAP CPI قيمة Resource Path وسطرًا من خيارات الاستعلام إلى استدعاء لخدمة OData، مثل API في SAP S/4HANA. وخيارات الاستعلام هي التي تحدد الحقول والصفوف والكيانات المرتبطة التي تعود، ويكفي اسم خاصية واحد مكتوب خطأً لترفض الخدمة الاستدعاء.

يمرّ هذا المقال على $select و$filter و$expand و$orderby من خلال مثال، وعلى الفروق بين OData V2 وV4 التي يتعثر بها كثيرون، وعلى طريقة إبقاء الأسماء صحيحة.

أين توضع خيارات الاستعلام في مستقبِل OData

في تبويب Processing في المحوّل تختار العملية، ثم تضبط Resource Path، وهو مجموعة الكيانات (entity set) أو الكيان الذي تستدعيه، وQuery Options، وهي كل ما يأتي بعد ? في عنوان URL. ويستطيع معالج الاستعلام في المحوّل بناء الاثنين من بيانات وصف الخدمة (metadata)، ويخزّن هذه البيانات، أي ملف EDMX، في موارد الـ iFlow.

يمكن أن تحتوي خيارات الاستعلام على تعبيرات Simple، فتأتي القيم من الرسالة، مثل $filter=SoldToParty eq '${property.customerId}'. ويقرأ المثال أدناه أوامر البيع مع بنودها من API_SALES_ORDER_SRV، وهي خدمة OData V2:

Resource Path:  A_SalesOrder
Query Options:  $select=SalesOrder,SoldToParty,CreationDate,to_Item/SalesOrderItem,to_Item/Material
                &$expand=to_Item
                &$filter=SoldToParty eq '${property.customerId}' and CreationDate ge datetime'2026-01-01T00:00:00'
                &$orderby=CreationDate desc
                &$top=50

في المحوّل تكون خيارات الاستعلام سطرًا واحدًا؛ وقد قُسّمت هنا لتسهيل القراءة فقط.

الخيارات الأربعة، واحدًا تلو الآخر

يحدّ $top و$skip من النتيجة ويقسّمانها إلى صفحات. وفي OData V2 تُختار خاصية من كيان موسَّع بمسار، كما في to_Item/Material، ويجب أن تُدرج خاصية التنقّل أيضًا في $expand.

يستخدم $filter عوامله الخاصة: eq وne وgt وge وlt وle، وتُربط بـ and وor وnot. وتوضع القيم النصية بين علامتي اقتباس مفردتين، وتحتاج التواريخ إلى الصيغة الحرفية التي يتوقعها إصدار الخدمة.

OData V2 وV4 لا يُكتبان بالطريقة نفسها

يدعم محوّل OData الإصدارين، وكثير من واجهات SAP API متاح بالإصدارين. ونسخ استعلام من إصدار إلى الآخر مصدر شائع للأخطاء:

OData V2:  $inlinecount=allpages
           $filter=substringof('Smith',CustomerName)
           $filter=CreationDate ge datetime'2026-01-01T00:00:00'

OData V4:  $count=true
           $filter=contains(CustomerName,'Smith')
           $filter=CreatedAt ge 2026-01-01T00:00:00Z
           $expand=_Item($select=Product,Quantity)

• عدّ الصفوف: $inlinecount=allpages في V2، و$count=true في V4.
• البحث داخل النص: substringof('Smith',CustomerName) في V2، وcontains(CustomerName,'Smith') في V4. لاحظ أن ترتيب الوسائط معكوس.
• التواريخ: يكتب V2 القيمة datetime'2026-01-01T00:00:00'؛ ويكتبها V4 دون بادئة.
• الخصائص الموسَّعة: يختارها V2 بمسار؛ أما V4 فيضع الخيارات داخل expand، كما في $expand=_Item($select=Product,Quantity).

الأخطاء الإملائية التي تسبب HTTP 400

عندما يكون خيار الاستعلام خاطئًا، تردّ الخدمة عادةً بـ HTTP 400 وتذكر الجزء الذي لم تستطع قراءته. والأخطاء التي تقف وراء ذلك هي نفسها تقريبًا في كل مرة:

• حالة أحرف خاطئة: أسماء OData تميّز بين الأحرف الكبيرة والصغيرة، فـ soldToParty ليست SoldToParty.
• مجموعة كيانات في موضع خاصية التنقّل: $expand=A_SalesOrderItem بدلًا من $expand=to_Item.
• خاصية موجودة في كيان آخر، أو في إصدار آخر من الخدمة فقط.
• غياب علامات الاقتباس حول القيم النصية، أو إرسال صيغة تاريخ V2 إلى خدمة V4.
• مشكلة في الفواصل: تُربط الخيارات بـ &، ويبدأ اسم كل خيار بـ $.

وللتعبيرات مخاطرها الخاصة: إذا كان ${property.customerId} فارغًا، يصبح الفلتر SoldToParty eq '' ويُرجع بصمت صفر صفوف بدلًا من خطأ. ويتناول مقال تعبيرات Simple طريقة قراءة هذه القيم.

أبقِ الاستعلام متوافقًا مع الخدمة

• اعتبر ملف EDMX في موارد الـ iFlow المرجع الموثوق للأسماء، وحدّثه عندما تتغير الخدمة.
• اختر الحقول التي تربطها في التحويل (mapping) فقط؛ فالاستجابة الأصغر أسرع وأسهل قراءةً في التتبع.
• للقراءات الكبيرة، استخدم خيار المحوّل للمعالجة على صفحات بدلًا من استجابة واحدة ضخمة.
• اختبر الاستعلام مرة واحدة بالقيم نفسها التي ستضعها فيه رسالة حقيقية.

تستدعي REST API بدلًا من خدمة OData؟ يتناول مقال Postman وOpenAPI مستقبِل HTTP.

كيف يساعدك Kitegra

تقرأ إضافة المتصفح Kitegra ملف EDMX الموجود أصلًا في الـ iFlow لقناة مستقبِل OData. وفي المصمم تقترح Resource Path وأسماء الخصائص وخصائص التنقّل لـ $select و$filter و$expand و$orderby من ذلك الملف، فتختار الأسماء بدلًا من كتابتها.

وتنبّهك لوحة الفحص (lint) فيها إلى أسماء OData غير الموجودة في ملف EDMX، إلى جانب ${ غير المغلق والترويسات أو الخصائص التي لا يضبطها شيء. وإذا لم تظهر اقتراحات لقناة ما، فتحقق من أن ملف EDMX الخاص بها موجود في موارد الـ iFlow. ولا تحفظ الإضافة محتوى أي iFlow ولا تنشره ولا تعدّله أبدًا، ولا يتغير المستأجر إلا عندما تنقر أحد أربعة إجراءات محددة بالاسم يمكن إيقافها.

لتتحقق مما أجابت به خدمة OData فعلًا، تتبّع الرسالة خطوة بخطوة واقرأ الجسم بعد الاستدعاء.

بلا حساب تعمل الإضافة على 5 iFlows لكل وحدة. وتغطي خطة Free حتى 50، وخطة Starter حتى 100، وخطة Pro حتى 300، أما خطة Business فبلا حد. قارن بين الخطط.

جرّبها في الـ iFlow التالي

تعرّف على ما يفعله Kitegra في مصمم SAP Integration Suite، أو اطّلع عليه مع بقية وحدات Kitegra.

الأسئلة الشائعة