سياسة SOAPMessagevalidation

يتم الآن عرض مستندات Apigee Edge.
انتقِل إلى مستند Apigee X.
المعلومات

تقوم سياسة SOAPMessagePolicyation بما يلي:

  • التحقّق من صحة أي رسالة XML بالمقارنة مع مخططات XSD الخاصة بها
  • التحقق من صحة رسائل SOAP مقابل تعريف WSDL
  • تحديد التنسيق الصحيح لرسائل JSON وXML

على الرغم من أنّ اسم هذه السياسة في واجهة المستخدم هو "التحقّق من صحة رسائل SOAP"، تتحقّق السياسة من أخطاء أخرى غير رسائل SOAP. يُشار إلى هذه السياسة باسم "سياسة التحقّق من صحة الرسائل".

عنصر <MessageValidation>

تحدِّد هذه السياسة سياسة التحقّق من صحة الرسائل.

القيمة التلقائية راجِع علامة التبويب السياسة التلقائية أدناه.
هل هي مطلوبة؟ اختياري
النوع عنصر معقد
العنصر الرئيسي timing fixed in amara
العناصر الثانوية <DisplayName>
<Element>
<ResourceURL>
<SOAPMessage>
<Source>

البنية

يستخدم العنصر <MessageValidation> البنية التالية:

<MessageValidation
  continueOnError="[false|true]"
  enabled="[true|false]"
  name="policy_name"
>
    <!-- All MessageValidation child elements are optional -->
    <DisplayName>policy_display_name</DisplayName>
    <Element namespace="element_namespace">element_to_validate</Element>
    <SOAPMessage version="[ 1.1 | 1.2 | 1.1/1.2 ]"/>
    <Source>message_to_validate</Source>
    <ResourceURL>validation_WSDL_or_XSD</ResourceURL>

</MessageValidation>

السياسة التلقائية

يوضح المثال التالي الإعدادات التلقائية عند إضافة سياسة "التحقّق من صحة الرسائل" إلى المسار في واجهة مستخدم Edge:

<MessageValidation continueOnError="false" enabled="true" name="SOAP-Message-Validation-1">
  <DisplayName>SOAP Message Validation-1</DisplayName>
  <Properties/>
  <Element namespace="http://sample.com">sampleObject</Element>
  <SOAPMessage/>
  <Source>request</Source>
  <ResourceURL>wsdl://SOAP-Message-Validation-1.wsdl</ResourceURL>
</MessageValidation>

يتضمن هذا العنصر السمات التالية الشائعة لجميع السياسات:

السمة تلقائي مطلوب الوصف
name لا ينطبق مطلوب

الاسم الداخلي للسياسة. يمكن أن تحتوي قيمة السمة name على أحرف وأرقام ومسافات وواصلات وشرطات سفلية ونقاط. ويجب ألا تتجاوز هذه القيمة 255 حرفًا.

اختياريًا، يمكنك استخدام العنصر <DisplayName> لتصنيف السياسة في محرّر الخادم الوكيل لواجهة مستخدم الإدارة باستخدام اسم بلغة مختلفة.

continueOnError false إجراء اختياري يمكنك ضبطها على "خطأ" لعرض رسالة خطأ عند تعذّر تنفيذ إحدى السياسات. ويُعدّ هذا سلوكًا متوقعًا في معظم السياسات. يمكنك ضبط القيمة على "صحيح" للاستمرار في تنفيذ العملية حتى بعد تعذُّر تنفيذ سياسة.
enabled صحيح إجراء اختياري اضبط القيمة على "true" لفرض السياسة. اضبط هذه القيمة على "false" على "إيقاف" السياسة. لن يتم فرض السياسة حتى إذا ظلت مرتبطة بتدفق.
async   false منهي العمل به تم إيقاف هذه السمة نهائيًا.

أمثلة

توضِّح الأمثلة التالية بعض الطرق التي يمكنك من خلالها استخدام سياسة التحقّق من صحة الرسائل:

1: التحقق من XSD

