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

Статья
08/30/2024

ОБЛАСТЬ ПРИМЕНЕНИЯ: все уровни Управление 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" case-insensitive-property-names="true | false"/>
</validate-content>

Атрибуты

Атрибут	Description	Обязательное поле	По умолчанию.
unspecified-content-type-action	Действие, выполняемое для запросов или ответов с типом содержимого, который не указан в схеме API. Допустимы выражения политики.	Да	Н/П
max-size	Максимальная длина текста запроса или ответа в байтах, проверенная на соответствие заголовку `Content-Length`. Если текст запроса или текст ответа сжат, это значение представляет собой длину в распакованном виде. Максимально допустимое значение: 4 МБ. Допустимы выражения политики.	Да	Н/П
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	Н/П
case-insensitive-property-name	Логическое значение. Для схемы JSON указывает, следует ли сравнивать имена свойств объектов JSON без учета регистра. - `true`: сравнивайте имена свойств без учета регистра. - `false`: сравните регистр свойств с учетом регистра.	No	false

Действия

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

На портале, перейдите к вашему экземпляру службы "Управление API".
В разделе API в меню слева выберите Схемы>+ Добавить.
В окне Создание схемы выполните следующие действия:
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} для клиента

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

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

Руководство. Преобразование и защита API
Полный перечень операторов политик и их параметров см. в справочнике по политикам.
Выражения политики
Настройка или изменение политик
Повторное использование конфигураций политик
Репозиторий фрагментов политик
Создание политик с помощью Microsoft Copilot в Azure

Поделиться через

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

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

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

Атрибуты

Элементы

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

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

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

Действия

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

Журналы

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

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

Примеры

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

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

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

Обратная связь

Дополнительные ресурсы

Поделиться через

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

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

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

Атрибуты

Элементы

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

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

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

Действия

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

Журналы

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

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

Примеры

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

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

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

Связанные политики

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

Обратная связь

Дополнительные ресурсы