يتم الآن عرض مستندات 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 |
لا ينطبق | مطلوب |
الاسم الداخلي للسياسة. يمكن أن تحتوي قيمة السمة اختياريًا، يمكنك استخدام العنصر |
continueOnError |
false | إجراء اختياري | يمكنك ضبطها على "خطأ" لعرض رسالة خطأ عند تعذّر تنفيذ إحدى السياسات. ويُعدّ هذا سلوكًا متوقعًا في معظم السياسات. يمكنك ضبط القيمة على "صحيح" للاستمرار في تنفيذ العملية حتى بعد تعذُّر تنفيذ سياسة. |
enabled |
صحيح | إجراء اختياري | اضبط القيمة على "true" لفرض السياسة. اضبط هذه القيمة على "false" على "إيقاف" السياسة. لن يتم فرض السياسة حتى إذا ظلت مرتبطة بتدفق. |
async |
false | منهي العمل به | تم إيقاف هذه السمة نهائيًا. |
أمثلة
توضِّح الأمثلة التالية بعض الطرق التي يمكنك من خلالها استخدام سياسة التحقّق من صحة الرسائل:
1: التحقق من XSD
يمكنك استخدام سياسة التحقق من صحة الرسائل للتحقّق من صحة حمولة طلب رسالة XML مقابل مخطّط XSD.
- أنشئ ملف مورد جديد لـ 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>
- أضِف سياسة التحقُّق من صحة رسائل SOAP إلى الخطوات المُسبَقة لنقطة نهاية الخادم الوكيل:
- حدِّد موقع ملف مورد XSD باستخدام العنصر
<ResourceURL>
. مثلاً:... <ResourceURL>xsd://note-schema.xsd</ResourceURL> ...
- أزِل العنصرَين
<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>
- حدِّد موقع ملف مورد XSD باستخدام العنصر
- أرسِل طلب
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.
- أنشئ ملف مورد جديد لـ WSDL. على سبيل المثال، "example-wsdl.wsdl":
- أضِف سياسة التحقُّق من صحة رسائل SOAP إلى التدفق المسبق لنقطة نهاية الخادم الوكيل:
- اضبط السمة
version
للعنصر<SOAPMessage>
على إصدار بروتوكول SOAP الذي تريد التحقّق منه. على سبيل المثال، "1.1":... <SOAPMessage version="1.1"/> ...
- اضبط قيمة العنصر
<Element>
على العنصر الذي تريد التحقّق من صحته:... <Element namespace="https://example.com/gateway">getID</Element> ...
تحدد السمة
<Element>
العنصر الثانوي الأول ضمن العنصر<Body>
في غلاف طلب SOAP.اضبط السمة
namespace
على مساحة الاسم لهذه المؤسسة الفرعية. - حدِّد موقع ملف مورد 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>
- اضبط السمة
- أرسِل طلب
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 بتنسيق سليم، يُرجى اتّباع الخطوات التالية:
- أضف سياسة التحقق من صحة رسائل SOAP إلى التدفق المسبق لنقطة نهاية الخادم الوكيل.
- أزِل العناصر
<ResourceURL>
و<SOAPMessage>
و<Element>
من تعريف السياسة.في هذه الحالة، يجب أن يظهر تعريف السياسة على النحو التالي:
<MessageValidation async="false" continueOnError="false" enabled="true" name="validateXMLRequest"> <DisplayName>My JSON Checker</DisplayName> <Properties/> <Source>request</Source> </MessageValidation>
- أرسِل طلب
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.
القيم الصالحة هي:
|
لمزيد من المعلومات، راجع من 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 تنسيقًا ثابتًا كما هو موضَّح في مرجع رمز الخطأ.
يصف هذا القسم رموز الأخطاء ورسائل الخطأ التي يتم عرضها ومتغيرات الأخطاء التي تضبطها Edge عندما تؤدي هذه السياسة إلى ظهور خطأ. هذه المعلومات مهمة لمعرفة ما إذا كنت تعمل على تطوير قواعد للأخطاء للتعامل معها. لمزيد من المعلومات، يمكنك الاطّلاع على المعلومات التي يجب معرفتها عن الأخطاء المتعلقة بالسياسات وأخطاء المعالجة.
أخطاء في وقت التشغيل
يمكن أن تحدث هذه الأخطاء عند تنفيذ السياسة.
رمز الخطأ | رموز حالة HTTP | السبب | إصلاح |
---|---|---|---|
steps.messagevalidation.SourceMessageNotAvailable |
500 |
يحدث هذا الخطأ إذا كان أحد المتغيّرين المحدَّدين في العنصر
|
build |
steps.messagevalidation.NonMessageVariable |
500 |
يحدث هذا الخطأ إذا تم ضبط العنصر تمثل متغيرات نوع الرسالة طلبات واستجابات HTTP كاملة. وتكون متغيّرات تدفق Edge المدمَجة |
build |
steps.messagevalidation.Failed |
500 | يحدث هذا الخطأ إذا تعذّر على سياسة SOAPMessageValidation التحقق من حمولة رسالة الإدخال وفقًا لمخطّط XSD أو تعريف WSDL. وستظهر هذه البيانات أيضًا إذا كانت رسالة الحمولة مكتوبة بتنسيق JSON أو XML بشكلٍ غير صحيح. | build |
أخطاء النشر
يمكن أن تحدث هذه الأخطاء عند نشر خادم وكيل يحتوي على هذه السياسة.
اسم الخطأ | السبب | إصلاح |
---|---|---|
InvalidResourceType |
تم ضبط العنصر <ResourceURL> في سياسة SOAPMessageHealthation على نوع مورد غير متوافق مع السياسة.
|
build |
ResourceCompileFailed |
يحتوي النص البرمجي للمورد المشار إليه في العنصر <ResourceURL> ضمن السياسة SOAPMessageHealthation على خطأ يمنع تجميعه.
|
build |
RootElementNameUnspecified |
لا يحتوي العنصر <Element> المتوفّر في سياسة SOAPMessageHealthation على اسم العنصر الجذر. |
build |
InvalidRootElementName |
يحتوي العنصر <Element> في سياسة SOAPMessage بدء الاستخدام على اسم عنصر جذري
لا يتوافق مع قواعد XML لتسمية العناصر الصالحة. |
build |
المخططات
يتم تحديد كل نوع سياسة من خلال مخطّط XML (.xsd
). تتوفّر مخطّطات السياسات
كمرجع على GitHub.