يمكنك استخدام سياسة التحقق من صحة الرسائل للتحقّق من صحة حمولة طلب رسالة XML مقابل مخطّط XSD.

  1. أنشئ ملف مورد جديد لـ XSD. على سبيل المثال، "note-schema.xsd":
    <xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema">
      <xs:element name="note">
        <xs:complexType>
          <xs:sequence>
            <xs:element name="to" type="xs:string"/>
            <xs:element name="from" type="xs:string"/>
            <xs:element name="heading" type="xs:string"/>
            <xs:element name="body" type="xs:string"/>
          </xs:sequence>
        </xs:complexType>
      </xs:element>
    </xs:schema>
  2. أضِف سياسة التحقُّق من صحة رسائل SOAP إلى الخطوات المُسبَقة لنقطة نهاية الخادم الوكيل:
    1. حدِّد موقع ملف مورد XSD باستخدام العنصر <ResourceURL>. مثلاً:
      ...
        <ResourceURL>xsd://note-schema.xsd</ResourceURL>
      ...
    2. أزِل العنصرَين <SOAPMessage> و<Element> من تعريف السياسة.

    في هذه الحالة، يجب أن يظهر تعريف السياسة على النحو التالي:

    <MessageValidation continueOnError="false"
        enabled="true" name="validateXMLRequest">
      <DisplayName>My XML Validator</DisplayName>
      <Properties/>
      <Source>request</Source>
      <ResourceURL>xsd://note-schema.xsd</ResourceURL>
    </MessageValidation>
  3. أرسِل طلب POST إلى الخادم الوكيل لواجهة برمجة التطبيقات باستخدام ملف XML كحمولة الرسالة، على النحو الموضّح في المثال التالي:
    curl -v -X POST -H 'Content-Type: application/xml' http://my-test.apigee.net/v1/xsd-mock
      -d '<note>
      <to>Fred Rogers</to>
      <from>Nick Danger</from>
      <heading>Greetings from my neighborhood</heading>
      <body>Just writing to say hello.</body>
    </note>'

    يُرجى العِلم أنّه تم ضبط عنوان Content-type على "Application/xml".

    يمكنك أيضًا إنشاء ملف بيانات للحمولة والإشارة إليه باستخدام أمر يشبه ما يلي:

    curl -v -X POST -H 'Content-type: application/xml' http://my-test.apigee.net/v1/xsd-mock
      --data '@../examples/note-payload.xml'

من المفترَض أن يصلك ردّ HTTP 200. قد تتلقّى تفاصيل إضافية عن الطلب حسب نقطة النهاية المستهدَفة. على سبيل المثال، إذا كنت تستخدم http://httpbin.org/post كنقطة نهاية مستهدفة وحددت إخراج -v (مطوَّل)، يجب أن تكون الاستجابة على النحو التالي:

< HTTP/1.1 200 OK
< Date: Wed, 16 May 2018 21:24:54 GMT
< Content-Type: application/xml
< Content-Length: 431
< Connection: keep-alive
< Server: gunicorn/19.8.1
< Access-Control-Allow-Origin: *
< Access-Control-Allow-Credentials: true
< Via: 1.1 vegur
{
  "args":{},
  "data":"<note><to>fred</to><from>nick</from><heading>hello</heading>
    <body>Just writing to say hello.</body></note>",
  "files":{},
  "form":{},
  "headers": {
    "Accept":"*/*",
    "Connection":"close",
    "Content-Length":"106",
    "Content-Type":"application/xml",
    "Host":"httpbin.org",
    "User-Agent":"curl/7.58.0"
  },
  "json":null,
  "origin":"10.1.1.1, 104.154.179.1",
  "url":"http://httpbin.org/post"
}

للتأكّد من عمل عملية التحقق من XSD، جرِّب إدراج علامة أخرى في نص الطلب. مثال:

curl -v -X POST -H 'Content-Type: application/xml' http://my-test.apigee.net/v1/xsd-mock
  -d '<note>
  <to>Fred Rogers</to>
  <from>Nick Danger</from>
  <heading>Greetings from my neighborhood</heading>
  <body>Just writing to say hello.</body>
  <badTag>Not good</badTag>
</note>'

من المفترض أن تظهر لك رسالة خطأ في عملية التحقّق.

