解析

使用 解析 策略来控制输入文档的解析。 当输入文档为 JSON 字符串时,将解析而非复制该字符串。

表 1. 该表显示了支持此策略的网关以及对应的策略版本
网关 策略版本
DataPower® API Gateway 2.0.0

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

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

本主题介绍如何在程序集用户界面中配置策略;有关如何在源代码中配置策略的详情,请参阅解析。 OpenAPI 源中配置策略的详情,请参阅解析

关于 解析

通过解析策略,您可以使用以下方法按优先顺序递增来检索解析设置。
  1. 指定有效的解析设置配置,以便从中检索其属性作为缺省解析设置。
    注: 如果更改缺省名称,那么必须在 DataPower API Gateway上单独配置相应的 ParseSettings 对象。
  2. 指定序列化 XML 或 JSON 属性形式的文字串,以作为解析设置。 这些属性优先于任何现有缺省属性。 文字串必须采用 XML 或 JSON 格式。
    • XML 格式为 "<ParseSettings><propertyName>propertyValue</propertyName></ParseSettings>"
    • JSON 格式为 "{ \"ParseSettings\" : { \"propertyName\" : propertyValue } }"
  3. 表示指定上下文的 URL,可从中检索序列化的 XML 或 JSON 属性作为解析设置。 这些属性优先于任何现有字面值或缺省属性。

属性

下表列示了策略属性,指示属性是否为必需属性,指定输入的有效值和缺省值并指定值的数据类型。

表 2. 解析 策略属性
属性标签 必需 描述 数据类型
职务 False 策略的标题。

缺省值为 parse

字符串
描述 False 对策略的描述。 字符串
使用内容类型 False 如果启用此设置并且解析设置配置为检测文档类型,那么解析操作将使用请求头中指定的 Content-Type

如果启用此设置并且为 JSON 或 XML 配置解析设置中的文档类型,那么解析操作将使用请求头中指定的 Content-Type,并且如果请求头中的 Content-Type 与解析设置不匹配,那么会失败。

只有当期望的 Content-Type 为 JSON 或 XML 时,才能启用此设置。

如果未启用此设置,那么解析操作将使用解析设置中指定的文档类型,或者如果将解析设置配置为检测文档类型,那么将使用检测到的文档类型。

缺省情况下未选中此复选框。

布尔型
解析设置对象引用 False 现有的有效对象,可从中检索动态对象的缺省属性值。 字符串
文档类型 False 要解析的文档类型。 选择下列其中一个选项:
  • Detect:检测文档类型,并相应解析有效内容。 此类型是缺省选项。
  • JSON:将有效内容解析为 JSON。
  • XML:将有效内容解析为 XML。
  • Graphql:通过以下任一方式执行解析:
    • 作为 POST 请求主体中的 GraphQL。 GraphQL 采用以下格式:
      {
        me {
          name
        }
      }
    • 作为包含 GraphQL 查询的 POST 请求主体中的 JSON 字符串。 JSON 对象采用以下格式:
      {
        "query": "query MyData ($idVar: Int!) { user (id: $idVar) { name }}",
        "operationName": "MyData",
        "variables": {"idVar": 123}
      }
    • 通过 GET 请求的 URL 查询。 URL 采用以下格式:
      https://myapi/graphql?query={me{name}}
      以下示例包括 variablesoperationName 属性,使用 URL 编码(换行符仅用于表格格式,您的值中不会包含换行符):
      https://hostname/basepath/graphql?query=query%20fetchAccounts
      %20($limit:%20Int)%20{accounts(limit:%20$limit)%20{name{first,last}}}
      &variables={"limit":100}&operationName=fetchAccounts
      注意: 如果在 "调用 "策略中选择了 " 缓冲" ,则会检测文件类型并相应地解析有效载荷。 更多信息,请参阅为 DataPower API Gateway 配置调用策略为 DataPower Gateway 配置调用策略 ( v5 兼容)

GET 请求中的查询变量可在名为 variables 的查询参数中作为 JSON 字符串发送。 如果查询包含多个已命名的操作,那么需要 operationName 查询参数来确定要执行的操作。

字符串
最大文档大小 False (可选)解析操作接受的 JSON、XML 或 GraphQL 输入文档的最大文档大小(以字节为单位)。 此设置通过实施最大文档大小来提供威胁保护。 请输入 0 - 5368709121 范围内的值。 当文档大小超过最大大小时,将拒绝该文档。 值 0 指示文档大小不受限制。 设置为 0 时,操作结果不会返回文档大小。

缺省值为 4194304。

整数
最大嵌套深度 False (可选)解析操作接受的 XML、JSON 或 GraphQL 消息的最大嵌套深度。 此设置通过在消息中实施限制来提供威胁保护。
  • 如果是 XML,那么这是元素深度的最大级别。
  • 如果是 JSON,那么这是嵌套标签/值对的最大级别、嵌套数组的最大数量或者标签/值对和数组组合的最大数量。
  • 如果是 GraphQL,那么这是嵌套选择集的最大级别。

请输入 0 - 4096 范围内的值。 当文档嵌套深度超过最大深度时,将拒绝该文档。 值 0 指示嵌套深度不受限制。 设置为 0 时,操作结果不会返回嵌套深度。

