XML وSOAP

لماذا يهم

ينتشر SOAP في التكامل بين المؤسسات وفي الأنظمة المؤسسية طويلة العمر، مثل واجهات المصارف والدفع والتأمين والخدمات الحكومية والاتصالات، وكثيراً ما يعمل خلف واجهة حديثة. وقد يوقف عيبٌ فيه عملية أعمال كاملة، مثل تأكيد دفعة.

كما أن أعطال XML وSOAP تختلف عن أعطال JSON عبر REST. فعلامة & واحدة غير مُهرَّبة تجعل الرسالة كلها غير مقروءة، والعنصر في مساحة أسماء خاطئة مجهول وإن بدا اسمه صحيحاً، ويعيد SOAP 1.1 رمز HTTP 500 حتى للمدخلات الخاطئة. ومن يقرأ رموز الحالة وحدها يفوّت عيوباً ويختلق عيوباً غير موجودة.

أساسيات XML: سلامة البنية والصلاحية ومساحات الأسماء

العنصر (Element) وسم بداية ثم محتوى ثم وسم نهاية، مثل <total>249.90</total>، ويمكن كتابة العنصر الخالي من المحتوى بالشكل <item/>. والسمة (Attribute) زوج name="value" داخل وسم البداية، مثل currency="SAR" في الوثيقة أدناه. ولوثيقة XML عنصر جذري (Root) واحد بالضبط، وكل عنصر يُغلق ويتداخل تداخلاً صحيحاً، والأسماء حساسة لحالة الأحرف، فـ <orderId> و<OrderId> عنصران مختلفان. وقيم السمات تُكتب بين علامتي اقتباس، ولا يتكرر اسم السمة في العنصر الواحد، ولا معنى لترتيب السمات.

اتباع هذه القواعد يجعل الوثيقة سليمة البنية (Well-formed)؛ ويعدّ XML 1.0 أي مخالفة خطأً فادحاً (Fatal error)، فيرفض المحلل (Parser) الرسالة كلها بدلاً من إصلاحها كما تفعل المتصفحات مع HTML. والوثيقة الصالحة (Valid) تطابق مخططاً أيضاً (ويعرّف XML 1.0 ذلك لملفات DTD)؛ وتستخدم خدمات الويب XML Schema (XSD) لتحديد العناصر الإلزامية وترتيبها وأنواعها وقيمها المسموحة.

