Проверка содержимого

  • Статья

ОБЛАСТЬ ПРИМЕНЕНИЯ: все уровни Управление API

Политика validate-content направлена на проверку размера или содержимого текста запроса или ответа на одну или несколько поддерживаемых схем.

В следующей таблице показаны форматы схемы и типы содержимого запроса или ответа, поддерживаемые политикой. Значения типов содержимого не учитывают регистр.

Формат Типы содержимого
JSON Примеры: application/json
application/hal+json
XML Пример: application/xml
Протокол SOAP Допустимые значения: application/soap+xml для API SOAP 1.2
text/xml для API SOAP 1.1

Примечание.

Максимальный размер схемы API, которую можно использовать этой политикой проверки, составляет 4 МБ. Если размер схемы превышает это ограничение, то политики проверки будут возвращать ошибки во время выполнения. Чтобы увеличить это ограничение, обратитесь в службу поддержки.

Какое содержимое проверяется

Политика проверяет следующее содержимое в запросе или ответе на схему:

  • Наличие всех обязательных свойств.
  • Присутствие или отсутствие дополнительных свойств, если в схеме задано поле additionalProperties. Может быть переопределен атрибутом allow-additional-properties .
  • Типы всех свойств. Например, если схема указывает свойство в виде целого числа, запрос (или ответ) должен включать целое число, а не другой тип, например строку.
  • Формат свойств, если он указан в схеме, например регулярное выражение (если указано ключевое слово pattern), minimum для целых чисел и т. д.

Совет

Примеры ограничений шаблона регулярного выражения, которые можно использовать в схемах, см. в репозитории регулярных выражений проверки OWASP.

Примечание.

Задайте элементы политики и дочерние элементы в порядке, указанном в правиле политики. Чтобы помочь вам настроить эту политику, портал предоставляет интерактивный редактор на основе форм. Узнайте, как устанавливать или изменять политики службы управления API.

Правило политики

<validate-content unspecified-content-type-action="ignore | prevent | detect" max-size="size in bytes" size-exceeded-action="ignore | prevent | detect" errors-variable-name="variable name">
    <content-type-map any-content-type-value="content type string" missing-content-type-value="content type string">
        <type from | when="content type string" to="content type string" />
    </content-type-map>
    <content type="content type string" validate-as="json | xml | soap" schema-id="schema id" schema-ref="#/local/reference/path" action="ignore | prevent | detect" allow-additional-properties="true | false" />
</validate-content>

Атрибуты

Атрибут Description Обязательное поле По умолчанию.
unspecified-content-type-action Действие, выполняемое для запросов или ответов с типом содержимого, который не указан в схеме API. Допустимы выражения политики. Да Н/П
max-size Максимальная длина текста запроса или ответа в байтах, проверенная на соответствие заголовку Content-Length. Если текст запроса или текст ответа сжат, это значение представляет собой длину в распакованном виде. Максимально допустимое значение: 102 400 байт (100 КБ). (Обратитесь в службу поддержки , если необходимо увеличить это ограничение.) Допустимы выражения политики. Да Н/П
size-exceeded-action Действие, выполняемое для запросов или ответов, длина текста которых превышает значение, указанное в max-size. Допустимы выражения политики. Да Н/П
errors-variable-name Имя переменной в context.Variables, где регистрируются ошибки проверки. Выражения политики не допускаются. No Н/П

Элементы

Имя Описание Обязательное поле
карта типа контента Добавьте этот элемент для сопоставления типа контента входящего запроса или ответа с другим типом контента, используемым для активации проверки. No
content Добавьте один или несколько этих элементов, чтобы проверить тип контента в запросе или ответе, или сопоставленный тип контента и выполнить указанное действие. No

Атрибуты карты типа контента

Атрибут Description Обязательное поле По умолчанию.
any-content-type-value Тип контента, используемый для проверки текста запроса или ответа независимо от типа входящего контента. Выражения политики не допускаются. No Н/П
missing-content-type-value Тип контента, используемый для проверки текста запроса или ответа при отсутствующем или пустом типе входящего контента. Выражения политики не допускаются. No Н/П

