Бөлісу құралы:

Проверка параметров

  • Мақала

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

Политика validate-parameters проверяет параметры заголовка, запроса или пути в запросах на соответствие схеме API.

Внимание

Если API импортирован с помощью версии API управления до 2021-01-01-preview, политика validate-parameters может не действовать. Возможно, потребуется повторно импортировать API с помощью версии API управления 2021-01-01-preview или более поздней версии.

Примечание.

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

Примечание.

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

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

<validate-parameters specified-parameter-action="ignore | prevent | detect" unspecified-parameter-action="ignore | prevent | detect" errors-variable-name="variable name"> 
    <headers specified-parameter-action="ignore | prevent | detect" unspecified-parameter-action="ignore | prevent | detect">
        <parameter name="parameter name" action="ignore | prevent | detect" />
    </headers>
    <query specified-parameter-action="ignore | prevent | detect" unspecified-parameter-action="ignore | prevent | detect">
        <parameter name="parameter name" action="ignore | prevent | detect" />
    </query>
    <path specified-parameter-action="ignore | prevent | detect">
        <parameter name="parameter name" action="ignore | prevent | detect" />
    </path>
</validate-parameters>

Атрибуты

Атрибут Description Обязательное поле По умолчанию.
specified-parameter-action Действие, выполняемое для параметров запроса, указанных в схеме API.

Если указано в элементе headers, query или path, значение переопределяет значение specified-parameter-action в элементе validate-parameters. Допустимы выражения политики.		 Да Н/П
unspecified-parameter-action Действие, выполняемое для параметров запроса, не указанных в схеме API.

Если указано в элементе headers или query, значение переопределяет значение unspecified-parameter-action в элементе validate-parameters. Допустимы выражения политики.		 Да Н/П
errors-variable-name Имя переменной в context.Variables, где регистрируются ошибки проверки. Выражения политики не допускаются. No Н/П

Элементы

Имя Описание Обязательное поле
заголовки Добавьте этот элемент и один или несколько parameter подэлементов, чтобы переопределить действия проверки по умолчанию для определенных именованных параметров в запросах. Если параметр указан в схеме API, это значение переопределяет конфигурацию specified-parameter-action более высокого уровня. Если параметр не указан в схеме API, это значение переопределяет конфигурацию unspecified-parameter-action более высокого уровня. No
query Добавьте этот элемент и один или несколько parameter подэлементов, чтобы переопределить действия проверки по умолчанию для определенных именованных параметров запроса в запросах. Если параметр указан в схеме API, это значение переопределяет конфигурацию specified-parameter-action более высокого уровня. Если параметр не указан в схеме API, это значение переопределяет конфигурацию unspecified-parameter-action более высокого уровня. No
path Добавьте этот элемент и один или несколько parameter подэлементов, чтобы переопределить действия проверки по умолчанию для определенных параметров пути URL-адреса в запросах. Если параметр указан в схеме API, это значение переопределяет конфигурацию specified-parameter-action более высокого уровня. Если параметр не указан в схеме API, это значение переопределяет конфигурацию unspecified-parameter-action более высокого уровня. No

Действия

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

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

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

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

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

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

Примечания об использовании

  • Эту политику можно использовать только один раз в разделе политики.

Журналы

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

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

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

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

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

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

Пример

В этом примере все параметры запроса и пути проверяются в режиме предотвращения, а заголовки — в режиме обнаружения. Проверка переопределяется для нескольких параметров заголовка.

<validate-parameters specified-parameter-action="prevent" unspecified-parameter-action="prevent" errors-variable-name="requestParametersValidation"> 
    <headers specified-parameter-action="detect" unspecified-parameter-action="detect">
        <parameter name="Authorization" action="prevent" />
        <parameter name="User-Agent" action="ignore" />
        <parameter name="Host" action="ignore" />
        <parameter name="Referrer" action="ignore" />
    </headers>   
</validate-parameters>

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

Управление 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} для клиента

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

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