你当前正在访问 Microsoft Azure Global Edition 技术文档网站。 如果需要访问由世纪互联运营的 Microsoft Azure 中国技术文档网站，请访问 https://docs.azure.cn。
验证参数
适用于：所有 API 管理层级
validate-parameters 策略根据 API 架构验证请求中的头、查询或路径参数。
重要
如果使用低于 2021-01-01-preview 的管理 API 版本导入了某个 API，validate-parameters 策略可能不起作用。 可能需要使用管理 API 版本 2021-01-01-preview 或更高版本重新导入你的 API。
注意
可供此验证策略使用的 API 架构的最大大小为 4 MB。 如果架构超过此限制，验证策略将在运行时返回错误。 若要提高限制，请与支持部门联系。
注意
按照策略声明中提供的顺序设置策略的元素和子元素。 为了帮助你配置此策略，门户提供了基于窗体的引导式编辑器。 详细了解如何设置或编辑 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>
属性
| 属性 | 说明 | 需要 | 默认 |
|---|---|---|---|
| specified-parameter-action | 针对 API 架构中指定的请求参数执行的操作。 在 headers、query 或 path 元素中提供时，该值将替代 specified-parameter-action 元素中的 validate-parameters 值。 允许使用策略表达式。 |
是 | 空值 |
| unspecified-parameter-action | 要针对未在 API 架构中指定的请求参数执行的操作。 在 headers 或 query 元素中提供时，该值将替代 validate-parameters 元素中的 unspecified-parameter-action 值。 允许使用策略表达式。 |
是 | 空值 |
| errors-variable-name | context.Variables 中的要将验证错误记录到的变量的名称。 不允许使用策略表达式。 |
否 | 空值 |
元素
| 名称 | 说明 | 必需 |
|---|---|---|
| headers | 添加此元素和一个或多个 parameter 子元素，以替代请求中某些命名参数的默认验证操作。 如果该参数已在 API 架构中指定，此值将替代更高级别的 specified-parameter-action 配置。 如果该参数未在 API 架构中指定，此值将替代更高级别的 unspecified-parameter-action 配置。 |
否 |
| query | 添加此元素和一个或多个 parameter 子元素，以替代请求中某些命名查询参数的默认验证操作。 如果该参数已在 API 架构中指定，此值将替代更高级别的 specified-parameter-action 配置。 如果该参数未在 API 架构中指定，此值将替代更高级别的 unspecified-parameter-action 配置。 |
否 |
| path | 添加此元素和一个或多个 parameter 子元素，以替代请求中某些 URL 路径参数的默认验证操作。 如果该参数已在 API 架构中指定，此值将替代更高级别的 specified-parameter-action 配置。 如果该参数未在 API 架构中指定，此值将替代更高级别的 unspecified-parameter-action 配置。 |
否 |
操作
内容验证策略包含一个或多个用于指定操作的特性，该操作将由 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-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} 字节)。 | 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} |
相关策略
相关内容
有关使用策略的详细信息，请参阅：
- 教程：转换和保护 API
- 策略参考，其中提供了策略语句及其设置的完整列表
- 策略表达式
- 设置或编辑策略
- 重复使用策略配置
- 策略片段存储库
- 使用 Azure 中的 Microsoft Copilot 创作策略