элементы content-type-map-elements

Имя Описание Обязательное поле
type Добавьте один или несколько из этих элементов для сопоставления входящего типа контента с типом контента, используемым для проверки текста запроса или ответа. Используйте from для указания известного типа входящего контента или использования when с выражением политики для указания любого входящего типа контента, соответствующего условию. Переопределяет сопоставление в any-content-type-value и missing-content-type-value, если указано. No

атрибуты содержимого

Атрибут Description Обязательное поле По умолчанию.
type Тип контента для выполнения проверки текста, проверяется по заголовку типа контента или значению, сопоставленному в content-type-mapping, если указано. Если значение отсутствует, оно применяется к каждому типу содержимого, указанному в схеме API.

Чтобы проверить запросы и ответы SOAP (для атрибута validate-asзадано значение soap), задайте для type значение application/soap+xml в случае API SOAP 1.2 или text/xml в случае API SOAP 1.1.		 No Н/П
validate-as Подсистема проверки, используемая для проверки текста запроса или ответа с соответствующим type. Поддерживаемые значения: json, xml, soap.

При указании soap XML из запроса или ответа извлекается из конверта SOAP и проверяется на соответствие схеме XML.		 Да Н/П
schema-id Имя существующей схемы, добавленной в экземпляр службы "Управление API" для проверки содержимого. Если значение не указано, используется схема по умолчанию из определения API. No Н/П
schema-ref Для схемы JSON, указанной в schema-id, необязательная ссылка на допустимый локальный путь ссылки в документе JSON. Пример: #/components/schemas/address. Атрибут должен возвращать объект JSON, который служба "Управление API" обрабатывает в качестве допустимой схемы JSON.

Для XML-схемы schema-ref не поддерживается, и любой элемент схемы верхнего уровня можно использовать в качестве корня полезных данных запроса или ответа XML. Цель проверки — убедиться, что все элементы, начиная с корня полезных данных запроса или ответа XML соответствуют предоставленной схеме XML.		 No Н/П
allow-additional-properties Логическое значение. Для схемы JSON указывает, следует ли реализовать переопределение additionalProperties среды выполнения значения, настроенного в схеме:
- true: разрешить дополнительные свойства в тексте запроса или ответа, даже если для поле схемы additionalProperties JSON настроено запрещать дополнительные свойства.
- false: запретить дополнительные свойства в тексте запроса или ответа, даже если для поле схемы additionalProperties JSON настроено разрешать дополнительные свойства.

Если атрибут не указан, политика проверит дополнительные свойства в соответствии с конфигурацией поля additionalProperties в схеме.		 No Н/П

Действия

Политики проверки содержимого включают один или несколько атрибутов, которые указывают действие, которое Управление API принимает при проверке сущности в запросе API или ответе на схему API.

  • Действие может быть задано для элементов, представленных в схеме API, и для элементов, которые не представлены в схеме API, в зависимости от политики.

  • Действие, указанное в дочернем элементе политики, переопределяет действие, указанное для его родительского элемента.

Доступные действия

Действие Описанием
ignore Пропуск проверки.
Предотвратить Блокировка обработки запроса или ответа, регистрация подробных сведений об ошибке и возврат ошибки. Обработка прерывается при обнаружении первого набора ошибок.
detect Регистрация ошибок проверки без прерывания обработки запроса или ответа.

Использование

  • Разделы политики: входящий трафик, исходящий трафик, при возникновении ошибок
  • Области политики: глобальная, рабочая область, продукт, API, операция
  • Шлюзы: классическая, версия 2, потребление, локальное размещение

Журналы

Сведения об ошибках проверки во время выполнения политики записываются в переменную в context.Variables, указанную в атрибуте errors-variable-name корневого элемента политики. Если так настроено действие prevent, ошибка проверки блокирует дальнейшую обработку запроса или ответа и также распространяется на свойство context.LastError.

Чтобы исследовать ошибки, используйте политику трассировки для регистрации ошибок из переменных контекста в Application Insights.

Влияние на производительность

