DataPower API Gateway

validate - DataPower API Gateway

在线编辑

使用 validate 策略针对模式验证组合件流中的有效内容。

网关支持

注: 此页面描述 DataPower® API Gateway中的 validate 策略实现。 如果您正在使用该功能 DataPower Gateway (v5 compatible)，请参阅 validate - DataPower Gateway （兼容 v5 ）。

有关不同类型的网关的信息，请参阅 API Connect 网关类型。

表 1. 显示哪些网关支持此策略以及对应策略版本的表格
网关 策略版本
DataPower API Gateway 2.0.0

2.1.0 (DataPower API Gateway V 10.0.1.0 或更高版本)

2.2.0 (DataPower API Gateway V 10.0.2.0 或更高版本)

2.3.0 (DataPower API Gateway V 10.0.2.0 或更高版本)

2.4.0 (DataPower API Gateway V 10.0.4.0 或更高版本)

2.5.0 (DataPower API Gateway V 10.5.0.0 或更高版本)

2.6.0 (DataPower API Gateway V 10.5.0.2 或更高版本)

2.7.0 (DataPower API Gateway V 10.5.0.3 或更高版本)

本主题介绍了如何在 OpenAPI 源中配置策略；有关如何在程序集用户界面中配置策略的详细信息，请参阅“验证” - DataPowerAPI Gateway。

关于

validate 策略具有以下格式:
- validate:
    version: version
    title: title
    description: description
    validate-against: validation_mechanism
         .
         .
         .
       properties_specific_to_the specified_validation_mechanism
         .
         .
         .

通过将具有 execute 字段的 assembly 扩展添加到 OpenAPI 定义文件来应用此策略。

注: 使用 DataPower API Gateway时， validate 策略的输入必须是已解析的数据。 生成已解析数据的一种方法是在组合件流中的 validate 策略之前使用 parse 策略，这将提供解析操作的显式控制。

属性

下表描述了该策略的属性：
表 2. validate 策略属性
属性 必需 描述 数据类型
version 是 策略版本号 字符串
title False 策略的标题。 字符串
description False 策略的描述。 字符串
input False 标识 API 上下文中的变量。 变量的 body 字段的内容（通过 variable_name.body 表示）是要验证的输入数据。 缺省情况下，变量名称是 message。 字符串
output False 指定 API 上下文中变量的名称。
  • 如果验证通过，那么输出变量的 body 字段（通过 variable_name.body 表示）将存储组合件 validate 操作的输出。
  • 如果要验证的模式是 JSON 模式，那么验证还会添加有效内容中缺失的任何缺省值。
  • 如果验证失败，那么将不存储任何输出。
  • 如果未指定输出变量，那么将不会保存组合件验证操作的结果。
 字符串
validate-against 是 指定要用于验证有效内容的模式。
有效值：
  • definition：使用先前定义的模式来验证从组合件流中的其他调用操作或任务返回的有效内容。

    此外，提供 definition 属性以指定所需模式。

  • url：该方案由 URL 位置标识。
    此外，还提供以下属性：
    • json-schema 字段：要用于验证 JSON 有效内容的 JSON 模式的 URL。
    • xml-validation-mode，指定以下值之一，以定义 XML 有效内容的验证方式：
      • xsd：使用 XML 模式；此外，提供 xml-schema 属性，以指定 XML 模式的 URL。
      • wsdl：使用 WSDL 模式；此外，提供 xml-schema 属性，以指定要用于验证 SOAP 有效内容的 WSDL 模式的 URL。
      • soap-body：仅针对 XML 模式，验证 SOAP 消息的主体。
      注: 以下限制适用于用于 JSON 验证的模式，其中包括用作验证模式的 JSON 模式和 OpenAPI 文档。 超出这些限制可能会影响编译性能，从而不受支持。
      • 最多 6500 行。 数组中的每个键和每个项计为一行。
      • 最大递归深度为 250。
      • enum 列表中最多包含 3000 项。
  • wsdl：（仅与基于 SOAP 服务的 API 一起使用）使用 WSDL 文件中与 API 操作或 API 路径关联的 XML 模式。
  • body-param：针对 schema 属性中为该操作的请求参数指定的模式定义对请求输入进行验证。
  • response-param：针对 schema 属性中为该操作的响应参数指定的模式定义验证要返回到客户机应用程序的响应。
  • graphql：（仅与 GraphQL 代理 API 一起使用）针对已导入到 GraphQL 代理 API 的 GraphQL 模式验证有效内容。 此外，根据输入，针对 GraphQL 模式分析 GraphQL 查询或响应以计算成本，并且将结果放置在 API 上下文中。

    有关 GraphQL 代理 API 的更多信息，请参阅 《创建 GraphQL 代理 API 》以及 GraphQL 上下文变量。

    .
 字符串
