واجهة JSON-2 في أودو 20: دليل عملي للتكامل

يتجه أودو في واجهته البرمجية الخارجية نحو JSON-2.

وبالنسبة للمطورين الذين يصونون تطبيقات الجوال أو البرمجيات الوسيطة أو البوابات أو المتاجر الإلكترونية متعددة البائعين أو غيرها من البرمجيات المرتبطة بأودو، ينبغي تقييم JSON-2 بمعزل عن خادم MCP في أودو، وبمعزل عن وحدات التحكم (controllers) المخصصة لبروتوكول HTTP.

والفرق الجوهري بسيط:

• JSON-2: تكامل API حتمي بين التطبيق وأودو.
• MCP: عملاء ذكاء اصطناعي خارجيون يستخدمون أدوات خاضعة للضبط.
• وحدة التحكم المخصصة: سلوك HTTP خاص بالتطبيق تنفّذه وحدتك.

لا تتعامل معها على أنها قابلة للتبادل.

لماذا تهم JSON-2 في أودو 20

قدّم أودو JSON-2 بوصفها الاتجاه البديل لواجهتَي XML-RPC وJSON-RPC الخارجيتين المتقادمتين.

وتذكر الوثائق الرسمية الحالية أن خدمة db القديمة أُزيلت في أودو 20، بينما أصبحت خدمتا common وobject متقادمتين ومن المقرر حاليًا إزالتهما في أودو 22.

وهذا يعني أن أودو 20 توقيت مناسب لجرد التكاملات القديمة، حتى وإن كانت بعض الاستدعاءات القديمة لا تزال تعمل.

ابدأ بوثائق API الرسمية

قبل نسخ أي مثال طلب من هذا المقال، تحقّق من:

• البنية الحالية لنقاط النهاية؛
• ترويسات المصادقة؛
• طريقة اختيار قاعدة البيانات؛
• دوال النماذج المتاحة؛
• دلالات المعاملات (transactions)؛
• متطلبات الخطة أو الاشتراك.

فهذه التفاصيل قد تتطور.

المصادقة

استخدم طريقة المصادقة الموثّقة لواجهة JSON-2 الحالية.

واحفظ بيانات اعتماد API في مخزن أسرار مناسب أو في إعدادات البيئة.

ولا تفعل أبدًا ما يلي:

• إدراج المفاتيح في نظام إدارة الشيفرة المصدرية؛
• تضمين مفاتيح خادم ذات صلاحيات واسعة داخل ملف تطبيق الجوال؛
• تسجيل الأسرار في السجلات؛
• إعادة استخدام بيانات اعتماد المسؤول حين يكفي مستخدم تكامل مقيّد.

وبالنسبة لعملاء الجوال والويب، فكّر في طبقة خلفية أو برمجية وسيطة حين يكون كشف بيانات اعتماد أودو طويلة الأمد للعميل مباشرةً غير آمن.

صمّم مستخدم التكامل

أنشئ مستخدم أودو لا يملك إلا الصلاحيات التي يتطلبها التكامل.

فإذا كان التكامل يحتاج فقط إلى:

• قراءة المنتجات؛
• إنشاء العملاء المحتملين؛
• قراءة طلباته الخاصة؛

فلا تمنحه صلاحيات واسعة في المحاسبة أو الموارد البشرية أو النظام.

فحقوق الوصول وقواعد السجلات في أودو جزء من أمان واجهتك البرمجية.

المعاملات في JSON-2

من المبادئ المهمة في تصميم التكامل نطاقُ المعاملة.

لا تفترض أن سلسلة من طلبات HTTP المنفصلة تتصرف كعملية أعمال واحدة غير قابلة للتجزئة.

وإذا كان لا بد أن تكون العملية غير قابلة للتجزئة، فالأفضل استدعاء دالة نموذج مصممة لهذا الغرض تنفّذ عملية الأعمال كاملةً بعد التحقق منها داخل أودو، بدلًا من تنسيق عمليات كتابة كثيرة هشّة من جهة العميل.

مثال:

نمط تكامل سيئ:

create order
→ create lines
→ manually update totals
→ change state
→ create stock data

الأفضل:

call a validated Odoo business method
→ let Odoo enforce invariants internally

استخدم طبقة ORM وطبقة الأعمال بدلًا من إعادة بناء منطق أودو خارجيًا.

معالجة الأخطاء

ينبغي أن يميّز التكامل بين:

• فشل المصادقة؛
• رفض الوصول؛
• فشل التحقق أو مخالفة قواعد الأعمال؛
• سجل غير موجود؛
• طلب غير سليم الصياغة؛
• خطأ في الخادم؛
• انتهاء المهلة أو فشل الشبكة.

لا تُعِد محاولة كل خطأ تلقائيًا.

فخطأ التحقق لن يصبح صحيحًا لأن العميل أرسل الطلب عشر مرات أخرى.

وبالنسبة للعمليات القابلة لإعادة المحاولة، صمّم عدم التأثر بالتكرار (idempotency) حيثما أمكن.

تصميم تكاملات البحث والقراءة

عند استرجاع السجلات:

• اطلب الحقول المطلوبة فقط؛
• قسّم النتائج إلى صفحات وحدّد عددها عن قصد؛
• استخدم النطاقات (domains) بعناية؛
• تجنّب عمليات البحث الضخمة غير المحدودة؛
• راعِ قواعد الشركة والوصول؛
• تحقّق من التواريخ والمناطق الزمنية؛
• تجنّب أنماط طلبات N+1.

وفي مهام المزامنة، احفظ معرّفات ثابتة ونقاط تحقق بدلًا من تنزيل قاعدة البيانات كاملة مرارًا.

تصميم الإنشاء والتحديث

في عمليات الكتابة:

• تحقّق من صحة البيانات المرسلة قبل استدعاء أودو؛
• دع أودو يفرض قيود النماذج؛
• تجنّب تمرير الحقول كيفما اتفق من عملاء غير موثوقين؛
• قيّد الحقول القابلة للكتابة في البرمجية الوسيطة أو في دوال مصممة لهذا الغرض؛
• حافظ على سياق الشركة؛
• سجّل معرّفات الربط (correlation IDs) حيثما كان ذلك مفيدًا.

فنقطة النهاية العامة التي تقبل أي نموذج أو حقل أو قيمة مريحة أثناء التطوير وخطيرة في بيئة الإنتاج.

JSON-2 مقابل وحدة التحكم المخصصة

استخدم JSON-2 حين توفّر دوال النماذج والأعمال القياسية الواجهة التي تحتاجها.

واستخدم وحدة تحكم مخصصة حين ينبغي أن يكون العقد الخارجي مصممًا لغرض محدد، مثل:

• مستقبِل webhook؛
• نقطة نهاية عامة أو للجوال بمصادقة مخصصة؛
• عملية تجميعية؛
• بيانات مرسلة ذات بنية خاصة؛
• عقد خارجي متوافق مع الإصدارات السابقة.

فوحدة التحكم المخصصة تضيف مسؤولية صيانة، لذا لا تبنِ واحدة لمجرد تجنّب تعلّم الواجهة البرمجية القياسية.

JSON-2 مقابل MCP

عادةً ما تكون JSON-2 الخيار الأفضل حين يعرف المستدعي مسبقًا العملية التي يجب تنفيذها بالضبط.

أما MCP فمفيد حين يحتاج عميل ذكاء اصطناعي إلى تفسير لغة طبيعية والاختيار بين أدوات معتمدة.

فاستدعاء بوابة الدفع الراجع لا ينبغي أن يسأل نموذجًا لغويًا كبيرًا (LLM) عمّا يفعله.

أما مساعد المطور المطلوب منه تقصّي الفرص البيعية المهملة فقد يستفيد من MCP.

استراتيجية الترحيل من RPC القديمة

اجرد كل عميل قديم:

امنح الأولوية لكل ما يستخدم خدمة db التي أُزيلت.

ثم ابنِ اختبارات للعقود تتيح مقارنة التكاملات القديمة بالجديدة.

قائمة التحقق للاختبار

• المصادقة؛
• حقوق الوصول؛
• قواعد السجلات؛
• تعدد الشركات؛
• عمليات CRUD ودوال الأعمال؛
• أخطاء التحقق؛
• المناطق الزمنية؛
• البيانات الثنائية والمستندات؛
• التقسيم إلى صفحات؛
• إعادة المحاولة؛
• منع التكرار؛
• أعطال الشبكة؛
• التزامن؛
• الأداء؛
• التدقيق والتسجيل.

بنية طلب JSON-2

تضع وثائق أودو الحالية النموذج والدالة في عنوان URL:

POST /json/2/<model>/<method>

وتعتمد المصادقة على مفتاح API من نوع Bearer.

ويبدو نمط القراءة الموثّق على النحو التالي:

import requests