Добавление политики проверки может повлиять на пропускную способность API. Предлагается руководствоваться общими принципами, описанными ниже.

  • Чем больше размер схемы API, тем более низкой будет пропускная способность.
  • Чем больше полезных данных в запросе или ответе, тем более низкой будет пропускная способность.
  • На производительность больше влияет размер схемы API, чем объем полезных данных.
  • При некоторых условиях проверка на соответствие схеме API, размер которой составляет несколько мегабайтов, может привести к превышению времени ожидания запроса или ответа. Этот эффект более выражен на уровнях службы Потребление и Разработчик.

Рекомендуем выполнять нагрузочные тесты с ожидаемыми рабочими нагрузками, чтобы оценить влияние политик проверки на пропускную способность API.

Схемы для проверки содержимого

По умолчанию проверка содержимого запроса или ответа использует схемы JSON или XML из определения API. Эти схемы можно указать вручную или создать автоматически при импорте API из спецификации OpenAPI или WSDL в службе "Управление API".

Используя политику validate-content, вы можете дополнительно проверить одну или несколько схем JSON или XML, добавленных в экземпляр службы "Управление API" и не являющихся частью определения API. Схему, добавляемую в службу "Управление API", можно повторно использовать во многих API.

Чтобы добавить схему в экземпляр службы "Управление API" с помощью портал Azure:

  1. На портале, перейдите к вашему экземпляру службы "Управление API".

  2. В разделе API в меню слева выберите Схемы>+ Добавить.

  3. В окне Создание схемы выполните следующие действия:

    1. Введите имя (идентификатор) для схемы.
    2. В типе схемы выберите JSON или XML.
    3. Введите Описание.
    4. В методе Create выполните одно из следующих действий:
      • Выберите Создать и введите или вставьте схему.
      • Выберите Импортировать из файла или Импортировать из URL-адреса и введите расположение схемы.

        Примечание.

        Чтобы схему можно было импортировать из URL-адреса, она должна быть доступна через Интернет из браузера.

    5. Выберите Сохранить.

    Создание схемы

API Management добавляет ресурс схемы по относительному URI/schemas/<schemaId>, а схема отображается в списке на странице Схемы. Выберите схему, чтобы просмотреть ее свойства или изменить ее в редакторе схем.

Примечание.

Схема может содержать перекрестную ссылку на другую схему, которая добавляется в экземпляр службы "Управление API". Например, включите XML-схему, добавленную в API Management с помощью примерно следующего элемента:

<xs:include schemaLocation="/schemas/myschema" />

Совет

Средства с открытым кодом для разрешения ссылок на схемы WSDL и XSD и пакетного импорта созданных схем в службе "Управление API" доступны на GitHub.

Примеры

Проверка схемы JSON

В следующем примере служба "Управление API" интерпретирует запросы с пустым заголовком типа контента или запросами с заголовком типа контента application/hal+json в виде запросов с типом контента application/json. Затем служба "Управление API" выполняет проверку в режиме обнаружения по схеме, определенной для типа контента application/json в определении API. Сообщения с полезными данными объемом более 100 КБ блокируются. Запросы, содержащие дополнительные свойства, блокируются, даже если для поля additionalProperties схемы настроено разрешать дополнительные свойства.

<validate-content unspecified-content-type-action="prevent" max-size="102400" size-exceeded-action="prevent" errors-variable-name="requestBodyValidation">
    <content-type-map missing-content-type-value="application/json">
        <type from="application/hal+json" to="application/json" />
    </content-type-map>
    <content type="application/json" validate-as="json" action="detect" allow-additional-properties="false" />
</validate-content>

Проверка схемы SOAP

В следующем примере служба "Управление API" интерпретирует любой запрос как запрос с типом контента application/soap+xml (тип контента, используемый API SOAP 1.2), независимо от типа входящего контента. Запрос может поступать с пустым заголовком типа контента, заголовком типа контента text/xml (используемым API SOAP 1.1) или другим заголовком типа контента. Затем служба "Управление API" извлекает полезные данные XML из конверта SOAP и выполняет проверку в режиме предотвращения в схеме с именем myschema. Сообщения с полезными данными объемом более 100 КБ блокируются.