xslt-version False XSLT 处理器版本。 缺省值为 XSLT10。 字符串
strict False 是否启用严格 XSLT 错误检查。 非严格操作会试图从某些错误（例如，使用未声明的变量、调用未声明的模板等）中恢复。 缺省情况下，已启用严格 XSLT 错误检查。 布尔型
profile False 是否启用样式表概要分析。 此选项不应在生产环境中使用。 缺省情况下，已禁用样式表概要分析。 布尔型
debug False 是否以调试方式运行样式表， XQuery 脚本和 JSONiq 脚本。 当以调试方式运行样式表、XQuery 脚本或 JSONiq 脚本时，它将生成定制 Web 页面，而不是显示其正常输出。 Web 页面详细描述执行期间发生的情况，包括变量的值以及特定部分输出的来源。 此选项不应在生产环境中使用。 默认情况下，调试模式处于禁用状态。 布尔型
stream False 是否必须以流式方式运行样式表。 文档的转换在完全解析输入之前开始。 并非所有样式表都可以流式传输。 如果样式表无法流式传输，那么将生成错误并且不处理输入。 缺省情况下，已禁用流方式。 布尔型
try-stream False 是否尝试以流式方式运行样式表。 文档的转换在完全解析输入之前开始。 并非所有样式表都可以流式传输。 如果样式表无法流式传输，那么会在编译期间生成警告，并且在执行时正常读取整个输入中的样式表。 缺省情况下，已禁止尝试在流方式下运行样式表。 布尔型
minimum-escaping False 是否在处理期间对从样式表生成的输出进行转义。 最小转义在处理非英语字符集时特别有用。 缺省情况下，已禁用最小转义。 布尔型
stack-size False 允许堆栈在执行样式表或其他已编译内容时使用的最大字节数。 此设置用于阻止无限递归。 最小值为 10 千字节或 10,240 字节。 最大值为 100 兆字节或 104,857,600 字节。 缺省值为 1 兆字节或 1,048,576 字节。 整数
wsi-validation False 要应用于 WSDL 文件的验证行为，这些文件检查是否符合 WS-I Basic Profile (V 1.0， 2004 年 4 月) 的 5 部分。 缺省设置为 Warn。
忽略
禁用符合性检查。
警告
记录违规警告。
失败
强制符合。 如果文件中存在任何违规内容，则操作失败。
 字符串
wsdl-validate-body False soap:Body的验证行为。 缺省设置为 严格。
严格
根据 WSDL 定义验证消息的这一部分。 仅允许包含此部分且符合 WSDL 定义的消息。
宽松
根据 WSDL 定义验证消息的这一部分。 如果消息包含该部分，而 WSDL 定义中未定义该部分，则允许该消息。 如果消息包含此部分，且 WSDL 定义中包含此部分，则仅在两者匹配时才允许该消息。
跳过
禁用对消息此部分的验证。
 字符串
wsdl-validate-headers False

soap:Header的验证行为。 缺省设置为 Lax。

严格
根据 WSDL 定义验证消息的这一部分。 仅允许包含此部分且符合 WSDL 定义的消息。
宽松
根据 WSDL 定义验证消息的这一部分。 如果消息包含该部分，而 WSDL 定义中未定义该部分，则允许该消息。 如果消息包含此部分，且 WSDL 定义中包含此部分，则仅在两者匹配时才允许该消息。
跳过
禁用对消息此部分的验证。
 字符串
wsdl-validate-faults False 指定故障详细信息的验证行为。 缺省设置为 严格。
严格
根据 WSDL 定义验证消息的这一部分。 仅允许包含此部分且符合 WSDL 定义的消息。
宽松
根据 WSDL 定义验证消息的这一部分。 如果消息包含该部分，而 WSDL 定义中未定义该部分，则允许该消息。 如果消息包含此部分，且 WSDL 定义中包含此部分，则仅在两者匹配时才允许该消息。
跳过
禁用对消息此部分的验证。
 字符串