2: التحقق من صحة SOAP

يمكنك استخدام سياسة التحقق من صحة الرسائل للتحقق من صحة حمولة طلب رسالة SOAP مقابل WSDL.

  1. أنشئ ملف مورد جديد لـ WSDL. على سبيل المثال، "example-wsdl.wsdl":
  2. أضِف سياسة التحقُّق من صحة رسائل SOAP إلى التدفق المسبق لنقطة نهاية الخادم الوكيل:
    1. اضبط السمة version للعنصر <SOAPMessage> على إصدار بروتوكول SOAP الذي تريد التحقّق منه. على سبيل المثال، "1.1":
      ...
        <SOAPMessage version="1.1"/>
      ...
    2. اضبط قيمة العنصر <Element> على العنصر الذي تريد التحقّق من صحته:
      ...
        <Element namespace="https://example.com/gateway">getID</Element>
      ...

      تحدد السمة <Element> العنصر الثانوي الأول ضمن العنصر <Body> في غلاف طلب SOAP.

      اضبط السمة namespace على مساحة الاسم لهذه المؤسسة الفرعية.

    3. حدِّد موقع ملف مورد WSDL باستخدام العنصر <ResourceURL>. مثلاً:
      ...
        <ResourceURL>wsdl://example-wsdl.wsdl</ResourceURL>
      ...

    في هذه الحالة، يجب أن يظهر تعريف السياسة على النحو التالي:

    <MessageValidation continueOnError="false"
        enabled="true" name="validateSOAPRequest">
      <DisplayName>My SOAP Validator</DisplayName>
      <Properties/>
      <Source>request</Source>
      <SOAPMessage version="1.1"/>
      <Element namespace="https://example.com/gateway">getID</Element>
      <ResourceURL>wsdl://example-wsdl.wsdl</ResourceURL>
    </MessageValidation>
  3. أرسِل طلب POST إلى الخادم الوكيل لواجهة برمجة التطبيقات مع مغلف SOAP كحمولة الرسالة، على النحو الموضّح في المثال التالي:
    curl -v -X POST -H 'Content-Type: application/xml' http://my-test.apigee.net/v1/xsd-mock
      -d '<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"
        xmlns:prox="https://example.com/gateway" xmlns:typ="https://example.com/gateway/types">
      <soapenv:Header/>
      <soapenv:Body>
        <prox:getID>
          <typ:MyType>
            <typ:ID>42</typ:ID>
          </typ:MyType>
        </prox:getID>
      </soapenv:Body>
    </soapenv:Envelope>'

    يُرجى العِلم أنّه تم ضبط عنوان Content-type على "Application/xml".

    يمكنك أيضًا إنشاء ملف بيانات للحمولة والإشارة إليه باستخدام أمر يشبه ما يلي:

    curl -v -X POST -H 'Content-type: application/xml' http://my-test.apigee.net/v1/xsd-mock
      --data '@../examples/soap-payload.xml'

من المفترَض أن يصلك ردّ HTTP 200. قد تتلقّى تفاصيل إضافية عن الطلب حسب نقطة النهاية المستهدَفة. على سبيل المثال، إذا كنت تستخدم http://httpbin.org/post كنقطة نهاية مستهدفة، يجب أن تكون الاستجابة مشابهة لما يلي:

< HTTP/1.1 200 OK
< Date: Wed, 16 May 2018 21:24:54 GMT
< Content-Type: application/xml
< Content-Length: 431
< Connection: keep-alive
< Server: gunicorn/19.8.1
< Access-Control-Allow-Origin: *
< Access-Control-Allow-Credentials: true
< Via: 1.1 vegur
{
  "args":{},
  "data":"<note><to>fred</to><from>nick</from><heading>hello</heading>
    <body>Just writing to say hello.</body></note>",
  "files":{},
  "form":{},
  "headers": {
    "Accept":"*/*",
    "Connection":"close",
    "Content-Length":"106",
    "Content-Type":"application/xml",
    "Host":"httpbin.org",
    "User-Agent":"curl/7.58.0"
  },
  "json":null,
  "origin":"10.1.1.1, 104.154.179.1",
  "url":"http://httpbin.org/post"
}

