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

    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 в предварительный поток конечной точки вашего прокси-сервера.
  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, имеют единый формат, описанный в справочнике кодов ошибок .

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.

Похожие темы