wsdl-wrapped-faults False 是否要求与 RPC 风格的封装函数兼容。 缺省情况下，不需要 RPC 样式的包装程序。 布尔型
allow-soap-enc-array False 是否允许模式接受 xsi:type='SOAP-ENC:Array' 与 SOAP 1.1 部分 5 一致的元素的大多数使用，即使这些属性违反 XML 模式规范也是如此。 通常， xsi:type 属性必须指定等于或派生自元素的实际类型的类型。 对于使用此选项编译的模式，如果元素类型派生自 SOAP-ENC:Array，那么将专门针对 SOAP 1.1 编码 "数组" 复杂类型接受 xsi:type 。 与之相对的是正常允许的情况。 缺省情况下，不接受具有 xsi:type='SOAP-ENC:Array' 的元素。 布尔型
validate-soap-enc-array False 是否遵循 SOAP 1.1 部分 5 中的编码规则执行额外的模式验证。 启用此选项后，将验证 SOAP 数组成员，即使模式不允许使用 @id 和 @href 之类的属性，也会检查 @href 值以确保它们具有相应的 @id 元素。 缺省情况下，将不执行额外的验证。 布尔型
wildcards-ignore-xsi-type False 模式中的 xs:any 元素是否仅按名称验证子元素。 XML 模式规范要求，如果通配符与某个元素匹配，但该元素没有元素声明，那么将根据该元素上的 xsi:type 属性来验证该元素。 此选项将忽略这些 xsi:type 属性。 此选项应在诸如 SOAP 包络验证之类的情况下使用，在此情况下，进一步验证步骤可能会使用 SOAP 1.1 编码规则验证与通配符匹配的内容。 缺省情况下，不会忽略 xsi:type 属性。 布尔型
wsdl-strict-soap-version False 是否严格遵循 WSDL 中的 SOAP 绑定。 启用此选项后，只有绑定到 SOAP 1.2 的消息才会出现在 SOAP 1.2 包络中，并且只有绑定到 SOAP 1.1 的消息才会出现在 SOAP 1.1 包络中。 缺省情况下，已禁用严格 SOAP 绑定。 布尔型
xacml-debug False 是否使用调试信息编译 XACML 策略。 请注意，XACML 调试消息也受 XACML 类别中的日志事件控制。 请使用调试日志级别来查看完整的 XACML 调试消息。 缺省情况下，不使用调试信息编译 XACML 策略。 布尔型
allow-xop-include False 指定模式或 WSDL 文档是否接受其基本 64 位编码的二进制内容已根据 MTOM/XOP 规范进行优化的消息。 XOP 二进制优化将 base64-encoded 二进制数据替换为引用附件中未编码的二进制数据的 xop:Include 引用元素。 缺省情况下，已禁用 MTOM/XOP 优化消息。
  • 如果禁用此功能，优化后的表单在验证时会拒绝此类优化后的消息。 发生拒绝的原因是模式指定了接受 base64-encoded 数据 (例如 xs:base64Binary 或 xs:string) 的简单类型，但消息改为包含 xop:Include 元素。
  • 启用后， xop:Include 元素可以选择性地显示用于验证 base64-encoded 二进制数据的任何 XML 模式简单类型的内容。 将根据 store:///schemas/xop.xsd中的内置模式来验证 xop:Include 元素本身。
 布尔型

您还可以通过使用 API Designer 组合件编辑器向 API 添加内置策略来应用 validate 策略。 如需更多信息，请参阅“内置策略”部分中的 “Validate - DataPower API Gateway ”。

示例 1

- validate:
    version: 2.0.0
    title: 'validate, response parameter schema'
    validate-against: response-param

示例 2

- validate:
    version: 2.0.0
    title: 'validate, predefined schema'
    validate-against: definition
    definition: '#/definitions/RouteOutput'

示例 3

- validate:
    version: 2.0.0
    title: 'validate, JSON and XML schema URLs'
    validate-against: url
    json-schema: 'https://my.json.schema'
    xml-validation-mode: xsd
    xml-schema: 'https://my.xml.schema'