انتقل إلى المحتوى الرئيسي

عقد admin-api

عقد admin-api يوفر وصولاً مباشراً إلى واجهة برمجة التطبيقات الداخلية لـ OneEntry. من خلاله يمكن قراءة وتعديل الطلبات، الصفحات، المنتجات، المستخدمين، المجموعات وجلسات الدفع مباشرة من تدفق التكامل — دون الحاجة لكتابة طلبات HTTP يدوياً.

إعدادات عقد admin-api​

IMG2

1. الاسم​

حقل لتحديد اسم العقد.
يظهر الاسم في مساحة العمل ويساعد في التعرف بسهولة على العقد.
إذا ترك فارغاً، سيتم تسمية العقد بـ admin-api.

مثال:

  • اسم العقد: إنشاء جلسة دفع

2. النوع​

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

مجموعة العمليات تعتمد على إصدار OneEntry، لذا يرجى مراجعة القائمة الدقيقة في القائمة المنسدلة النوع. تشمل العمليات:

  • الصفحات والمنتجات — على سبيل المثال، "تحديث كائن الصفحة"، "البحث عن جميع كائنات صفحة المنتج مع الترقيم والفلاتر."، الحصول على عدة منتجات حسب المعرفات؛
  • المستخدمون — بما في ذلك البحث عن المستخدمين؛
  • قيم السمات — بما في ذلك تحديث قيم السمات لعدة كيانات في وقت واحد؛
  • الطلبات — تغيير حالة الطلب، تطبيق مشغل الحالة، المرتجعات؛
  • جلسات الدفع — على سبيل المثال، "إنشاء جلسة دفع" و "تحديث جلسة الدفع"؛
  • رصيد المكافآت — تعديل يدوي لرصيد المستخدم؛
  • سجلات المجموعات — على سبيل المثال، "استرجاع جميع السجلات التي تنتمي إلى مجموعة.".

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

3. معلمات الاستعلام​

معلمات الطلب. يأخذ العقد المسار وطريقة HTTP من العملية المختارة تلقائياً، ولا يمكن تعديلها في النموذج. يتم تحديد قيم معلمات المسار (مثل معرف السجل) في هذا الحقل مع معلمات طلب URL.

يستخدم الحقل بناء جملة Mustache — يمكن إدخال القيم من msg عبر {{المتغير}}.

مثال (لعملية "استرجاع جميع السجلات التي تنتمي إلى مجموعة."):

{
  "entityType": "orders",
  "entityId": "{{orderId}}",
  "langCode": "en_US",
  "offset": 0,
  "limit": 1,
  "marker": "delivery"
}

4. جسم الطلب​

جسم الطلب بتنسيق JSON. يظهر الحقل فقط للعمليات ذات الطرق POST، PUT و PATCH. يدعم Mustache لإدخال البيانات من msg.

مثال (لعملية "إنشاء جلسة دفع"):

{
  "orderId": {{orderId}},
  "type": "session"
}

5. مخطط الإدخال​

يظهر قسم مخطط الإدخال في إعدادات العقد ويعرض هيكل البيانات التي تأتي من العقد السابق في التدفق. يتم تقديم المخطط في شكل أزواج "مفتاح - نوع"، مع مراعاة تداخل الكائنات.

إذا كانت هناك حقول في المخطط في وصف واجهة برمجة التطبيقات، تظهر أوصاف نصية بجانبها. يتم التقاط هذه الأوصاف أيضاً بواسطة محرر الشيفرة كإشارات عند كتابة قوالب Mustache.

مثال على عرض مخطط الإدخال:

payload
  └── order
        ├── id           (integer)  — معرف الطلب
        ├── status       (string)   — الحالة الحالية
        └── totalPrice   (number)   — المبلغ الإجمالي

6. زر التنفيذ​

زر تنفيذ يسمح باستدعاء طلب واجهة برمجة التطبيقات مباشرة من نموذج تحرير العقد، دون الحاجة لتشغيل التدفق بالكامل.

كيف يعمل:

  • يقوم الخادم بتنفيذ كامل التدفق من البداية حتى هذا العقد، مع تمرير البيانات عبر السلسلة وفقاً لأحدث حالة منشورة للتدفق.
  • إذا كان هناك أي عقدة function في الطريق لا تمرر البيانات إلى الأمام، ولكن لديها حقل مثال الإخراج (JSON) ممتلئ، يتم استخدام هذه البيانات كاختبار.
  • في حالة استجابة ناجحة، يتم تمرير استجابة واجهة برمجة التطبيقات إلى العقدة التالية كهيكل.
  • إذا أعاد الطلب خطأ — لا يتم تمرير الهيكل إلى العقدة التالية.
معلومات

قبل استخدام زر التنفيذ، تأكد من أن التدفق منشور. يقوم الخادم بتنفيذ السلسلة وفقاً لحالة آخر publish.

التأثير على الهيكل:

تحتوي عقدة admin-api في الأصل على هيكل استجابة من وصف واجهة برمجة التطبيقات. عند الضغط على تنفيذ، يتم الكتابة فوق الهيكل باستجابة حقيقية من واجهة برمجة التطبيقات. في هذه الحالة، تبقى الحقول التي تتطابق مع وصف واجهة برمجة التطبيقات مع أوصافها النصية.

7. استدعاء تلقائي لطلبات القراءة فقط​

تتم استدعاء جميع العقد admin-api التي تنفذ طلبات القراءة فقط (GET) تلقائياً:

  • عند فتح صفحة التكاملات،
  • عند تحديث التدفق عبر زر النشر.

هذا يضمن دائماً وجود مخطط بيانات محدث في العقدة التالية دون الحاجة لتشغيل يدوي.

أمثلة الاستخدام​

مثال 1: إنشاء جلسة دفع​

إعدادات العقد:

  • النوع: إنشاء جلسة دفع
  • جسم الطلب: 
    {
      "orderId": {{orderEvent.order.id}},
      "type": "session"
    }

النتيجة:
ينشئ العقد جلسة دفع، باستخدام orderId من الرسالة الواردة، وينقل بيانات الجلسة الجديدة إلى العقدة التالية.

مثال 2: تحديث حالة الطلب​

إعدادات العقد:

  • النوع: تحديث حالة الطلب الذي ينتمي إلى كائن تخزين الطلبات
  • معلمات الاستعلام: 
    {
      "id": {{orderId}}
    }
  • جسم الطلب: 
    {
      "status": "{{newStatus}}"
    }

النتيجة:
يقوم العقد بتحديث حالة الطلب، باستخدام البيانات من الرسالة الواردة.

مثال 3: استرجاع سجلات المجموعة​

إعدادات العقد:

  • النوع: استرجاع جميع السجلات التي تنتمي إلى مجموعة.
  • معلمات الاستعلام: 
    {
      "entityType": "delivery",
      "entityId": "{{payload.id}}",
      "langCode": "en_US",
      "offset": 0,
      "limit": 10
    }

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