SQLQueries في SAP B1 Service Layer: تشغيل SQL وحل الأخطاء 701 و703 و402 و-2028

لماذا وُجدت SQLQueries

يعرض Service Layer كائنات الأعمال مثل Orders و Invoices. هذا مناسب لإنشاء المستندات، لكن التقارير تحتاج إلى عمليات ربط وتجميع عبر صفوف كثيرة. وسحب كل أسطر الفواتير عبر OData ثم تجميعها في تطبيقك عملية بطيئة.

تحل SQLQueries هذه المشكلة. تحفظ عبارة SELECT في SAP Business One مرة واحدة، ثم تشغّلها عبر HTTPS كلما احتجت إليها. نستخدمها في لوحة معلومات SAP B1 من كودينوفا لقراءة مبيعات عام كامل في استدعاءات قليلة.

الخطوة 1: احفظ الاستعلام

POST https://your-b1-server:50000/b1s/v1/SQLQueries
Content-Type: application/json

{
  "SqlCode": "KN_SALES_01",
  "SqlName": "Sales lines since a date",
  "SqlText": "SELECT T0.\"DocEntry\", T0.\"DocDate\", T0.\"CardCode\", T1.\"ItemCode\", T1.\"LineTotal\" FROM OINV T0 INNER JOIN INV1 T1 ON T0.\"DocEntry\" = T1.\"DocEntry\" WHERE T0.\"CANCELED\" = 'N' AND T0.\"DocDate\" >= :dfrom"
}

يعيد الاستدعاء الناجح 201 Created. ورمز SqlCode هو المفتاح الذي تستدعيه لاحقًا، فاجعله قصيرًا وثابتًا.

الخطوة 2: شغّله باستخدام List

POST https://your-b1-server:50000/b1s/v1/SQLQueries('KN_SALES_01')/List
Content-Type: application/json

{ "ParamList": "dfrom='2025-01-01'" }

تحتوي الاستجابة على مصفوفة value بصفوفك. وتأتي النتائج الكبيرة على صفحات: اتبع odata.nextLink ‏(v1) أو @odata.nextLink ‏(v2) حتى يختفي.

تُربط المعاملات المتعددة بعلامة &:

{ "ParamList": "dfrom='2025-01-01'&card='C0001'" }

الخطأ 701: صياغة SQL غير صالحة

تبدو الرسالة المعتادة هكذا:

[701] Invalid SQL syntax:, line 1, character position 280,
no viable alternative at input 'T0."DocDate" >= :from'

هذا الخطأ كلّفنا ظهيرة كاملة. كان SQL صحيحًا، لكن اسم المعامل كان :from. قرأه المحلل على أنه الكلمة المحجوزة FROM. وإعادة تسميته إلى :dfrom حلّت المشكلة فورًا.

أسباب أخرى للخطأ 701:

• استخدام صياغة SQL Server على شركة HANA، أو العكس. ضع المعرّفات بين علامتي اقتباس مزدوجتين والتزم بلهجة قاعدة البيانات.
• تعبيرات لا تقبلها قائمة السماح، مثل بعض استخدامات CASE أو استدعاءات الدوال. اختر الأعمدة الخام ونفّذ الحساب في تطبيقك.
• فاصلة منقوطة في النهاية أو تعليق داخل SqlText.

الخطأ -2028: لم يُعثر على سجلات مطابقة

تستدعي SQLQueries('KN_SALES_01')/List فتحصل على -2028. الاستعلام غير موجود في تلك الشركة. الأسباب الشائعة:

• استُعيدت قاعدة بيانات الشركة أو نُسخت دون استعلاماتك المحفوظة.
• حذف أحدهم الاستعلام، أو استخدم تطبيق آخر رمز SqlCode نفسه.
• سجّلت الدخول إلى شركة غير التي حفظت فيها الاستعلام.

التكامل المتين يعالج ذلك بنفسه: عند -2028، أرسل الاستعلام مجددًا بطلب POST، ثم أعد محاولة List مرة واحدة. وللخطأ -2028 والرموز الشائعة الأخرى خارج SQLQueries، راجع رموز أخطاء SAP B1 DI API. نحن نسمّي الرموز بتجزئة (Hash) قصيرة لنص SQL، فيحصل الاستعلام المعدّل على رمز جديد ولا يشغّل SQL قديمًا أبدًا.

قائمة السماح والصلاحيات

لا تشغّل SQLQueries أي SQL على أي جدول. بل تفحص العبارة مقابل قائمة سماح على خادم Service Layer. إذا لم يكن الجدول مسموحًا، يفشل الاستدعاء حتى لو كان SQL صحيحًا. اطلب من مسؤول SAP لديك مراجعة قائمة السماح قبل أن تصمم التقرير حول جدول محظور.

ويحتاج المستخدم أيضًا إلى صلاحيتين:

• Modify SQL Queries in Service Layer: لإنشاء الاستعلامات وتعديلها وحذفها.
• Service Layer SQL Query: لتنفيذ استعلام محدد.

