验证参数

适用于：所有 API 管理层级

validate-parameters 策略根据 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>

属性

元素

操作

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

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

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

可用操作：

使用情况

• 策略节：入站
• 策略范围：全局、工作区、产品、API、操作
• 网关：经典、消耗、自承载

使用注意事项

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

日志

有关在执行策略期间出现的验证错误的详细信息将记录到策略根元素的 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。

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

相关策略

• 内容验证

后续步骤

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

• 教程：转换和保护 API
• 策略参考，其中提供了策略语句及其设置的完整列表
• 策略表达式
• 设置或编辑策略
• 策略示例