解析

使用 解析 策略来控制输入文档的解析。 当输入文档为 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 源文件中配置策略的详细信息,请阅parse。

关于 解析

通过解析策略,您可以使用以下方法按优先顺序递增来检索解析设置。
  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 的 Invoke 策略》 ( API Gateway )以及《配置 DataPower Gateway 的 Invoke 策略》( 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 字段的内容即解析操作的输出。 已解析文档的解析度量值可以存储在消息的另一个部分中。 缺省变量名称与输入名称相同,因此缺省情况下输出消息将覆盖输入消息。 字符串
Draft comment: slaflamm@us.ibm.com
For 10.0.5.3, the strict UTF-8 option is supported only in the YAML, not in the APIM UI. When it is added to the UI, remove the following table and add strict UTF-8 to the properties table.

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

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

默认值为 off.

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