أخطاء SQLQueries الأخرى: 703 و402 والدوال غير المدعومة

الخطأ 703: العمود غير موجود (اسم مستعار في ORDER BY)

استعلام يجمع RDR1."Quantity" باسم مستعار Q وينتهي بـ ORDER BY Q DESC يعيد:

703 Column 'Q' from table 'RDR1' not exist

أُبلغ عن ذلك على SAP B1 10.0 SP2402، وفي استعلامات أبسط أيضًا: تقرأ SQLQueries الاسم المستعار في ORDER BY على أنه عمود في الجدول. لم نجد حلًا أكّدته SAP، لذلك لا ترتّب حسب اسم مستعار. رتّب الصفوف في تطبيقك بدلًا من ذلك.

الخطأ 402: إعداد خاطئ في الملف b1s_sqltable.conf

الملف b1s_sqltable.conf هو قائمة السماح للجداول في SQLQueries، والخطأ 402 يعني أن الملف تالف. على Windows يوجد في %ProgramFiles%\SAP\SAP Business One ServerTools\ServiceLayer\Conf\، وعلى Linux في /usr/sap/SAPBusinessOne/ServiceLayer/conf/. الحل المذكور في SAP Community، استنادًا إلى SAP Note 3064927:

1. أعد تسمية b1s_sqltable.conf إلى b1s_sqltable_backup.conf.
2. افتح b1s_sqltable.template.conf واحفظه باسم b1s_sqltable.conf.
3. أعد تشغيل Service Layer.
4. أضف الجداول الإضافية التي تحتاجها إلى قائمة الجداول مرة أخرى.

التعبيرات والدوال غير المدعومة (701)

تقبل SQLQueries مجموعة محدودة من SQL. تذكر مدونة SAP التعريفية عمليات الربط و GROUP BY و ORDER BY و LIKE ودوال مثل sum و avg و max و min و left و right و distinct و count و lower و upper و isnull و ifnull. وما يقع خارج هذه المجموعة يفشل بالخطأ 701:

• UNION / UNION ALL: ‏Incorrect syntax near 'union'. شغّل استعلامين وادمج الصفوف في تطبيقك.
• العمليات الحسابية في قائمة SELECT: ‏mismatched input '-' expecting FROM. اختر الأعمدة الخام ونفّذ الحساب في تطبيقك.
• دوال أخرى: ‏Cannot support this function or expression: 'DAYS_BETWEEN'.

جداول UDT و UDO مدعومة بدءًا من 10.0 FP 2102. أما جداول السجل (Log) و SBO-COMMON فغير مدعومة.

الخطأ 502 (خطأ الوكيل) في List

الخطأ 502 من SQLQueries List لا يتعلق دائمًا بالحجم. في إحدى حالات SAP Community كان السبب نصًا سيريليًا (Cyrillic) في النتيجة، وهو موثّق في SAP Note 3029055 وأُصلح في حزمة ميزات لاحقة. وللنتائج الكبيرة، قسّمها دائمًا إلى صفحات باستخدام الترويسة Prefer: odata.maxpagesize، كما هو موضح في الترقيم الذي يحدده الخادم في دليل Service Layer.

قائمة التحقق

1. اجعل SqlText بسيطًا: أعمدة خام، وعمليات ربط، و WHERE، و GROUP BY.
2. لا تسمِّ أي معامل باسم كلمة SQL محجوزة أبدًا.
3. عالج -2028 بإعادة الإنشاء ثم إعادة المحاولة مرة واحدة.
4. لا UNION ولا عمليات حسابية ولا اسم مستعار في ORDER BY داخل SqlText ‏(701 / 703)؛ وعند الخطأ 402 أعد بناء b1s_sqltable.conf من القالب.
5. اتبع nextLink حتى تُقرأ كل الصفحات.
6. طابق الإجماليات مع SAP مرة واحدة. إجماليات الأسطر تتجاهل خصم المستند، وهو ما نشرحه في لماذا لا تتطابق تقارير مبيعات SAP B1.

تحتاج تقريرًا أو تكاملًا مبنيًا على SQLQueries؟ اطّلع على دليل Service Layer أو تواصل معنا.

المصادر

• SAP Learning: إدارة استعلامات SQL باستخدام واجهة Service Layer البرمجية
• SAP Community: ميزة SQL Query الجديدة في SAP Business One Service Layer
• SAP Community: خطأ الوكيل 502 عند الجلب عبر Service Layer SQL Query
• SAP Community: تعذّر استخدام اسم مستعار في ORDER BY ضمن SQLQueries في Service Layer (الخطأ 703)
• SAP Community: استعلامات SQL عبر Service Layer تعيد رمز الخطأ 402
• SAP Community: صياغة غير صحيحة قرب UNION ‏(SQLQueries)

خدمات ذات صلة

• تطوير SAP Business One
• بوابات الويب و B2B