خط مشی SOAPMessageValidation

شما در حال مشاهده اسناد Apigee Edge هستید.
به مستندات Apigee X بروید .
اطلاعات

خط مشی SOAPMessageValidation موارد زیر را انجام می دهد:

  • هر پیام XML را در برابر طرحواره های XSD آنها اعتبار سنجی می کند
  • پیام های SOAP را در برابر تعریف WSDL اعتبار سنجی می کند
  • به خوبی شکل گیری پیام های JSON و XML را تعیین می کند

در حالی که نام این خط‌مشی در رابط کاربری «تأیید اعتبار پیام SOAP» است، این خط‌مشی بیش از پیام‌های SOAP را تأیید می‌کند. این بخش به این خط‌مشی با عنوان «خط‌مشی اعتبارسنجی پیام» اشاره می‌کند.

عنصر <MessageValidation>

خط مشی اعتبارسنجی پیام را تعریف می کند.

مقدار پیش فرض به برگه سیاست پیش‌فرض در زیر مراجعه کنید
مورد نیاز؟ اختیاری
تایپ کنید شیء پیچیده
عنصر والد n/a
عناصر کودک <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>

This element has the following attributes that are common to all policies:

Attribute Default Required? Description
name N/A Required

The internal name of the policy. The value of the name attribute can contain letters, numbers, spaces, hyphens, underscores, and periods. This value cannot exceed 255 characters.

Optionally, use the <DisplayName> element to label the policy in the management UI proxy editor with a different, natural-language name.

continueOnError false Optional Set to "false" to return an error when a policy fails. This is expected behavior for most policies. Set to "true" to have flow execution continue even after a policy fails.
enabled true Optional Set to "true" to enforce the policy. Set to "false" to "turn off" the policy. The policy will not be enforced even if it remains attached to a flow.
async   false Deprecated This attribute is deprecated.

نمونه ها

مثال‌های زیر برخی از روش‌های استفاده از خط‌مشی اعتبارسنجی پیام را نشان می‌دهند:

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 خود به عنوان بار پیام به پروکسی API خود ارسال کنید:
    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" تنظیم شده است.

    همچنین می توانید یک فایل داده برای payload ایجاد کنید و با دستوری مشابه زیر به آن ارجاع دهید:

    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 به عنوان بار پیام به پروکسی API خود ارسال کنید:
    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" تنظیم شده است.

    همچنین می توانید یک فایل داده برای payload ایجاد کنید و با دستوری مشابه زیر به آن ارجاع دهید:

    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 به پروکسی API خود ارسال کنید:
    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 روی "application/xml" تنظیم کنید.

شما باید یک پاسخ HTTP 200 دریافت کنید. وقتی پیغامی ارسال می‌کنید که حاوی XML یا JSON مناسب نیست، باید یک خطای steps.messagevalidation.Failed دریافت کنید.

مرجع عنصر کودک

این بخش عناصر فرزند <MessageValidation> را توصیف می کند.

<DisplayName>

علاوه بر ویژگی name برای برچسب گذاری خط مشی در ویرایشگر پروکسی رابط کاربری مدیریت با نامی متفاوت و طبیعی تر، از آن استفاده کنید.

عنصر <DisplayName> در همه خط مشی ها مشترک است.

مقدار پیش فرض n/a
مورد نیاز؟ اختیاری. اگر <DisplayName> حذف کنید، از مقدار ویژگی name خط مشی استفاده می شود
تایپ کنید رشته
عنصر والد < PolicyElement >
عناصر کودک هیچ کدام

عنصر <DisplayName> از نحو زیر استفاده می کند:

نحو

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

مثال

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

عنصر <DisplayName> هیچ ویژگی یا عنصر فرزند ندارد.

<Element>

عنصری را در پیام برای اعتبار سنجی مشخص می کند. این اولین فرزند زیر عنصر <Body> در پاکت درخواست SOAP است.

مقدار پیش فرض نمونه شی
مورد نیاز؟ اختیاری
تایپ کنید رشته
عنصر والد <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> باید به یک فایل منبع در پروکسی API شما اشاره کند. نمی تواند به منابع خارجی از طریق HTTP یا HTTPS اشاره کند.

اگر مقداری را برای <ResourceURL> مشخص نکنید، اگر هدر Content-type به ترتیب "application/json" یا "application/xml" باشد، پیام از نظر 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 را تعریف می کند که خط مشی اعتبارسنجی پیام با آن اعتبارسنجی می کند.

مقدار پیش فرض n/a
مورد نیاز؟ اختیاری
تایپ کنید n/a
عنصر والد <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 تا 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 در دسترس هستند.

موضوعات مرتبط