من Postman أو OpenAPI إلى مستقبِل HTTP في SAP CPI

معظم واجهات REST API التي تربطها من SAP CPI تأتي مع ملف OpenAPI أو Swagger، أو مجموعة Postman، أو كليهما. وكل ما يحتاجه محوّل مستقبِل HTTP موجود فيها: الخادم، والمسار، والمعاملات، والترويسات، وشكل الجسم. والعمل هو نقل كل جزء إلى الحقل الصحيح دون أن يسقط حرف واحد.

يطابق هذا المقال عملية OpenAPI وطلب Postman مع مستقبِل HTTP خطوة بخطوة، ويسرد التفاصيل التي تُفشل الاستدعاء الأول في أغلب الأحيان.

ما يحتاجه مستقبِل HTTP

• Address: عنوان URL الكامل للعملية. ويمكن أن يحتوي على تعبيرات Simple، مثل ${property.orderId} لمعامل مسار.
• Query: سلسلة الاستعلام دون ?، مثل notify=true.
• Method: ‏GET أو POST أو PUT أو PATCH أو DELETE.
• Authentication: بلا مصادقة، أو Basic، أو Client Certificate، أو OAuth2 Client Credentials وغيرها، باستخدام بيانات اعتماد مخزّنة في المستأجر، ولا تُكتب أبدًا في القناة.
• Request Headers: أسماء ترويسات الرسالة التي تُرسل إلى الـ API، مفصولة بـ |.
• الجسم: أيًا كان جسم الرسالة عند وصولها إلى المحوّل، ويُبنى عادةً في Content Modifier أو في تحويل (mapping).

قراءة عملية OpenAPI أو Swagger

خذ عملية OpenAPI 3 هذه، التي تنشئ شحنة لطلب ما:

openapi: 3.0.3
servers:
  - url: https://api.example.com/v1
paths:
  /orders/{orderId}/shipments:
    post:
      parameters:
        - { name: orderId, in: path, required: true, schema: { type: string } }
        - { name: notify, in: query, schema: { type: boolean } }
        - { name: X-Request-Id, in: header, schema: { type: string } }
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                carrier: { type: string }
                trackingNumber: { type: string }

1. Address: اجمع عنوان URL للخادم مع المسار. وفي Swagger 2.0 يُقسَّم الخادم إلى schemes وhost وbasePath.
2. معاملات المسار مثل {orderId}: استبدل كلًّا منها بتعبير، مثل ${property.orderId}.
3. معاملات الاستعلام (in: query): انقلها إلى حقل Query.
4. معاملات الترويسة (in: header): اضبطها كترويسات رسالة في Content Modifier وأدرج أسماءها في Request Headers.
5. جسم الطلب: ابنِ JSON في Content Modifier وفق المخطط الموجود تحت requestBody.
6. مخططات الأمان (security schemes): أنشئ بيانات الاعتماد المطابقة في المستأجر واخترها تحت Authentication.

النتيجة: Content Modifier والقناة

لهذه العملية، يبدو Content Modifier الذي يسبق المحوّل وقناة مستقبِل HTTP هكذا:

Content Modifier
  Header   Content-Type   application/json
  Header   X-Request-Id   ${property.requestId}
  Body     {
             "carrier": "${property.carrier}",
             "trackingNumber": "${property.trackingNumber}"
           }

HTTP receiver
  Address           https://api.example.com/v1/orders/${property.orderId}/shipments
  Query             notify=true
  Method            POST
  Request Headers   Content-Type|X-Request-Id

يضبط Content Modifier الترويسة Content-Type على application/json، والترويسة X-Request-Id، وجسم JSON، بقيم مأخوذة من خصائص تبادل ضُبطت في وقت سابق من التدفق. ويسرد Request Headers بالضبط الترويستين اللتين يجب أن تستلمهما الـ API، فتبقى كل ترويسة أخرى داخل المستأجر.

انطلاقًا من طلب Postman

يحمل طلب Postman المعلومات نفسها في أماكن مختلفة:

• كثيرًا ما يبدأ عنوان URL بمتغير Postman مثل {{baseUrl}}. وفي SAP CPI تعني صيغة {{…}} نفسها معاملًا خارجيًا يُضبط عند النشر: موضع طبيعي لعنوان URL الأساسي، الذي يختلف بين الاختبار والإنتاج.
• متغيرات المسار (:orderId) ومعاملات الاستعلام تُطابَق مع حقلي Address وQuery كما سبق.
• يصبح تبويب Headers ترويسات في Content Modifier مع إدراج أسمائها في Request Headers.
• يصبح جسم JSON الخام جسم Content Modifier، مع استبدال كل قيمة اختبارية بتعبير.
• يخبرك تبويب Authorization بالمصادقة التي يجب ضبطها. لا تنسخ رمزًا (token) من Postman إلى الـ iFlow؛ بل خزّن بيانات الاعتماد في المستأجر.

تفاصيل تُفشل الاستدعاء الأول

• ضبط Request Headers على * يرسل كل ترويسات الرسالة إلى الـ API، بما فيها الداخلية. أدرج فقط الترويسات التي تتوقعها الـ API.
• ترويسة Content-Type مفقودة أو خاطئة: كثير من واجهات API ترفض جسم JSON دون application/json.
• يجب أن تكون القيم في عنوان URL آمنة للاستخدام فيه: فالمعرّف الذي يحتوي على مسافات أو شرطات مائلة يحتاج إلى ترميز قبل وضعه في العنوان.
• استجابات الخطأ: عند إيقاف Throw Exception on Failure يستمر التدفق ويحمل ${header.CamelHttpResponseCode} رمز الحالة، فيستطيع Router معالجة الأخطاء.
• أسماء الحقول في جسم JSON تميّز بين الأحرف الكبيرة والصغيرة في معظم واجهات API؛ انسخها من المخطط لا من الذاكرة.

تستدعي خدمة OData بدلًا من ذلك؟ اطّلع على مقال مستقبِل OData. وللتعبيرات المستخدمة في العنوان والجسم، اطّلع على تعبيرات Camel Simple في SAP CPI.

كيف يساعدك Kitegra

تتولى إضافة المتصفح Kitegra قراءة مواصفات الـ API عنك. أعطها ملف OpenAPI أو Swagger، بصيغة JSON أو YAML، أو مجموعة Postman، فتقترح في مصمم SAP Integration Suite عناوين URL والمسارات ومعاملات الاستعلام وترويسات الطلب وأمثلة لأجسام JSON من تلك المواصفات.

تبقى المواصفات في متصفحك: لا يخزّن Kitegra مواصفات API أبدًا. ولا تحفظ الإضافة محتوى أي iFlow ولا تنشره ولا تعدّله أبدًا، ولا يتغير المستأجر إلا عندما تنقر أحد أربعة إجراءات محددة بالاسم يمكن إيقافها.

لاستدعاء نقطة وصول HTTPS للـ iFlow الخاص بك بالطريقة نفسها، اطّلع على اختبار iFlow بمرسِل HTTPS باستخدام مفتاح خدمة.

بلا حساب تعمل الإضافة على 5 iFlows لكل وحدة. وتغطي خطة Free حتى 50، وخطة Starter حتى 100، وخطة Pro حتى 300. وفي خطط الفرق يحصل كل عضو على Pro، مع 300 iFlow لكل وحدة في خطة Startup Team، وبلا حد في خطتي Growth Team وScale Team. وطوال فترة إطلاق Kitegra، تتاح كل الأدوات لكل من سجّل الدخول، حتى على خطة Free. قارن بين الخطط.

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

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

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