<validate-content unspecified-content-type-action="prevent" max-size="102400" size-exceeded-action="prevent" errors-variable-name="requestBodyValidation">
    <content-type-map any-content-type-value="application/soap+xml" />
    <content type="application/soap+xml" validate-as="soap" schema-id="myschema" action="prevent" /> 
</validate-content>

Ошибки проверки

Управление API создает ошибки проверки содержимого в следующем формате:

{
 "Name": string,
 "Type": string,
 "ValidationRule": string,
 "Details": string,
 "Action": string
}

В таблице ниже перечислены все возможные ошибки политик проверки.

  • Сведения — можно использовать для изучения ошибок. Не предназначено для общего доступа.
  • Общедоступный ответ — ошибка, возвращенная клиенту. Не допускает утечки сведений о реализации.

Если политика проверки задает действие prevent и выдает ошибку, ответ от службы "Управление API"включает код состояния HTTP: 400, когда политика применяется в разделе входящего трафика, и 502, когда политика применяется в разделе исходящего трафика.

Имя Тип Правило проверки Сведения Общедоступный ответ Действие
validate-content
RequestBody SizeLimit Длина текста запроса составляет {size} байт и превышает заданное ограничение в {maxSize} байт. Длина текста запроса составляет {size} байт и превышает ограничение в {maxSize} байт. обнаружение/предотвращение
ResponseBody SizeLimit Длина текста ответа составляет {size} байт и превышает заданное ограничение в {maxSize} байт. Не удалось обработать запрос из-за внутренней ошибки. Обратитесь к владельцу API. обнаружение/предотвращение
{messageContentType} RequestBody Не определено Неуказанный тип содержимого {messageContentType} не допускается. Неуказанный тип содержимого {messageContentType} не допускается. обнаружение/предотвращение
{messageContentType} ResponseBody Не определено Неуказанный тип содержимого {messageContentType} не допускается. Не удалось обработать запрос из-за внутренней ошибки. Обратитесь к владельцу API. обнаружение/предотвращение
ApiSchema Схема API не существует, или не может быть разрешена. Не удалось обработать запрос из-за внутренней ошибки. Обратитесь к владельцу API. обнаружение/предотвращение
ApiSchema Схема API не задает определения. Не удалось обработать запрос из-за внутренней ошибки. Обратитесь к владельцу API. обнаружение/предотвращение
{messageContentType} RequestBody / ResponseBody MissingDefinition Схема API не содержит определение {definitionName}, связанное с типом содержимого {messageContentType}. Не удалось обработать запрос из-за внутренней ошибки. Обратитесь к владельцу API. обнаружение/предотвращение
{messageContentType} RequestBody IncorrectMessage Текст запроса не соответствует определению {definitionName}, связанному с типом содержимого {messageContentType}.

{valError.Message} Line: {valError.LineNumber}, Position: {valError.LinePosition}		 Текст запроса не соответствует определению {definitionName}, связанному с типом содержимого {messageContentType}.

{valError.Message} Line: {valError.LineNumber}, Position: {valError.LinePosition}		 обнаружение/предотвращение
{messageContentType} ResponseBody IncorrectMessage Текст ответа не соответствует определению {definitionName}, связанному с типом содержимого {messageContentType}.

{valError.Message} Line: {valError.LineNumber}, Position: {valError.LinePosition}		 Не удалось обработать запрос из-за внутренней ошибки. Обратитесь к владельцу API. обнаружение/предотвращение
RequestBody ValidationException Не удается проверить текст запроса для типа содержимого {messageContentType}.

{exception details}		 Не удалось обработать запрос из-за внутренней ошибки. Обратитесь к владельцу API. обнаружение/предотвращение
ResponseBody ValidationException Не удается проверить текст ответа для типа содержимого {messageContentType}.