3: تنسيق XML/JSON مكتوب بتنسيق جيد

يمكنك استخدام سياسة التحقق من صحة الرسائل للتأكد من صحة تنسيق حمولة رسالة JSON أو XML (وهي مختلفة عن طريقة التحقّق). تضمن السياسة توافق البنية والمحتوى مع المعايير المقبولة، بما في ذلك:

  • يوجد عنصر جذر واحد
  • عدم وجود أحرف غير قانونية في المحتوى
  • تضمين العناصر والعلامات بشكل صحيح
  • علامات البداية والنهاية متطابقة

للتحقّق من حُملة XML أو JSON بتنسيق سليم، يُرجى اتّباع الخطوات التالية:

  1. أضف سياسة التحقق من صحة رسائل SOAP إلى التدفق المسبق لنقطة نهاية الخادم الوكيل.
  2. أزِل العناصر <ResourceURL> و<SOAPMessage> و<Element> من تعريف السياسة.

    في هذه الحالة، يجب أن يظهر تعريف السياسة على النحو التالي:

    <MessageValidation async="false" continueOnError="false"
        enabled="true" name="validateXMLRequest">
      <DisplayName>My JSON Checker</DisplayName>
      <Properties/>
      <Source>request</Source>
    </MessageValidation>
  3. أرسِل طلب POST إلى الخادم الوكيل لواجهة برمجة التطبيقات، كما يوضِّح المثال التالي:
    curl -v -X POST -H 'Content-Type: application/json' http://my-test.apigee.net/v1/xsd-mock
      -d '{
    "note": {
      "to": "Fred Rogers",
      "from": "Nick Danger",
      "header": "Greetings from my neighborhood",
      "body": "Just writing to say hello."
      }
    }'

    يُرجى العلم أنّه تم ضبط عنوان Content-type على "Application/json".

    للتأكّد من صحة تنسيق ملف XML، استخدِم XML كحمولة الرسالة واضبط Content-type على "تطبيق/xml".

من المفترَض أن يصلك ردّ HTTP 200. عند إرسال حمولة رسالة لا تحتوي على تنسيق XML أو JSON بتنسيق سليم، من المفترَض أن تظهر لك رسالة الخطأ steps.messagevalidation.Failed.

مرجع عنصر فرعي

يصف هذا القسم العناصر الفرعية لـ <MessageValidation>.

<DisplayName>

يمكنك استخدامها بالإضافة إلى السمة name لتصنيف السياسة في محرِّر الخادم الوكيل لواجهة المستخدم الخاصة بالإدارة، وذلك باستخدام اسم مختلف يبدو طبيعيًا.

العنصر <DisplayName> شائع لجميع السياسات.

القيمة التلقائية timing fixed in amara
هل هي مطلوبة؟ اختياريّ. إذا حذفت <DisplayName>، سيتم استخدام قيمة السمة name للسياسة.
النوع سلسلة
العنصر الرئيسي <PolicyElement>
العناصر الثانوية لا ينطبق

يستخدم العنصر <DisplayName> البنية التالية:

البنية

<PolicyElement>
  <DisplayName>policy_display_name</DisplayName>
  ...
</PolicyElement>

مثال

<PolicyElement>
  <DisplayName>My Validation Policy</DisplayName>
</PolicyElement>

لا يتضمّن العنصر <DisplayName> أيّ سمات أو عناصر فرعية.

<Element>

لتحديد العنصر في الرسالة للتحقق من صحته. هذا هو العنصر الثانوي الأول ضمن العنصر <Body> في غلاف طلب SOAP.

القيمة التلقائية sampleObject
هل هي مطلوبة؟ اختياري
النوع سلسلة
العنصر الرئيسي <MessageValidation>
العناصر الثانوية لا ينطبق

يستخدم العنصر <Element> البنية التالية:

البنية

...
  <Element namespace="element_namespace">element_to_validate</Element>
...

مثال 1

يحدد المثال التالي عنصرًا واحدًا يجب التحقق منه:

...
<Element namespace="https://example.com/gateway">getID</Element>
...

مثال 2

يمكنك تحديد أكثر من عنصر واحد للتحقّق من صحته من خلال إضافة عناصر <Element> متعددة:

...
<Element namespace="https://example.com/gateway">getID</Element>
<Element namespace="https://example.com/gateway">getDetails</Element>
...

يحتوي العنصر <Element> على السمات التالية:

السمة تلقائي مطلوب؟ الوصف
namespace "http://sample.com" اختياري تحدد مساحة الاسم للعنصر الذي سيتم التحقق من صحته.

<ResourceURL>

لتحديد مخطط XSD أو تعريف WSDL المراد استخدامه للتحقّق من الرسالة المصدر.

القيمة التلقائية wsdl://display_name.wsdl
هل هي مطلوبة؟ اختياري
النوع سلسلة
العنصر الرئيسي <MessageValidation>
العناصر الثانوية لا ينطبق

يستخدم العنصر <ResourceURL> البنية التالية:

البنية

...
  <ResourceURL>[wsdl|xsd]://validation_WSDL_or_XSD</ResourceURL>
...

أمثلة

بالنسبة إلى ملف XML:

...
<ResourceURL>xsd://note-schema.xsd</ResourceURL>
...

بالنسبة إلى WSDL:

...
<ResourceURL>wsdl://example-wsdl.wsdl</ResourceURL>
...

يجب أن تشير قيمة <ResourceURL> إلى ملف مورد في الخادم الوكيل لواجهة برمجة التطبيقات. ولا يمكن أن يشير إلى موارد خارجية عبر HTTP أو HTTPS.

إذا لم تحدّد قيمة للسمة <ResourceURL>، يتم التحقّق من الرسالة للتأكّد من تنسيق JSON أو XML بشكل صحيح إذا كان عنوان Content-type هو "تطبيق/json" أو "تطبيق/xml"، على التوالي.

لا يتضمّن العنصر <ResourceURL> أيّ عناصر أو سمات فرعية

استخدام ملفات XSD للتحقق من الصحة

إذا كانت حمولة XML التي تم التحقق منها باستخدام سياسة التحقق من صحة الرسائل تشير إلى مخطط آخر، يجب أن تبدأ ملف XSD المضمّن بـ xsd في السمة schemaLocation.

يتألف المثال التالي من وحدات XSD متعددة:

<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema"
    elementFormDefault="qualified" attributeFormDefault="unqualified">
  <xs:include schemaLocation="xsd://note-schema.xsd"/>
  <xs:include schemaLocation="xsd://letter-schema.xsd"/>
  <xs:include schemaLocation="xsd://user-schema.xsd"/>
</xs:schema>

استخدام WSDL للتحقق من الصحة

يجب أن تحدِّد WSDL مخططًا واحدًا على الأقل. وإذا كانت السياسة لا تشير إلى مخطط واحد على الأقل، لن تنجح سياسة "التحقّق من صحة الرسائل".

الحد الأقصى لعمق الاستيراد في أي مخطط هو 10. إذا تجاوزت هذا العدد من عمليات الاستيراد المتداخلة، لن تنجح سياسة "التحقّق من صحة الرسائل".

<SOAPMessage>

تُحدِّد إصدار SOAP الذي تتحقق منه سياسة التحقُّق من الرسائل.

القيمة التلقائية timing fixed in amara
هل هي مطلوبة؟ اختياري
النوع timing fixed in amara
العنصر الرئيسي <MessageValidation>
العناصر الثانوية لا ينطبق

يستخدم العنصر <SOAPMessage> البنية التالية:

البنية

...
  <SOAPMessage version="[ 1.1 | 1.2 | 1.1/1.2 ]"/>
...

مثال

...
<SOAPMessage version="1.1"/>
...

يحتوي العنصر <SOAPMessage> على السمات التالية:

السمة تلقائي مطلوب؟ الوصف
version لا ينطبق اختياري يشير ذلك المصطلح إلى إصدار SOAP الذي تستخدمه هذه السياسة للتحقّق من صحة رسائل SOAP.