• تهريب الأحرف الخاصة (Escaping): لا يجوز أن يظهر < و& كما هما في النص؛ اكتب < و& (ويعرّف XML مسبقاً أيضاً > و" و'). ومقطع CDATA، أي <![CDATA[...]]>، يحمل نصاً دون تهريب.
• ترميز الأحرف (Encoding): يحدده التصريح الاختياري <?xml version="1.0" encoding="UTF-8"?>، والبايتات التي لا تطابقه تشوّه الأسماء العربية أو الهندية أو تؤدي إلى رفض الرسالة.
• مساحات الأسماء (Namespaces): xmlns:ord="urn:example:orders" يربط بادئة بعنوان URI. ويُعرَّف العنصر بالعنوان مع اسمه المحلي، فالبادئة لا تهم، والاسم الصحيح في مساحة أسماء خاطئة مجهول.

<?xml version="1.0" encoding="UTF-8"?>
<order id="ORD-1042" currency="SAR">
  <customer>Smith &amp; Sons</customer>
  <item sku="A-100" qty="2"/>
  <note><![CDATA[Leave at <b>reception</b>]]></note>
  <total>249.90</total>
</order>

جرّبها: مدقّق XML جرّبها: منسّق XML

مغلف SOAP وربطه بـ HTTP

رسالة SOAP وثيقة XML عنصرها الجذري Envelope. وتحمل الترويسة الاختيارية Header بيانات عن الرسالة مثل معرّف الطلب أو رمز الأمان (Security token)، ويحمل الجسم الإلزامي Body عنصر الطلب أو الاستجابة، أو عطلاً. وكتلة الترويسة الموسومة بـ mustUnderstand التي يعجز المستقبِل عن معالجتها يجب أن تُنتج عطل MustUnderstand.

تُرسَل الطلبات عادةً بطريقة POST إلى عنوان نقطة نهاية (Endpoint) واحد تشترك فيه كل العمليات. ويختلف إصدارا SOAP في مساحة أسماء المغلف وفي الربط بـ HTTP، لذا يفشل الطلب المبني لأحد الإصدارين عند إرساله إلى خدمة لا تدعم إلا الإصدار الآخر.

الجزء 1:1POST /services/orders HTTP/1.1
Host: api.example.com
الجزء 2:2Content-Type: text/xml; charset=utf-8
الجزء 3:3SOAPAction: "urn:example:orders/GetOrderStatus"

الجزء 4:4<?xml version="1.0" encoding="UTF-8"?>
الجزء 5:5<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/"
               الجزء 6:6xmlns:ord="urn:example:orders">
  الجزء 7:7<soap:Header>
    <ord:RequestId>7f3c-0091</ord:RequestId>
  </soap:Header>
  الجزء 8:8<soap:Body>
    الجزء 9:9<ord:GetOrderStatus>
      الجزء 10:10<ord:orderId>ORD-1042</ord:orderId>
    </ord:GetOrderStatus>
  </soap:Body>
</soap:Envelope>

• SOAP 1.1 (مذكرة W3C Note صدرت عام ⁦2000⁩): مساحة الأسماء http://schemas.xmlsoap.org/soap/envelope/، وContent-Type: text/xml، وترويسة SOAPAction إلزامية يحدد WSDL قيمتها لكل عملية.
• SOAP 1.2 (توصية W3C منذ ⁦2003⁩): مساحة الأسماء http://www.w3.org/2003/05/soap-envelope، وContent-Type: application/soap+xml، والإجراء (Action)، إن وُجد، معامل باسم action في هذه الترويسة.

POST /services/orders HTTP/1.1
Host: api.example.com
Content-Type: text/xml; charset=utf-8
SOAPAction: "urn:example:orders/GetOrderStatus"

<?xml version="1.0" encoding="UTF-8"?>
<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/"
               xmlns:ord="urn:example:orders">
  <soap:Header>
    <ord:RequestId>7f3c-0091</ord:RequestId>
  </soap:Header>
  <soap:Body>
    <ord:GetOrderStatus>
      <ord:orderId>ORD-1042</ord:orderId>
    </ord:GetOrderStatus>
  </soap:Body>
</soap:Envelope>

جرّبها: مختبِر طلبات SOAP

WSDL: عقد خدمة SOAP

وثيقة WSDL (Web Services Description Language) هي العقد المقروء آلياً لخدمة SOAP، ويُعتاد نشرها على عنوان نقطة النهاية مع إضافة ?wsdl. وما زال WSDL 1.1 (مذكرة من W3C صدرت عام ⁦2001⁩) واسع الاستخدام؛ ويغيّر WSDL 2.0 (عام ⁦2007⁩) اسم portType إلى interface واسم port إلى endpoint. ولـ WSDL 1.1 خمسة عناصر في المستوى الأعلى، مذكورة أدناه.

ومخطط XSD داخل types هو أدق جزء في أساس الاختبار (Test basis). ففي المخطط الوارد في نهاية هذا القسم، orderId إلزامي (القيمة الافتراضية لـ minOccurs هي ⁦1⁩) ويجب أن يطابق ORD- متبوعاً بـ⁦1⁩ إلى ⁦8⁩ أرقام، لأن أنماط XSD تطابق القيمة كاملة. وincludeItems اختياري لا يقبل إلا true أو false أو 1 أو 0؛ ويفرض xs:sequence الترتيب؛ وtargetNamespace هي مساحة الأسماء التي يجب أن تستخدمها عناصر الطلب.

• types: تعريفات XML Schema لعناصر الطلب والاستجابة والأعطال.
• message: البيانات التي ترسلها كل عملية أو تستقبلها.
• portType: العمليات بمدخلاتها ومخرجاتها وأعطالها المعلنة.
• binding: الربط، أي إصدار SOAP، ونمط document أو rpc، وقيمة soapAction لكل عملية.
• service: عنوان المنفذ (Port)، أي عنوان URL الذي ترسل إليه الطلبات.

<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema"
           targetNamespace="urn:example:orders"
           elementFormDefault="qualified">
  <xs:element name="GetOrderStatus">
    <xs:complexType>
      <xs:sequence>
        <xs:element name="orderId">
          <xs:simpleType>
            <xs:restriction base="xs:string">
              <xs:pattern value="ORD-[0-9]{1,8}"/>
            </xs:restriction>
          </xs:simpleType>
        </xs:element>
        <xs:element name="includeItems" type="xs:boolean" minOccurs="0"/>
      </xs:sequence>
    </xs:complexType>
  </xs:element>
</xs:schema>

أعطال SOAP: أخطاء ذات بنية محددة

الطلب الذي يتعذر تنفيذه يحصل على عنصر Fault داخل Body. وفي SOAP 1.1 يحتوي على faultcode وfaultstring، وfaultactor اختيارياً، وعنصر detail الذي يجب أن يوجد إذا تعذرت معالجة محتوى Body، ويحمل بيانات خاصة بالتطبيق مثل أعطال الأعمال المعلنة في WSDL. ويسمّيها SOAP 1.2 Code (فيه Value وSubcode اختياري) وReason وNode وRole وDetail، والإلزامي منها Code وReason فقط. تحقّق من رمز العطل أولاً:

• Client في 1.1 أو Sender في 1.2: الرسالة خاطئة، أي معطوبة البنية أو غير صالحة أو تحمل قيمة خاطئة، وستفشل مجدداً إذا أُعيد إرسالها دون تغيير.
• Server في 1.1 أو Receiver في 1.2: الرسالة سليمة لكن المعالجة فشلت، كأن تكون قاعدة البيانات متوقفة. وقد تنجح لاحقاً.
• VersionMismatch: مساحة أسماء مغلف غير مدعومة. MustUnderstand: لم تُفهم كتلة ترويسة إلزامية. ويضيف SOAP 1.2 الرمز DataEncodingUnknown.
• رمز حالة HTTP: يفرض SOAP 1.1 الرمز 500 لكل عطل، بما فيها أعطال Client؛ ويستخدم SOAP 1.2 الرمز 400 لأعطال Sender و500 لبقيتها. لذا فإن 500 بعد مدخلات خاطئة صحيح في SOAP 1.1؛ ورمز العطل هو الحَكَم.

HTTP/1.1 500 Internal Server Error
Content-Type: text/xml; charset=utf-8

<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
  <soap:Body>
    <soap:Fault>
      <faultcode>soap:Client</faultcode>
      <faultstring>orderId must match ORD- followed by 1 to 8 digits</faultstring>
      <detail>
        <ord:ValidationError xmlns:ord="urn:example:orders">
          <ord:field>orderId</ord:field>
          <ord:value>1042</ord:value>
        </ord:ValidationError>
      </detail>
    </soap:Fault>
  </soap:Body>
</soap:Envelope>

مثال تطبيقي: اختبار العملية GetOrderStatus

تعمل خدمة الطلبات بالإصدار SOAP 1.1 على بيئة اختبار يملكها الفريق. ويستخرج المختبِر الفحوص من WSDL ومخططه، لكل فحص نتيجة متوقعة، ويتأكد من سلامة بنية كل مغلف يكتبه يدوياً قبل إرساله (أداة «مدقّق XML» تفحص سلامة البنية، لا المطابقة لمخطط XSD).

ويتحقق المختبِر من الاستجابات بلغة XPath، وهي لغة استعلام لوثائق XML: فالتعبير //ord:status يختار كل عنصر status في مساحة الأسماء التي تربطها أداة الاختبار بالبادئة ord، أياً كانت البادئة التي تستخدمها الاستجابة نفسها. ولا يقارن المختبِر الاستجابة نصاً بنص أبداً.

• طلب صالح للرقم ORD-1042: رمز HTTP 200، وعنصر GetOrderStatusResponse في مساحة أسماء الخدمة صالح وفق XSD.
• طلب شراء غير موجود ORD-99999999: العطل الذي يعلنه WSDL، مثل OrderNotFound، لا 200 بجسم فارغ.
• رسالة معطوبة البنية، مثل </ord:orderID> لإغلاق <ord:orderId>: عطل Client، ولا صفحة HTML أبداً. ولا يحتوي أي faultstring على تتبّع مكدس (Stack trace) أو أسماء أصناف (Classes) أو SQL أو مسارات ملفات.
• رسالة غير صالحة: orderId محذوف، أو 1042 بلا البادئة، أو ORD- دون أي رقم أو متبوعاً بتسعة أرقام (خارج الحدين ⁦1⁩ و⁦8⁩ مباشرة)، أو includeItems بالقيمة yes، أو تبديل ترتيب العنصرين: عطل Client يسمّي الحقل. وقبول أيٍّ منها يعني أن الخدمة لا تتحقق من مدخلاتها؛ فاسأل هل هذا مقصود.
• المغلف: مغلف بمساحة أسماء SOAP 1.2، مرسَل مع text/xml، يحصل على VersionMismatch؛ وقيمة SOAPAction التي لا تطابق الجسم لا تؤدي أبداً إلى تنفيذ عملية أخرى.
• سطر <!DOCTYPE> قبل المغلف ينبغي أن يُرفض بعطل: فإصدارا SOAP كلاهما يمنعان تصريح نوع الوثيقة (Document type declaration) في الرسالة، والمحلل الذي يقبله قد يكون معرَّضاً لهجمات الكيانات الخارجية في XML (XXE). لا تُجرِ مثل هذه الفحوص إلا على أنظمة لديك إذن باختبارها.

جرّبها: مختبِر طلبات SOAP جرّبها: مدقّق XML

أسئلة شائعة

المراجع

• Extensible Markup Language (XML) 1.0 (Fifth Edition)W3C · 2008ما يجعل مستند XML سليم البنية: العناصر والسمات والكيانات وترميز المحارف والمقدمة.
• SOAP Version 1.2 Part 1: Messaging Framework (Second Edition)W3C · 2007إطار الرسائل في SOAP 1.2: مغلّف XML بترويسة اختيارية وجسم إلزامي، وعنصر الخطأ (Fault)، ونموذج المعالجة عبر الوسطاء.
• OWASP Cheat Sheet Series: Web Service SecurityOWASP Foundationتأمين خدمات الويب SOAP وXML: أمن النقل وسلامة الرسائل والتحقق من المخطط والهجمات الخاصة بـ XML.
• OWASP Cheat Sheet Series: XML External Entity PreventionOWASP Foundationلماذا يجب على محللات XML تعطيل الكيانات الخارجية وDTD، وكيف تُضبط المحللات الشائعة بأمان.