لقد تم تسليمك نقطة نهاية SOAP. ربما يكون محول عملات قديمًا لا يزال فريق الفوترة الخاص بك يعتمد عليه، أو خدمة ويب لإدارة الطلبات يديرها شريك على .NET. تحتاج إلى استدعائها، والتأكد من أنها تُرجع ما يَعِد به العقد، وإثبات أنها تظل صحيحة مع تغير الكود المحيط بها. أدوات REST لا تناسب تمامًا، لأن SOAP يتطلب غلاف XML كامل، وContent-Type محدد، وملف WSDL يصف كل عملية.
يتعامل Apidog مع طلبات SOAP وخدمات الويب جنبًا إلى جنب مع REST وGraphQL وgRPC، لذلك لا تحتاج إلى تطبيق منفصل للخدمة القديمة الوحيدة في مجموعتك. يرشدك هذا الدليل عبر المسارين الموثقين: إرسال طلب SOAP يدويًا، واستيراد ملف WSDL ليقوم Apidog ببناء البيئة ونقاط النهاية لك. إذا كنت تريد الصورة الأوسع للبروتوكولات أولاً، فإن مقارنتنا بين REST وGraphQL وgRPC وSOAP توضح مكانة كل منها. للتعريف الرسمي لهيكل الغلاف، تعد مواصفات W3C SOAP هي المصدر الموثوق.
ما هو SOAP، ولماذا يحتاج إلى معالجة مختلفة
يصف Apidog بروتوكول SOAP بأنه بروتوكول الوصول البسيط للكائنات (Simple Object Access Protocol)، وهو بروتوكول اتصال قائم على XML يتيح للمنصات ولغات البرمجة المتنوعة التواصل مع بعضها البعض. هذه الفكرة وحدها تفسر سبب استمرار العديد من الشركات في استخدامه. يمكن لعميل Java وخدمة .NET التحدث من خلال نفس العقد دون الاهتمام بالتفاصيل الداخلية لكل منهما.
ثلاث خصائص مهمة عند اختباره. يستخدم SOAP لغة XML لتنسيق الرسائل، لذا فإن كل طلب واستجابة عبارة عن مستند منظم، وليس مجرد كتلة JSON غير محددة. إذا كانت XML نفسها منطقة غير مألوفة، فإن مرجع XML من MDN هو مقدمة جيدة للقواعد النحوية التي ستقوم بقراءتها وكتابتها. ينتقل عادةً عبر HTTP أو HTTPS، على الرغم من أن البروتوكول يدعم بروتوكولات أخرى. ويتبع معايير W3C للاتصالات المنظمة والموثوقة، وهذا هو سبب صرامة شكل الرسالة وقواعد التحقق.
تلك الصرامة هي السبب وراء بقاء نقاط نهاية SOAP في الخدمة للتكامل عبر الأنظمة الأساسية، والجسور بين الأنظمة القديمة والحديثة، والمعاملات الآمنة باستخدام WS-Security للرسائل المشفرة والمصدقة. وهذا أيضًا هو السبب في أنك لا تستطيع مجرد إرسال طلب بأسلوب REST إليها. أنت بحاجة إلى العنوان الصحيح، وجسم XML ملفوف في غلاف SOAP، وطريقة لقراءة XML الذي يعود. إذا كنت تريد نظرة أعمق على كيفية حمل الغلاف وجسمه للبيانات، فراجع شرحنا لـ واجهات برمجة تطبيقات SOAP وXML.
قبل أن تبدأ
هناك شرط أساسي واحد يحكم كل ما يلي. لإرسال طلب SOAP أو WebService، يجب أن يكون Apidog بالإصدار 2.1.31 أو أحدث. الإصدارات الأقدم لا تدعمه. افتح Apidog، تحقق من إصدارك، وقم بالتحديث إذا كنت متأخرًا. كل شيء آخر في هذا الدليل يفترض أنك تستخدم الإصدار 2.1.31 أو أحدث.
إذا لم يكن لديك Apidog بعد، فقم بتنزيل Apidog واتبع الخطوات. جربه مجانًا، لا يلزم وجود بطاقة ائتمان.
سترغب أيضًا في الحصول على تفاصيل خدمتك المستهدفة: عنوان URL لنقطة النهاية، اسم العملية التي تريد استدعاءها، ومعاملاتها. إذا كان لديك ملف WSDL، فاحتفظ به بالقرب منك، لأن النصف الثاني من هذا الدليل يقوم باستيراده مباشرة.
المسار أ: إرسال طلب SOAP يدويًا
هذا هو المسار الذي تتبعه عندما يكون لديك نقطة نهاية وتعرف العملية التي تريد استدعاءها. هناك ثلاثة أشياء تقوم بتعيينها لا يحتاجها طلب REST، وتعيينها بشكل صحيح هو جوهر العمل كله.
الخطوة 1: تعيين رأس Content-Type يدويًا
طلبات SOAP لا تستنتج رؤوسها الخاصة. أنت تقوم بتعيين Content-Type بنفسك، وهناك قيمتان صالحتان:
text/xml; charset=utf-8application/soap+xml
أي منهما صحيح يعتمد على الخدمة. تتوقع نقاط نهاية SOAP 1.1 عادةً text/xml; charset=utf-8، بينما غالبًا ما تتطلب نقاط نهاية SOAP 1.2 application/soap+xml. إذا لم تكن متأكدًا، فتحقق من WSDL أو وثائق الخدمة، وإذا أعادت القيمة الأولى خطأً بخصوص نوع المحتوى، فقم بالتبديل إلى الأخرى. أضف الرأس في قسم Headers للطلب قبل الإرسال.
الخطوة 2: تعيين تنسيق الجسم إلى XML ولصق الغلاف
عيّن تنسيق جسم الطلب (Body format) إلى xml، ثم الصق غلاف SOAP. الغلاف هو مستند يحتوي على تعريفات للمساحات الاسمية (namespace declarations) وعنصر Body الذي يحمل العملية التي تستدعيها، بالإضافة إلى أي معلمات متداخلة بداخله.
إليك مثال عملي على خدمة عامة لتحويل الأرقام إلى كلمات، بنفس الشكل الذي يستخدمه Apidog في وثائقه. العملية هي NumberToWords وتأخذ معلمة واحدة، ubiNum:
<?xml version="1.0" encoding="utf-8"?>
<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:web="http://www.dataaccess.com/webservicesserver/">
<soap:Body>
<web:NumberToWords>
<web:ubiNum>1234</web:ubiNum>
</web:NumberToWords>
</soap:Body>
</soap:Envelope>
يجب أن يتطابق مساحة الاسم في العملية مع ما تتوقعه الخدمة، وهذا هو السبب في أنك تقرأه من WSDL بدلاً من التخمين. يغلف soap:Body الاستدعاء الفعلي؛ web:NumberToWords هي العملية؛ web:ubiNum هي المدخلات.
الخطوة 3: إرسال وقراءة استجابة XML
أرسل الطلب. تعود الاستجابة بصيغة XML، كغلاف SOAP يحتوي جسمه على عملية الاستجابة. بالنسبة للاستدعاء أعلاه، تحصل على NumberToWordsResponse مع النتيجة متداخلة بالداخل:
<?xml version="1.0" encoding="utf-8"?>
<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
<soap:Body>
<m:NumberToWordsResponse xmlns:m="http://www.dataaccess.com/webservicesserver/">
<m:NumberToWordsResult>one thousand two hundred and thirty four</m:NumberToWordsResult>
</m:NumberToWordsResponse>
</soap:Body>
</soap:Envelope>
تعكس الاستجابة الطلب: يكتسب اسم العملية لاحقة Response، وتهبط القيمة في عنصر النتيجة. هذا الانعكاس هو ما تؤكد عليه. أنت تؤكد أن الغلاف عاد، وأن عقدة NumberToWordsResponse موجودة، وأن النتيجة تتطابق مع ما توقعته. تحتوي وثائق خدمة الويب المخصصة لـ Apidog على webservice.apidog.io على المرجع الكامل للتكوين والمزيد من أغلفة العينة إذا كنت تريد مثالاً عمليًا ثانيًا.
تتبع حالة الاستخدام الواقعية نفس الخطوات الثلاث. استبدل NumberToWords بعملية ConvertCurrency على خدمة سعر صرف قديمة، ومرّر fromCurrency وtoCurrency وamount كعناصر متداخلة، واقرأ الرقم المحوّل من غلاف الاستجابة. أو استدعِ عملية GetOrderStatus على خدمة ويب للطلبات، ومرّر orderId، وتحقق من عقدة الحالة المعادة. الآليات لا تتغير أبدًا: رأس، جسم XML، إرسال، قراءة الغلاف.
المسار ب: استيراد ملف WSDL لتوليد نقاط النهاية
كتابة الأغلفة يدويًا أمر جيد لاستدعاء واحد. عندما تعرض خدمة ما عشرات العمليات، دع WSDL يقوم بالعمل. يصف ملف WSDL كل عملية، ومدخلاتها، وعنوان الخدمة، ويقرأ Apidog كل ذلك في استيراد واحد.
إليك مسار النقر الدقيق:
- انتقل إلى الإعدادات (Settings)، ثم استيراد البيانات (Import Data).
- حدد
WSDL. - حمّل ملف
.wsdlأو.xmlالخاص بك. - راجع معاينة نقاط نهاية API التي حللها Apidog من الملف.
- افتح علامة التبويب
Environmentsوتحقق من صحة عنوان الخدمة. - انقر على
Confirm(تأكيد). يتم إنشاء البيئة المستوردة تلقائيًا. - حدد البيئة المستوردة من الزاوية العلوية اليمنى.
- أرسل طلبًا. يتم تطبيق Base URL تلقائيًا من تلك البيئة.
هناك خطوتان في تلك القائمة يميل الناس إلى تخطيهما ثم يندمون.
تعد الخطوة 5 مهمة لأن عنوان الخدمة في WSDL هو نقطة النهاية التي ستصل إليها كل طلب مستورد. إذا كان يشير إلى مضيف مرحلي (staging host)، أو عنوان URL نائب لم يقم مؤلف WSDL بتحديثه مطلقًا، فستنتقل طلباتك إلى المكان الخطأ. تحقق منها في علامة التبويب Environments قبل النقر على Confirm، وليس بعد ذلك.
تعد الخطوة 7 مهمة لأن عنوان URL الأساسي (Base URL) موجود في تلك البيئة التي تم إنشاؤها تلقائيًا. إذا لم تحدد البيئة المستوردة من الزاوية العلوية اليمنى، فلن يكون لطلباتك عنوان أساسي وستفشل. حددها أولاً، ثم أرسل.
بمجرد الانتهاء من الاستيراد، تظهر كل عملية كنقطة نهاية يمكنك استدعاؤها دون كتابة الغلاف بنفسك، وتؤكد على استجابة XML تمامًا كما في المسار أ. إذا كنت تنقل مشروعًا كاملاً من أداة أخرى، فإن دليلنا حول استيراد مشاريع SOAP يغطي عملية الترحيل من البداية إلى النهاية.
لاحظ قيودًا واحدة صريحة: استيراد WSDL موثق لرفع ملفات .wsdl و.xml. استيراد WSDL عن طريق URL أو عن طريق لصق محتوياته غير موثق، لذا قم بتحميل الملف بدلاً من توقع حقل URL.
الانتقال من SoapUI
إذا كانت اختبارات SOAP الخاصة بك موجودة حاليًا في SoapUI، فلن تضطر إلى إعادة بنائها من صفحة بيضاء. قم بتصدير أو الاحتفاظ بملف WSDL الخاص بك، ثم استورده إلى Apidog باستخدام المسار ب، وستحصل على نفس العمليات كنقاط نهاية قابلة للاستدعاء داخل مساحة عمل تقوم أيضًا بالتصميم، والمحاكاة، والتوثيق. المكسب هو التوحيد: مشروع واحد يضم خدمة SOAP ونقاط نهاية REST وسيناريوهات الاختبار بدلاً من تشتيتها عبر أدوات منفصلة. مقارنتنا جنبًا إلى جنب بين Apidog وSoapUI تستعرض ما يتم نقله وأين تختلف سير العمل.
التأكيدات والاختلافات
استدعاء واحد ناجح يثبت أن نقطة النهاية تعمل. أما الاختبار فيثبت أنها صحيحة. بمجرد عودة طلب SOAP الخاص بك، أضف تأكيدات على غلاف الاستجابة: تأكد من وجود عقدة عملية الاستجابة المتوقعة، واستخرج عنصر النتيجة، وتحقق من قيمته مقابل ما يَعِد به العقد. لخدمة العملات، تؤكد أن المبلغ المحوّل هو رقم ضمن النطاق؛ لخدمة الطلبات، تؤكد أن الحالة هي إحدى القيم المسموح بها.
من هناك، تقوم ببناء سيناريو اختبار قابل للتكرار يربط الاستدعاءات، على سبيل المثال إنشاء طلب، ثم الاستعلام عن حالته، وتمرير القيم بين الخطوات. يوضح دليلنا حول كتابة سيناريو اختبار باستخدام Apidog كيفية ربط القيم المستخرجة في الطلبات اللاحقة. النمط غير مرتبط بالبروتوكول، لذا يمكن لسيناريو أن يمزج استدعاء SOAP مع نقاط نهاية REST المحيطة به.
بالنسبة لنقاط النهاية الآمنة، يستخدم SOAP عادةً WS-Security للرسائل المشفرة والمصدقة. يعد رأس الأمان هذا جزءًا من غلاف SOAP الذي ترسله، لذا أضف كتلة أمان wsse داخل رأس الغلاف جنبًا إلى جنب مع عمليتك. تظل آليات الإرسال كما هي: قم بتعيين Content-Type، ضع الغلاف الكامل بما في ذلك رأس الأمان في جسم XML، ثم أرسل.
أتمتة سير العمل باستخدام Apidog CLI
بمجرد حفظ طلبات SOAP أو الطلبات المستوردة من WSDL كسيناريوهات اختبار، يقوم Apidog CLI بتشغيلها من سطر الأوامر حتى تتمكن البنية التحتية (pipeline) من تشغيلها عند كل دفعة (push). قم بتثبيته باستخدام Node.js v16 أو أحدث، ثم قم بالمصادقة:
npm install -g apidog-cli
apidog login --with-token <YOUR_ACCESS_TOKEN>
قم بتشغيل سيناريو محفوظ بالمعرّف، مقابل البيئة التي أنشأها استيراد WSDL الخاص بك:
apidog run --access-token $APIDOG_ACCESS_TOKEN -t <scenario_id> -e <env_id> -r cli
هنا، -t هو معرّف سيناريو الاختبار، و -e هو معرّف البيئة، و -r هو المُبلغ (reporter) (cli، html، أو junit، مفصولة بفواصل لعدة قيم). تحذير واحد صريح: تؤكد الوثائق أن المشغل ينفذ سيناريوهات الاختبار ومجموعات الاختبار المحفوظة، لكنها لا تذكر ما إذا كانت السيناريوهات المبنية على خطوات SOAP تعمل دون واجهة رسومية، لذا تعامل مع CLI كمحرك لسيناريوهات HTTP للمشروع وللحفاظ على مزامنة نقاط النهاية المستوردة من WSDL في CI بدلاً من افتراض التنفيذ الخاص بـ SOAP. يتم تغطية ربطه بالبنية التحتية (pipeline) في دليل Apidog CLI CI/CD الخاص بنا.
الأسئلة الشائعة
ما هو Content-Type الذي يجب استخدامه لطلب SOAP؟ إما text/xml; charset=utf-8 أو application/soap+xml. يعتمد الصحيح منهما على الخدمة: تتوقع نقاط نهاية SOAP 1.1 عمومًا الأول، ونقاط نهاية SOAP 1.2 الثاني. قم بتعيينه يدويًا في رؤوس الطلب، وإذا تلقيت خطأ في نوع المحتوى (content-type fault)، فقم بالتبديل إلى القيمة الأخرى.
هل أحتاج إلى خطة مدفوعة لاختبار SOAP في Apidog؟ الشرط الموثق الوحيد هو أن يكون Apidog بالإصدار 2.1.31 أو أعلى. لم يتم ذكر أي قيود على المستويات أو الاستضافة الذاتية لدعم SOAP أو WSDL، لذا قم بالتحديث إلى إصدار حديث وستكون جاهزًا.
هل يمكنني استيراد WSDL من URL؟ يقبل استيراد WSDL الموثق تحميل ملفات .wsdl و.xml. استيرادها بواسطة URL أو عن طريق لصق نص WSDL غير موثق، لذا قم بتحميل الملف. بعد الاستيراد، يتم إنشاء البيئة تلقائيًا وتختارها من الزاوية العلوية اليمنى قبل الإرسال.
كيف يمكنني اختبار كل من واجهات برمجة تطبيقات SOAP وREST في نفس المشروع؟ يتعامل Apidog معهما كأنواع طلبات داخل مساحة عمل واحدة، لذا يمكن لمشروع واحد أن يحتوي على عمليات SOAP بجانب نقاط نهاية REST وحتى استدعاءات GraphQL. إذا كانت GraphQL أيضًا ضمن اهتماماتك، فإن دليلنا لاختبار واجهات برمجة تطبيقات GraphQL في Apidog يغطي هذا الجانب، ويمكن لسيناريو اختبار أن يربط الطلبات عبرها جميعًا.
طلباتي المستوردة من WSDL تصل إلى الخادم الخطأ. ماذا حدث؟ سببان شائعان. إما أن عنوان الخدمة في علامة التبويب Environments كان خاطئًا وقت الاستيراد وقمت بالنقر على `Confirm` (تأكيد) دون التحقق منه، أو أنك لم تحدد البيئة المستوردة من الزاوية العلوية اليمنى، وبالتالي لم يتم تطبيق أي Base URL (عنوان URL أساسي). أعد الاستيراد وتحقق من العنوان، ثم تأكد من أن البيئة الصحيحة نشطة قبل الإرسال.
خاتمة
اختبار SOAP لا يعني بالضرورة استخدام أداة قديمة منفصلة. في Apidog، يمكنك إما إرسال الغلاف يدويًا (تعيين Content-Type، وتعيين الجسم إلى xml، ولصق الغلاف، وقراءة استجابة XML) أو استيراد ملف WSDL والسماح لـ Apidog ببناء نقاط النهاية والبيئة لك. كلا المسارين يؤديان إلى نفس النتيجة: تحقق قابل للتكرار من أن خدمة الويب الخاصة بك لا تزال تلتزم بعقدها. قم بتنزيل Apidog بالإصدار 2.1.31 أو أعلى، واستورد ملف WSDL الخاص بك، وضع خدماتك القديمة تحت نفس الاختبارات التي تُجرى على بقية واجهات برمجة تطبيقاتك.