القيم الصالحة هي:

  • "1.1"
  • "1.2"
  • "1.1/1.2"

لمزيد من المعلومات، راجع من SOAP/1.1 إلى الإصدار 1.2 من SOAP/1.2 بعد 9 نقاط.

<Source>

تحدد الرسالة المصدر المراد التحقّق منها. وقيمة هذا العنصر هي اسم الرسالة التي تريد التحقّق من صحتها.

في حال عدم ضبط <Source>، يتم ضبط هذه السياسة تلقائيًا على "رسالة"، وتشير إلى رسالة الطلب الكاملة (ضمن مسار الطلب) أو رسالة الاستجابة (في مسار الاستجابة)، بما في ذلك أي حمولة. يمكنك أيضًا ضبطها بشكل صريح على "الطلب" أو "الاستجابة" للإشارة إلى الطلب أو الرد.

القيمة التلقائية طلب
هل هي مطلوبة؟ اختياري
النوع سلسلة
العنصر الرئيسي <MessageValidation>
العناصر الثانوية لا ينطبق

يستخدم العنصر <Source> البنية التالية:

البنية

...
  <Source>message_to_validate</Source>
...

مثال

...
<Source>request</Source>
...

بالإضافة إلى "الرسالة" و"الطلب" و "الاستجابة"، يمكنك ضبط القيمة <Source> على اسم أي رسالة في مسارك. في حال إجراء ذلك، عليك إنشاء رسالة مخصّصة بهذا الاسم في مسارك قبل تنفيذ هذه السياسة. وإلا، ستظهر رسالة خطأ.

إذا تعذّر مطابقة قيمة <Source> في تدفق الرسائل أو إذا تم تحويلها إلى نوع غير رسائل، سيحدث أحد الحالات التالية:

  • إذا كانت القيمة فارغة: يعرض Edge الخطأ steps.messagevalidation.SourceMessageNotAvailable.
  • إذا كان نوع غير الرسائل: يعرض Edge الخطأ steps.messagevalidation.NonMessageVariable.

لا يتضمّن العنصر <Source> أيّ سمات أو عناصر فرعية.

رموز الخطأ

تتّبع الأخطاء التي تعرضها سياسات Edge تنسيقًا ثابتًا كما هو موضَّح في مرجع رمز الخطأ.

This section describes the fault codes and error messages that are returned and fault variables that are set by Edge when this policy triggers an error. This information is important to know if you are developing fault rules to handle faults. To learn more, see What you need to know about policy errors and Handling faults.

Runtime errors

These errors can occur when the policy executes.

Fault code HTTP status Cause Fix
steps.messagevalidation.SourceMessageNotAvailable 500

This error occurs if a variable specified in the <Source> element of the policy is either:

  • out of scope (not available in the specific flow where the policy is being executed)
  • or
  • can't be resolved (is not defined)
steps.messagevalidation.NonMessageVariable 500

This error occurs if the <Source> element in the SOAPMessageValidation policy is set to a variable which is not of type message.

Message type variables represent entire HTTP requests and responses. The built-in Edge flow variables request, response, and message are of type message. To learn more about message variables, see the Variables reference.

steps.messagevalidation.Failed 500 This error occurs if the SOAPMessageValidation policy fails to validate the input message payload against the XSD schema or WSDL definition. It will also occur if there is malformed JSON or XML in the payload message.

Deployment errors

These errors can occur when you deploy a proxy containing this policy.

Error name Cause Fix
InvalidResourceType The <ResourceURL> element in the SOAPMessageValidation policy is set to a resource type not supported by the policy.
ResourceCompileFailed The resource script referenced in the <ResourceURL> element of the SOAPMessageValidation policy contains an error that prevents it from compiling.
RootElementNameUnspecified The <Element> element in the SOAPMessageValidation policy does not contain the root element's name.
InvalidRootElementName The <Element> element in the SOAPMessageValidation policy contains a root element name that does not adhere to XML rules for valid element naming.

المخططات

يتم تحديد كل نوع سياسة من خلال مخطّط XML (.xsd). تتوفّر مخطّطات السياسات كمرجع على GitHub.

مواضيع ذات صلة