{exception details}		 Не удалось обработать запрос из-за внутренней ошибки. Обратитесь к владельцу API. обнаружение/предотвращение
validate-parameters / validate-headers
{paramName} / {headerName} QueryParameter / PathParameter / RequestHeader Не определено Неуказанный {path parameter / query parameter / header} {paramName} не допускается. Неуказанный {path parameter / query parameter / header} {paramName} не допускается. обнаружение/предотвращение
{headerName} ResponseHeader Не определено Неуказанный заголовок {headerName} не допускается. Не удалось обработать запрос из-за внутренней ошибки. Обратитесь к владельцу API. обнаружение/предотвращение
ApiSchema Схема API не существует, или ее не удалось разрешить. Не удалось обработать запрос из-за внутренней ошибки. Обратитесь к владельцу API. обнаружение/предотвращение
ApiSchema Схема API не задает определения. Не удалось обработать запрос из-за внутренней ошибки. Обратитесь к владельцу API. обнаружение/предотвращение
{paramName} QueryParameter / PathParameter / RequestHeader / ResponseHeader MissingDefinition Схема API не содержит определение {definitionName}, связанное с {query parameter / path parameter / header} {paramName}. Не удалось обработать запрос из-за внутренней ошибки. Обратитесь к владельцу API. обнаружение/предотвращение
{paramName} QueryParameter / PathParameter / RequestHeader IncorrectMessage Запрос не может содержать несколько значений для {query parameter / path parameter / header} {paramName}. Запрос не может содержать несколько значений для {query parameter / path parameter / header} {paramName}. обнаружение/предотвращение
{headerName} ResponseHeader IncorrectMessage Ответ не может содержать несколько значений для заголовка {headerName}. Не удалось обработать запрос из-за внутренней ошибки. Обратитесь к владельцу API. обнаружение/предотвращение
{paramName} QueryParameter / PathParameter / RequestHeader IncorrectMessage Значение {query parameter / path parameter / header} {paramName} не соответствует определению.

{valError.Message} Line: {valError.LineNumber}, Position: {valError.LinePosition}		 Значение {query parameter / path parameter / header} {paramName} не соответствует определению.

{valError.Message} Line: {valError.LineNumber}, Position: {valError.LinePosition}		 обнаружение/предотвращение
{headerName} ResponseHeader IncorrectMessage Значение заголовка {headerName} не соответствует определению.

{valError.Message} Line: {valError.LineNumber}, Position: {valError.LinePosition}		 Не удалось обработать запрос из-за внутренней ошибки. Обратитесь к владельцу API. обнаружение/предотвращение
{paramName} QueryParameter / PathParameter / RequestHeader IncorrectMessage Значение {query parameter / path parameter / header} {paramName} не может быть проанализировано в соответствии с определением.

{ex.Message}		 Значение {query parameter / path parameter / header} {paramName} не удалось проанализировать в соответствии с определением.

{ex.Message}		 обнаружение/предотвращение
{headerName} ResponseHeader IncorrectMessage Значение заголовка {headerName} не удалось проанализировать в соответствии с определением. Не удалось обработать запрос из-за внутренней ошибки. Обратитесь к владельцу API. обнаружение/предотвращение
{paramName} QueryParameter / PathParameter / RequestHeader ValidationError Не удается проверить {Query parameter / Path parameter / Header} {paramName}.

{exception details}		 Не удалось обработать запрос из-за внутренней ошибки. Обратитесь к владельцу API. обнаружение/предотвращение
{headerName} ResponseHeader ValidationError Не удается проверить заголовок {headerName}.

{exception details}		 Не удалось обработать запрос из-за внутренней ошибки. Обратитесь к владельцу API. обнаружение/предотвращение
validate-status-code
{status-code} StatusCode Не определено Код состояния ответа {status-code} не допустим. Не удалось обработать запрос из-за внутренней ошибки. Обратитесь к владельцу API. обнаружение/предотвращение

В следующей таблице перечислены все возможные значения причины ошибки проверки, а также возможные значения сообщений.

Причина Сообщение
Недопустимый запрос {Details} для переменной контекста, {Public response} для клиента
Ответ не разрешен {Details} для переменной контекста, {Public response} для клиента

Связанный контент

Дополнительные сведения о работе с политиками см. в нижеуказанных статьях.