通过

验证头

  • 项目

适用于：所有 API 管理层级

validate-headers 策略根据 API 架构验证响应头。

重要

如果使用低于 2021-01-01-preview 的管理 API 版本导入了某个 API，validate-headers 策略可能不起作用。 可能需要使用管理 API 版本 2021-01-01-preview 或更高版本重新导入该 API。

注意

可供此验证策略使用的 API 架构的最大大小为 4 MB。 如果架构超过此限制，验证策略将在运行时返回错误。 若要提高限制，请与支持部门联系。

提示

为了帮助你配置此策略，门户提供了基于窗体的引导式编辑器。 详细了解如何设置或编辑 API 管理策略。

策略语句

<validate-headers specified-header-action="ignore | prevent | detect" unspecified-header-action="ignore | prevent | detect" errors-variable-name="variable name">
    <header name="header name" action="ignore | prevent | detect" />
</validate-headers>

属性

属性 说明 需要 默认
specified-header-action 针对 API 架构中指定的响应头执行的操作。 允许使用策略表达式。 是 空值
unspecified-header-action 要针对未在 API 架构中指定的响应头执行的操作。 允许使用策略表达式。 是 空值
errors-variable-name context.Variables 中的要将验证错误记录到的变量的名称。 不允许使用策略表达式。 否 空值

元素

名称 说明 必需
标头的值开始缓存响应 为命名的头添加一个或多个元素可以替代针对响应中的头执行的默认验证操作。 否

操作

内容验证策略包含一个或多个用于指定操作的特性，该操作将由 API 管理在根据 API 架构验证 API 请求或响应中的实体时执行。

  • 可为 API 架构中表示的元素指定操作，并可以根据策略为 API 架构中未表示的元素指定操作。

  • 在策略的子元素中指定的操作将替代针对其父级指定的操作。

可用操作：

操作 说明
ignore 跳过验证。
prevent 阻止请求或响应处理，记录详细的验证错误，并返回错误。 检测到第一组错误时便中断处理。
检测 (detect) 记录验证错误，但不中断请求或响应处理。

使用情况

使用注意事项

  • 此策略只能在策略部分中使用一次。

日志

有关在执行策略期间出现的验证错误的详细信息将记录到策略根元素的 errors-variable-name 特性中指定的 context.Variables 内的变量。 在 prevent 操作中进行配置后，验证错误会阻止进一步的请求或响应处理，并会传播到 context.LastError 属性。

若要调查错误，请使用跟踪策略将上下文变量中的错误记录到 Application Insights。

性能影响

添加验证策略可能会影响 API 吞吐量。 以下一般原则适用：

  • API 架构越大，吞吐量越低。
  • 请求或响应中的有效负载越大，吞吐量越低。
  • 相比于有效负载大小，API 架构大小对性能的影响更大。
  • 在某些情况下，根据若干 MB 大小的 API 架构进行验证可能会导致请求或响应超时。 在“消耗”和“开发人员”服务层级中，这种影响更为明显。

我们建议在预期的生产工作负载中执行负载测试，以评估验证策略对 API 吞吐量的影响。

示例

<validate-headers specified-header-action="ignore" unspecified-header-action="prevent" errors-variable-name="responseHeadersValidation" />

验证错误

API 管理生成以下格式的内容验证错误：

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

下表列出了验证策略的所有可能错误。

  • 详细信息：可用于调查错误。 不应公开共享。
  • 公共响应：返回到客户端的错误。 不会泄漏实现详细信息。

当验证策略指定 prevent 操作并产生错误时，API 管理的响应将包括 HTTP 状态代码：在入站部分中应用该策略时为 400，在出站部分应用该策略时为 502。

名称 类型 验证规则 详细信息 公共响应 操作
validate-content
RequestBody SizeLimit 请求正文的长度为 {size} 个字节，超过了配置的限制({maxSize} 字节)。 请求正文的长度为 {size} 个字节，超过了限制({maxSize} 字节)。 detect / prevent
ResponseBody SizeLimit 响应正文的长度为 {size} 个字节，超过了配置的限制({maxSize} 字节)。 由于发生内部错误，无法处理请求。 请与 API 所有者联系。 detect / prevent
{messageContentType} RequestBody 未指定 不允许未指定的内容类型 {messageContentType}。 不允许未指定的内容类型 {messageContentType}。 detect / prevent
{messageContentType} ResponseBody 未指定 不允许未指定的内容类型 {messageContentType}。 由于发生内部错误，无法处理请求。 请与 API 所有者联系。 detect / prevent
ApiSchema API 的架构不存在或无法解析。 由于发生内部错误，无法处理请求。 请与 API 所有者联系。 detect / prevent
ApiSchema API 的架构未指定定义。 由于发生内部错误，无法处理请求。 请与 API 所有者联系。 detect / prevent
{messageContentType} RequestBody / ResponseBody MissingDefinition API 的架构不包含与内容类型 {messageContentType} 关联的定义 {definitionName}。 由于发生内部错误，无法处理请求。 请与 API 所有者联系。 detect / prevent
{messageContentType} RequestBody IncorrectMessage 请求正文不符合与内容类型 {messageContentType} 关联的定义 {definitionName}。

