Политика 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

Политику проверки сообщений можно использовать для проверки содержимого 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 запрос на ваш 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

Политику проверки сообщений можно использовать для проверки содержимого запроса 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 в значение 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

Политика проверки сообщений позволяет подтвердить корректность структуры полезной нагрузки 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> является общим для всех политик.

Значение по умолчанию н/д
Необходимый? Необязательно. Если <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-данные, проверяемые с помощью политики проверки сообщений, ссылаются на другую схему, необходимо добавить префикс 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"

Для получения более подробной информации см. раздел «Переход от SOAP/1.1 к SOAP версии 1.2 в 9 пунктах» .

<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 для допустимого именования элементов.
,

В этом разделе описаны коды ошибок и сообщения об ошибках, которые возвращаются, а также переменные ошибок, которые устанавливаются 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.

Связанные темы