缺省值为 512。

整数
最大宽度 False (可选)解析操作接受的有效内容的最大宽度。
  • 当输入文档为 XML 时,此属性指定元素的最大属性数或元素的最大子元素数。
  • 当输入文档为 JSON 时,此属性指定 JSON 对象上的最大属性数或 JSON 数组中 JSON 项的最大数量。
  • 当输入文档为 GraphQL 时,此属性指定选择集中的最大选择数。

请输入 0 - 65535 范围内的值。 当文档的宽度超过最大宽度时,将拒绝该文档。 值 0 指示宽度不受限制。 设置为 0 时,操作结果不会返回文档的宽度。

缺省值为 4096。

整数
最大名称长度 False (可选)解析操作接受的文档中的最大名称长度(以字节为单位)。
  • 对于 XML,它是标记的名称部分长度。
  • 对于 JSON,它是 JSON 标签/值对的标签部分长度。
  • 对于 GraphQL,它是标识的最大长度,包括字段名称和伪指令名称。

长度包括 XML 中的标记或 JSON 中的引号之间包含的任何空格。 请输入 0 - 8192 范围内的值。 当文档名称长度超过最大长度时,将拒绝该文档。 值 0 指示长度不受限制。 设置为 0 时,操作结果不会返回文档的名称长度。

缺省值为 256。

整数
最大值长度 False (可选)解析操作接受的文档中的最大值长度(以字节为单位)。
  • 对于 XML,这是属性的长度或文本值的长度。
  • 对于 JSON 和 GraphQL,这是字符串值的长度。

长度包括 XML 中的标记或 JSON 中的引号之间包含的任何空格。 请输入 0 - 5368709121 范围内的值。 当文档值长度超过最大长度时,将拒绝该文档。 值 0 指示值长度不受限制。 设置为 0 时,操作结果不会返回文档的值长度。

缺省值为 8192。

整数
唯一名称的最大数量 False (可选)解析操作接受的 JSON 或 XML 文档中唯一名称的最大数量。
  • 对于 XML,这是唯一 XML 本地名称的数量。
  • 对于 JSON,这是唯一 JSON 标签的数量。

请输入 0 - 1048575 范围内的值。 当文档中唯一名称的数量超过最大数量时,将拒绝文档。 值 0 表示唯一名称数不受限制。 设置为 0 时,操作结果不会返回文档中唯一名称的数量。

缺省值为 1024。

整数
唯一前缀的最大数量 False (可选)解析操作接受的文档中唯一 XML 名称空间前缀的最大数量。 此限制将统计为同一名称空间定义的多个前缀,但不统计在输入文档的不同部分中以一个前缀定义的多个名称空间。 请输入 0 - 262143 范围内的值。 当文档中唯一前缀的数量超过最大数量时,将拒绝文档。 值 0 指示唯一前缀数不受限制。 设置为 0 时,操作结果不会返回文档中唯一前缀的数量。

缺省值为 1024。

整数
唯一名称空间的最大数量 False (可选)解析操作接受的唯一 XML 名称空间 URI 的最大数量。 此限制将统计所有 XML 名称空间,而不考虑使用了多少前缀来声明这些名称空间。 请输入 0 - 65535 范围内的值。 当文档中唯一名称空间的数量超过最大数量时,将拒绝文档。 值 0 指示唯一名称空间数不受限制。 设置为 0 时,操作结果不会返回文档中唯一名称空间的数量。

缺省值为 1024。

整数
最大数字长度 False (可选)当值为数字时,JSON 标签/值对的值部分中的最大字节数。 该数字必须是不包含空格的连续字节字符串。 该数字可以包含减号和正指数或负指数。 请输入 0 - 256 范围内的值。 当文档中的数字长度超出最大长度时,将拒绝文档。 值 0 指示数字长度不受限制。 设置为 0 时,操作结果不会返回文档中的数字长度。

缺省值为 128。

整数
解析设置字面值配置 False 已合并到动态对象中的序列化 XML 或 JSON 属性形式的文字串。 这些属性优先于任何现有缺省属性。 字符串
解析设置 URL 引用 False 表示指定上下文的 URL,可从中检索已合并到动态对象中的序列化的 XML 或 JSON 属性。 这些属性优先于任何现有文字或缺省属性。 字符串
要解析的消息 False API 上下文中变量的名称。 变量的 body 字段的内容即策略的输入。 缺省变量名称为 message 字符串
生成的已解析数据的消息 False API 上下文中变量的名称。 变量的 body 字段的内容即解析操作的输出。 已解析文档的解析度量值可以存储在消息的另一个部分中。 缺省变量名称与输入名称相同,因此缺省情况下输出消息将覆盖输入消息。 字符串

使用 YAML 源来设置以下选项。

属性 必需 描述 数据类型
strict-utf8-encoding False 对于 JSON 文档,是否在整个文档中实施严格的 UTF-8 编码。
  • on时,将检查整个文档的有效 UTF-8 编码。
  • 如果设置为 off,那么将仅检查前几个字节以获取正确的编码。 假定文档的其余部分采用相同的编码。

缺省值为 off

布尔型
有关示例,请参见 parse
解析政策限制
  • 解析策略中的 literal 属性不支持变量或上下文参数。 它必须是一个固定的字符串。