Правило SOAPMessageValidation

Вы просматриваете документацию по Apigee Edge.
Перейдите к документации по Apigee X.
info

Правило SOAPMessageValidation выполняет следующие действия:

  • Проверяет XML-сообщения на соответствие схемам XSD.
  • Проверяет сообщения SOAP на соответствие определению WSDL.
  • Определяет правильность формата сообщений JSON и XML.

Хотя в интерфейсе это правило называется "Проверка сообщений SOAP", оно проверяет не только сообщения SOAP. В этом разделе правило называется "Правило проверки сообщений".

Элемент <MessageValidation>

Определяет правила проверки сообщений.

Значение по умолчанию См. вкладку Правила по умолчанию ниже.
Обязательно? Необязательно
Тип Сложный объект
Родительский элемент –
Дочерние элементы <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», чтобы возвращать ошибку при сбое политики. Это ожидаемое поведение для большинства политик. Установите значение «true», чтобы выполнение потока продолжалось даже после сбоя политики.
enabled истинный Необязательный Установите значение «true», чтобы применить политику. Установите значение «false», чтобы «отключить» политику. Политика не будет применяться, даже если она остается присоединенной к потоку.
async ЛОЖЬ Устаревший Этот атрибут устарел.

Примеры

В следующих примерах показаны некоторые способы использования политики проверки сообщений:

1: проверка XSD

Вы можете использовать правило Message Validation, чтобы проверить полезную нагрузку запроса 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 Message Validation в предварительный поток конечной точки прокси-сервера:
    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 на прокси-сервер API, используя 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

Вы можете использовать правило Message Validation, чтобы проверить полезную нагрузку запроса сообщения SOAP на соответствие WSDL.

  1. Создайте новый файл ресурсов WSDL. Например, example-wsdl.wsdl:
  2. Добавьте правило SOAP Message Validation в предварительный поток конечной точки прокси-сервера:
    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 к прокси-серверу API с конвертом 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

Правило Message Validation позволяет проверить, правильно ли сформирован полезный контент сообщения JSON или XML (это не то же самое, что проверка). Правила обеспечивают соответствие структуры и содержания принятым стандартам, в том числе:

  • Есть только один корневой элемент.
  • В контенте нет недопустимых символов.
  • Объекты и теги вложены правильно.
  • Начальный и конечный теги совпадают.

Чтобы проверить, правильно ли сформирована полезная нагрузка XML или JSON, выполните следующие действия:

  1. Добавьте правило SOAP Message Validation в предварительный поток конечной точки прокси-сервера.
  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> является общим для всех правил.

Значение по умолчанию –
Обязательно? Необязательное поле. Если вы не укажете <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> должно указывать на файл ресурса в прокси-сервере API. Он не может ссылаться на внешние ресурсы по протоколу HTTP или HTTPS.

Если вы не укажете значение для <ResourceURL>, сообщение будет проверено на соответствие формату JSON или XML, если заголовок Content-type имеет значение "application/json" или "application/xml" соответственно.

У элемента <ResourceURL> нет дочерних элементов или атрибутов.

Как использовать XSD для проверки

Если полезная нагрузка XML, которую вы проверяете с помощью правила Message Validation, ссылается на другую схему, вы должны добавить префикс 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, по которой правило проверки сообщений выполняет проверку.

Значение по умолчанию –
Обязательно? Необязательно
Тип –
Родительский элемент <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"

Дополнительную информацию можно найти в статье From SOAP/1.1 to SOAP Version 1.2 in 9 points.

<Source>

Определяет исходное сообщение, которое нужно проверить. Значение этого элемента – название сообщения, которое вы хотите проверить.

Если вы не зададите <Source>, по умолчанию будет использоваться значение "message", которое относится к полному сообщению запроса (в потоке запросов) или сообщению ответа (в потоке ответов), включая любую полезную нагрузку. Вы также можете явно задать значение request или response, чтобы указать на запрос или ответ.

Значение по умолчанию запрос
Обязательно? Необязательно
Тип Строка
Родительский элемент <MessageValidation>
Дочерние элементы Нет

Элемент <Source> использует следующий синтаксис:

Синтаксис

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

Пример

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

Помимо message, request и response, в качестве значения <Source> можно указать название любого сообщения в потоке. Если вы это сделаете, то перед выполнением этого правила вам необходимо создать настраиваемое сообщение с таким именем в вашем потоке. В противном случае вы получите сообщение об ошибке.

Если значение <Source> не может быть разрешено в потоке сообщений или разрешается в тип, отличный от сообщения, происходит одно из следующих событий:

  • Если значение равно null, Edge выдает ошибку steps.messagevalidation.SourceMessageNotAvailable.
  • Если тип не является сообщением, Edge выдает ошибку steps.messagevalidation.NonMessageVariable.

У элемента <Source> нет атрибутов или дочерних элементов.

Коды ошибок

Ошибки, возвращаемые правилами Edge, имеют единый формат, описанный в справочнике по кодам ошибок.

В этом разделе описаны коды ошибок и сообщения об ошибках, которые возвращаются, а также переменные ошибок, которые задаются Edge, когда это правило вызывает ошибку. Эта информация важна, если вы разрабатываете правила обработки ошибок. Подробнее о том, что нужно знать об ошибках в правилах и об обработке ошибок…

Ошибки времени выполнения

Эти ошибки могут возникать при выполнении правил.

Код ошибки Статус HTTP Причина Исправить
steps.messagevalidation.SourceMessageNotAvailable 500

Эта ошибка возникает, если переменная, указанная в элементе <Source> правил,

  • недоступно (недоступно в определенном процессе, в котором выполняется правило).
  • или
  • не может быть разрешен (не определен);
steps.messagevalidation.NonMessageVariable 500

Эта ошибка возникает, если для элемента <Source> в правиле SOAPMessageValidation задана переменная, тип которой не message.

Переменные типа сообщения представляют собой полные HTTP-запросы и ответы. Встроенные переменные потока Edge request, response и message имеют тип message. Подробнее о переменных в сообщениях…

steps.messagevalidation.Failed 500 Эта ошибка возникает, если правилу SOAPMessageValidation не удается проверить полезную нагрузку входного сообщения на соответствие схеме XSD или определению WSDL. Она также возникает, если в сообщении полезной нагрузки есть неверно сформированный код JSON или XML.

Ошибки развертывания

Эти ошибки могут возникать при развертывании прокси-сервера, содержащего это правило.

Название ошибки Причина Исправить
InvalidResourceType Элемент <ResourceURL> в правиле SOAPMessageValidation задан для типа ресурса, который не поддерживается правилом.
ResourceCompileFailed Скрипт ресурса, на который ссылается элемент <ResourceURL> правила SOAPMessageValidation, содержит ошибку, из-за которой его не удается скомпилировать.
RootElementNameUnspecified Элемент <Element> в правиле SOAPMessageValidation не содержит название корневого элемента.
InvalidRootElementName Элемент <Element> в правиле SOAPMessageValidation содержит название корневого элемента, которое не соответствует правилам XML для допустимых названий элементов.

Схемы

Каждый тип правил определяется схемой XML (.xsd). Схемы правил доступны на GitHub.

Статьи по теме