Проверка кода состояния

  • Статья

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

Политика validate-status-code проверяет коды состояния HTTP в ответах на соответствие схеме API. Эту политику можно применять, чтобы предотвратить утечку данных внутренних ошибок, где может содержаться трассировка.

Примечание.

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

Примечание.

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

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

<validate-status-code unspecified-status-code-action="ignore | prevent | detect" errors-variable-name="variable name">
    <status-code code="HTTP status code number" action="ignore | prevent | detect" />
</validate-status-code>

Атрибуты

Атрибут Description Обязательное поле По умолчанию.
unspecified-status-code-action Действие, выполняемое для кодов состояния HTTP в ответах, не указанных в схеме API. Допустимы выражения политики. Да Н/П
errors-variable-name Имя переменной в context.Variables, где регистрируются ошибки проверки. Выражения политики не допускаются. No Н/П

Элементы

Имя Описание Обязательное поле
status-code Добавьте один или несколько элементов для кодов состояния HTTP, чтобы переопределить действие проверки по умолчанию для кодов состояния в ответах. No

Атрибуты кода состояния

Атрибут Description Обязательное поле По умолчанию.
кодом Код состояния HTTP, для которого переопределяется действие проверки. Да Н/П
действие Действие, выполняемое для совпадающего кода состояния, не указанного в схеме API. Если код состояния указан в схеме API, это переопределение не будет действовать. Да Н/П

Действия

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

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

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

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

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

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

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

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

Журналы

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

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

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

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

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

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

Пример

<validate-status-code unspecified-status-code-action="prevent" errors-variable-name="responseStatusCodeValidation" />

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

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

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

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