response = requests.post(
    "https://your-odoo.example.com/json/2/res.partner/read",
    headers={"Authorization": f"bearer {API_KEY}"},
    json={
        "ids": [1, 2, 3],
        "context": {"lang": "en_US"},
        "fields": ["name"],
        "load": None,
    },
)

data = response.json()

وحين يخدم نطاق واحد عدة قواعد بيانات، توضّح وثائق أودو أن الترويسة X-Odoo-Database قد تكون مطلوبة.

مستخدمو bot مخصصون

يوصي أودو باستخدام مستخدمي bot مخصصين للاستخدام الآلي الممتد.

ومن فوائد ذلك: الاقتصار على الحد الأدنى من الصلاحيات المطلوبة، ووضوح نسبة العمليات في سجلات الوصول، وإمكانية الإبطال المستقل، وخيار تعطيل تسجيل الدخول بكلمة المرور لمستخدم bot.

ويُفضَّل تخصيص مفتاح API منفصل لكل تكامل حيثما أمكن ذلك عمليًا.

دورة حياة مفتاح API

تدعم الوثائق الحالية النطاقات (scopes) وتواريخ انتهاء الصلاحية. وينبغي أن تسير عملية تدوير المفاتيح في بيئة الإنتاج على النحو التالي:

1. أنشئ مفتاحًا جديدًا؛
2. انشره في التكامل؛
3. تحقّق من أن حركة الطلبات تستخدمه؛
4. أبطل المفتاح السابق.

وسمِّ المفاتيح باسم الخدمة التي تستخدمها، حتى يتمكن المسؤول عن الاستجابة للحوادث من معرفة الجهة المالكة لكل مفتاح.

كيف تختلف JSON-2 عن واجهة object RPC القديمة

تحدد وثائق أودو الحالية التغييرات الرئيسية التالية:

• يوضع النموذج والدالة في عنوان URL؛
• تحل المصادقة بمفتاح API من نوع Bearer محل المصادقة باسم المستخدم وكلمة المرور؛
• تُمرَّر المعاملات بأسمائها في جسم طلب JSON؛
• لا يلزم تحديد قاعدة البيانات بشكل منفصل إلا في بعض عمليات النشر متعددة قواعد البيانات.

تعامل مع الترحيل على أنه إعادة هيكلة لعميل API، لا مجرد استبدال لسلاسل نصية.

صلاحيات الوصول لا تزال سارية

يؤكد أودو أن عمليات JSON-2 يجري التحقق منها وفق صلاحيات وصول المستخدم وقواعد السجلات وصلاحيات الوصول إلى الحقول.

وهذا يجعل تصميم مستخدم bot بأقل قدر من الصلاحيات جزءًا من بنية API نفسها، لا خطوة تحصين اختيارية.

ابنِ طبقة تكامل مستقرة

لا ينبغي للتكامل المتين أن ينثر استدعاءات أودو المباشرة في أرجاء التطبيق.

أنشئ طبقة عميل/خدمة صغيرة تتولى مسؤولية:

• المصادقة؛
• إعداد عنوان URL الأساسي وقاعدة البيانات؛
• بناء الطلبات؛
• سياسة المهلة؛
• توحيد صيغة الأخطاء؛
• إعادة المحاولة؛
• التسجيل وربط الطلبات بمعرّفات التتبّع؛
• التسلسل (serialization)؛
• التقسيم إلى صفحات.

وبعدها تستطيع شيفرة الأعمال استدعاء عمليات مثل:

odooCustomers.search(...)
odooOrders.create(...)
odooInvoices.getStatus(...)

بدلًا من تكرار منطق النقل في كل مكان.

تجنّب إعادة بناء منطق أعمال أودو من جهة العميل

إذا كان التكامل يحتاج إلى تأكيد عملية بيع، وإنشاء ما يترتب عليها من عمليات تسليم، وإحداث آثارها المحاسبية، فلا تُعِد إنتاج الخطوات الداخلية يدويًا عبر عمليات كتابة عشوائية.

وفضّل دوال الأعمال المدعومة في أودو، أو دالة مصممة لهذا الغرض على جهة الخادم تُبقي العملية داخل معاملة أعمال واحدة جرى التحقق منها.

فهذا يقلّل احتمال أن يترك عميل خارجي أودو في حالة لا يمكن لواجهة المستخدم العادية أن تُنشئها أبدًا.

عدم التأثر بالتكرار (idempotency) ومنع الازدواج

الأنظمة الخارجية تعيد المحاولة.

لذا صمّم تكاملات الكتابة بحيث لا يؤدي انتهاء المهلة إلى إنشاء نسخ مكررة من:

• العملاء المحتملين؛
• الطلبات؛
• المدفوعات؛
• الشحنات؛
• الفواتير.

ومن الأنماط الشائعة حفظ معرّف خارجي ثابت لا يتغير، والتحقق منه قبل إنشاء سجل جديد.

ويتوقف التنفيذ الدقيق على كائن الأعمال، لكن منع الازدواج ينبغي أن يُصمَّم قبل الوصول إلى الإنتاج.

اعتبارات الأداء

في التكاملات ذات الأحجام الكبيرة:

• اجمع الطلبات في دفعات منطقية حيثما تدعم الواجهة البرمجية أو دالة الأعمال ذلك؛
• تجنّب طلب حقول لا تستخدمها؛
• تجنّب استدعاءات N+1 لكل سجل على حدة؛
• قسّم النتائج إلى صفحات؛
• خزّن البيانات المرجعية الثابتة مؤقتًا بالطريقة المناسبة؛
• قِس زمن الاستجابة الفعلي؛
• راعِ سعة عمّال أودو (workers) والبنية التحتية.

فقد يُثقل عميلُ API سليمٌ تقنيًا نظامَ ERP إذا ظل يكرر عمليات بحث مكلفة.

قائمة التحقق من أمان التكامل

• مستخدم مخصص بأقل قدر من الصلاحيات؛
• مدير أسرار أو إعدادات البيئة؛
• لا مفاتيح API في الشيفرة المصدرية لتطبيقات الجوال أو الواجهة الأمامية؛
• TLS؛
• اختبارات لحقوق الوصول وقواعد السجلات؛
• اختبارات لسياق الشركة؛
• التحقق من صحة الحمولات؛
• ضوابط لمعدّل الطلبات ومنع إساءة الاستخدام حيثما ينطبق ذلك؛
• سجلات تُحجب منها البيانات الحساسة؛
• إجراء لتدوير بيانات الاعتماد.

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

هل JSON-2 هي واجهة API في أودو 20؟

إنها الاتجاه الحالي لدى أودو كبديل لخدمات XML-RPC وJSON-RPC الخارجية المتقادمة. ويمكن لأودو أيضًا إتاحة وحدات تحكم مخصصة وMCP لحالات استخدام مختلفة.

هل أُزيلت XML-RPC وJSON-RPC في أودو 20؟

ليس بالكامل. تذكر الوثائق الرسمية الحالية أن خدمة db أُزيلت في أودو 20، بينما من المقرر حاليًا إزالة خدمتَي common وobject المتقادمتين في أودو 22.

هل ينبغي أن أستخدم MCP بدلًا من JSON-2؟

استخدم MCP لسير عمل الذكاء الاصطناعي القائم على الأدوات الخارجية، واستخدم JSON-2 لتكامل التطبيقات الحتمي.

هل ينبغي أن يحتوي تطبيق الجوال على مفتاح API لأودو؟

احذر من تضمين أسرار طويلة الأمد ذات صلاحيات واسعة في تطبيقات تُوزَّع على المستخدمين. فقد تكون بنية تعتمد على طبقة خلفية أو برمجية وسيطة أكثر أمانًا بحسب التطبيق ونموذج التهديدات.

ما صيغة نقطة النهاية؟

/json/2/<model>/<method> وفق الوثائق الرسمية الحالية.

هل تحترم JSON-2 قواعد السجلات؟

نعم. تنطبق ضوابط الأمان القياسية في أودو على المستخدم الذي جرت مصادقته.

متى تكون X-Odoo-Database مطلوبة؟

في بعض عمليات النشر التي يستضيف فيها نطاق أو خادم واحد عدة قواعد بيانات، ولا يكفي التوجيه حسب اسم المضيف أو dbfilter لاختيار قاعدة بيانات واحدة بعينها.

الخلاصة

أهم مبدأ في الترحيل إلى JSON-2 ليس صيغة نقاط النهاية.

بل هو إبقاء ثوابت الأعمال داخل أودو، وتقليل الصلاحيات إلى أدناها، وتحديد عقود تكامل مستقرة، واختبار السلوك عند الفشل، لا الطلبات الناجحة فحسب.

هل تخطط لمشروع على أودو 20؟ تساعد Octivex Tech الشركات في ترقيات أودو، وترحيل الوحدات المخصصة، والتكاملات، وسير العمل المدعوم بالذكاء الاصطناعي. تصفّح خدماتنا في أودو أو تواصل مع فريقنا الهندسي لمناقشة بيئتك.