{valError.Message} 行: {valError.LineNumber}，位置: {valError.LinePosition}		 请求正文不符合与内容类型 {messageContentType} 关联的定义 {definitionName}。

{valError.Message} 行: {valError.LineNumber}，位置: {valError.LinePosition}		 detect / prevent
{messageContentType} ResponseBody IncorrectMessage 响应正文不符合与内容类型 {messageContentType} 关联的定义 {definitionName}。

{valError.Message} 行: {valError.LineNumber}，位置: {valError.LinePosition}		 由于发生内部错误，无法处理请求。 请与 API 所有者联系。 detect / prevent
RequestBody ValidationException 无法验证 {messageContentType} 内容类型的请求正文。

{exception details}		 由于发生内部错误，无法处理请求。 请与 API 所有者联系。 detect / prevent
ResponseBody ValidationException 无法验证 {messageContentType} 内容类型的响应正文。

{exception details}		 由于发生内部错误，无法处理请求。 请与 API 所有者联系。 detect / prevent
validate-parameters / validate-headers
{paramName} / {headerName} QueryParameter / PathParameter / RequestHeader 未指定 不允许未指定的 {path parameter / query parameter / header} {paramName}。 不允许未指定的 {path parameter / query parameter / header} {paramName}。 detect / prevent
{headerName} ResponseHeader 未指定 不允许未指定的头 {headerName}。 由于发生内部错误，无法处理请求。 请与 API 所有者联系。 detect / prevent
ApiSchema API 的架构不存在或无法解析。 由于发生内部错误，无法处理请求。 请与 API 所有者联系。 detect / prevent
ApiSchema API 架构未指定定义。 由于发生内部错误，无法处理请求。 请与 API 所有者联系。 detect / prevent
{paramName} QueryParameter / PathParameter / RequestHeader / ResponseHeader MissingDefinition API 的架构不包含与 {query parameter / path parameter / header} {paramName} 关联的定义 {definitionName}。 由于发生内部错误，无法处理请求。 请与 API 所有者联系。 detect / prevent
{paramName} QueryParameter / PathParameter / RequestHeader IncorrectMessage 请求不能包含 {query parameter / path parameter / header} {paramName} 的多个值。 请求不能包含 {query parameter / path parameter / header} {paramName} 的多个值。 detect / prevent
{headerName} ResponseHeader IncorrectMessage 响应不能包含头 {headerName} 的多个值。 由于发生内部错误，无法处理请求。 请与 API 所有者联系。 detect / prevent
{paramName} QueryParameter / PathParameter / RequestHeader IncorrectMessage {query parameter / path parameter / header} {paramName} 的值不符合定义。

{valError.Message} 行: {valError.LineNumber}，位置: {valError.LinePosition}		 {query parameter / path parameter / header} {paramName} 的值不符合定义。

{valError.Message} 行: {valError.LineNumber}，位置: {valError.LinePosition}		 detect / prevent
{headerName} ResponseHeader IncorrectMessage 头 {headerName} 的值不符合定义。

{valError.Message} 行: {valError.LineNumber}，位置: {valError.LinePosition}		 由于发生内部错误，无法处理请求。 请与 API 所有者联系。 detect / prevent
{paramName} QueryParameter / PathParameter / RequestHeader IncorrectMessage 无法根据定义分析 {query parameter / path parameter / header} {paramName} 的值。

{ex.Message}		 无法根据定义分析 {query parameter / path parameter / header} {paramName} 的值。

{ex.Message}		 detect / prevent
{headerName} ResponseHeader IncorrectMessage 无法根据定义分析头 {headerName} 的值。 由于发生内部错误，无法处理请求。 请与 API 所有者联系。 detect / prevent
{paramName} QueryParameter / PathParameter / RequestHeader ValidationError 无法验证 {Query parameter / Path parameter / Header} {paramName}。

{exception details}		 由于发生内部错误，无法处理请求。 请与 API 所有者联系。 detect / prevent
{headerName} ResponseHeader ValidationError 无法验证头 {headerName}。

{exception details}		 由于发生内部错误，无法处理请求。 请与 API 所有者联系。 detect / prevent
validate-status-code
{status-code} StatusCode 未指定 不允许响应状态代码 {status-code}。 由于发生内部错误，无法处理请求。 请与 API 所有者联系。 detect / prevent

下表列出了验证错误的所有可能原因值以及可能的消息值：

原因 消息
错误的请求 针对上下文变量的 {Details}，针对客户端的 {Public response}
不允许响应 针对上下文变量的 {Details}，针对客户端的 {Public response}

后续步骤

有关使用策略的详细信息，请参阅：