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

عقدة admin-api

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

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

لوحة "Node Information" لعقدة admin-api: زر "Execute" والحقول "Name" و"Type" و"Query parameters" و"Request body".

1. Name​

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

مثال:

  • اسم العقدة: Create Payment Session

2. Type​

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

تختلف العمليات المتاحة باختلاف إصدار OneEntry، لذا راجع القائمة المنسدلة Type لمعرفة القائمة الدقيقة. تشمل العمليات:

  • الصفحات والمنتجات: مثل "Page object update" و "Searching for all product page objects with pagination and filters."، وجلب عدة منتجات حسب معرّفاتها؛
  • المستخدمون: بما في ذلك البحث عن المستخدمين؛
  • قيم السمات: بما في ذلك تحديث قيم السمات لعدة كيانات دفعة واحدة؛
  • الطلبات: تغيير حالة الطلب، وتطبيق مشغّل الحالة، والمرتجعات؛
  • جلسات الدفع: مثل "Payment session creation" و "Payment session update"؛
  • رصيد المكافآت: التعديل اليدوي لرصيد المستخدم؛
  • سجلات المجموعات: مثل "Retrieving all records belonging to a collection.".

بعد اختيار العملية، يُملأ الحقلان Query parameters و Request body بمثال من وصف API، ولا يبقى عليك إلا استبدال قيمه بقيمك.

3. Query parameters​

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

يستخدم الحقل صيغة Mustache، لذا يمكنك إدراج قيم من msg بكتابة {{المتغير}}.

مثال (لعملية "Retrieving all records belonging to a collection."):

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

4. Request body​

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

مثال (لعملية "Payment session creation"):

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

5. Input Schema​

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

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

مثال على عرض Input Schema:

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

6. زر Execute​

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

طريقة العمل:

  • ينفّذ الخادم التدفق من بدايته حتى هذه العقدة، ويمرّر البيانات عبر السلسلة وفق آخر حالة منشورة للتدفق.
  • إذا كانت إحدى عقد function في المسار لا تمرّر البيانات، لكن حقل Output Example (JSON) فيها معبّأ، تُستخدم هذه البيانات للاختبار.
  • عند نجاح الطلب، تُمرَّر استجابة API إلى العقدة التالية بوصفها مخططًا.
  • إذا أعاد الطلب خطأ، لا يُمرَّر أي مخطط إلى العقدة التالية.
معلومات

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

التأثير في المخطط:

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

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

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

  • عند فتح صفحة Integrations،
  • عند تحديث التدفق بزر Publish.

بذلك يبقى مخطط البيانات في العقدة التالية محدّثًا دائمًا دون تشغيل يدوي.

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

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

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

  • Type: Payment session creation
  • Request body: 
    {
      "orderId": {{orderEvent.order.id}},
      "type": "session"
    }

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

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

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

  • Type: Updating the status of an order belonging to the order storage object
  • Query parameters: 
    {
      "id": {{orderId}}
    }
  • Request body: 
    {
      "status": "{{newStatus}}"
    }

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

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

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

  • Type: Retrieving all records belonging to a collection.
  • Query parameters: 
    {
      "entityType": "delivery",
      "entityId": "{{payload.id}}",
      "langCode": "en_US",
      "offset": 0,
      "limit": 10
    }

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

آخر تحديث في