映射 策略结构

除了其标题和描述外， 映射 策略还具有以下四个主要部分:

inputs

构成 Map 策略输入的变量的列表。 每个输入都有一个上下文变量，在该变量中找到输入变量，变量在 Map 策略中的名称，变量的内容类型以及变量的定义或定义其结构的模式。

outputs

构成 Map 策略输出的变量列表。 这些包括可在其中找到或应创建输出变量的上下文变量、输出中的变量名称以及变量的定义或定义其结构的模式。

action

包含要按顺序执行的操作的详细信息的数组。 每个条目都包含一个 set 或 create 字段，该字段指定作为操作一部分的一个或多个输出变量。 操作还可以包含 from 字段，此字段指定作为操作一部分的一个或多个输入变量。

每个操作还包含一个 value 字段（在设置或创建输出时）或一个 foreach 字段和一个新的 actions 部分（在第一个操作中嵌套更多操作以在嵌套数组中设置或创建元素时）。

options

可选择以下属性选项：

• 包含空。 如果选中此复选框（缺省选项），那么将在映射策略的输出中包含空的 XML 元素。 如果不想在映射策略的输出中包含空的 XML 元素，那么请清除此复选框。
• 名称空间继承。 如果选中此复选框（缺省选项），那么将继承父元素的 XML 名称空间。 如果想要映射策略使用显式名称空间，请清除此复选框。
• 名称空间直接插入。 如果选中此复选框（缺省选项），那么会将 XML 名称空间插入到第一个使用这些名称空间的文档中。 如果希望在根元素上定义所有名称空间，请取消选中此复选框。
• 解析 XML 输入数据类型。 如果选中此复选框，那么会将模式配置为布尔或数字类型的 XML 元素转换为该数据类型。 如果希望以字符串形式返回所有 XML 元素值，请清除此复选框（缺省选项）。
• 解析 XML 输出 ：如果选中复选框，地图策略将以解析 XML 文档的形式将 XML 输出写入 message.body 。 缺省情况下，XML 将采用 XML 字符串形式输出。 写入到任何其他变量的 XML 输出都始终采用 XML 字符串形式。
• 处理空 XML 元素。 此属性控制 map 策略处理空 XML 元素的输出的方式。 可用选项如下：
  • 字符串（缺省选项）：将空 XML 元素作为空字符串处理。
  • 空：将空 XML 元素作为空值处理。
  • 无: 将忽略数据。
  • 字符串 Badgerfish ：空 XML 元素的值被视为空字符串。 空字符串值将放置到 JSON badgerfish 值属性中。
  • Null Badgerfish（空獾鱼） ：空 XML 元素的值被视为空。 空值将放置到 JSON badgerfish 值属性中。 除非选择允许空值选项，否则不会将此元素映射到 JSON 输出属性。
• 只使用第一个数组元素。 如果选中此复选框，并且在遍历输入的过程中遇到数组，那么仅使用第一个元素。 如果您希望 map 策略使用所有数组元素，请清除此复选框（缺省选项）。
• 解决 API Connect 变量引用问题。 如果取消选中此复选框 (缺省选项) ，那么 map 策略将忽略 map 属性中的 API Connect 变量引用。 如果要解析映射属性中的 API Connect 变量引用，请选中此复选框。
• 允许空值。 如果选中此复选框，那么具有空值的输入属性值将映射到输出文档。 如果您希望 map 策略忽略所有空输入值，请清除此复选框（缺省选项）。
• 优化模式定义。 如果选中此复选框，那么复杂模式类型评估会按经过优化的方式来处理循环类型引用。 请清除此复选框（缺省选项）以按标准方式对这些模式类型进行评估。
• 为数组对象和映射可选对象创建所需的子属性。 如果选中此复选框，那么在下列特定情况下，将在输出中为未映射的必需属性或不存在输入数据的必需属性生成缺省值：
  • 数组由包含一个或多个必需属性的对象组成。
  • 可选的对象具有一个或多个必需的子属性。
  缺省情况下，输出中不存在这些必需属性。 如果选择此选项，那么这些必需属性将显示在输出中。 如果输出模式定义了输出属性的 default 属性，那么将使用指定的缺省值，否则将根据数据类型来分配缺省值，如下所示：

  • 字符串：空字符串 ("")
  • 数字：0
  • 布尔：false
  • 对象：空对象
  • 数组：空数组

  示例 1

  输入数据具有以下对象数组：

  [{“a”: “value1”}, {“a”: “value2", "b": “value3”}]

  输出模式将输出对象定义为具有两个属性 a 和 b，其中 b 是必需的。 map 策略定义以下映射：

  • input.array.a 到 output.array.a
  • input.array.b 到 output.array.b

  如果选中此复选框，b 未映射或者不存在输入数据，那么会为 b 分配空字符串作为缺省值，并且输出如下所示：

  [{“a”: “value1", "b": ""}, {"a": "value2", "b": "value3"}]

  示例 2

  输出模式定义以下结构：

  {"a" : {"b" : {"c" : "value1", "d" : "value2"} } }

  属性 b 是可选的，但 b 中的属性 d 是必需的。

  map 策略将定义到 output.a.b.c 的映射。

  如果选中此复选框，并且 d 未映射，那么会为 d 分配空字符串作为缺省值，并且输出如下所示：

  {"a" : {"b" : {"c" : "value1", "d" : ""} } }

  如果未选中此复选框，那么不会在输出中使用其缺省值来创建这些必需属性。

• 处理空 JSON 数组。 此属性控制 map 策略处理空数组的输出的方式。 可用选项如下：
  • 全部（缺省值）：输出所有空数组，包括空的子数组。
  • 父代：仅输出当前属性的空数组值。 不会尝试此属性的子代映射操作。
  • 无：防止生成任何空输出数组值。
• 启用 JSON 后处理。 选择此复选框以启用映射的 JSON 输出的后处理。 JSON 输出的后处理将使用输出模式以确保属性值的数据类型与模式中定义的数据类型相同。 它还将规范化具有 Badgerfish JSON 语法的输出属性值（这些值是 XML 输入的对象映射的结果）。 缺省情况下清除此复选框，意味着不对映射的 JSON 输出执行后处理。
• 模式定义循环引用限制。 将此属性的值设置为整数值，指定循环模式定义的最大允许迭代次数。

  缺省值为 1，这意味着不遵循循环模式定义。 最大可能值为 5。

• 输入数据日志消息的严重性级别; 此属性指定与输入数据相关的日志消息的严重性级别。 可用选项如下：
  • 错误
  • 警告
  • 信息
• 为失败的映射创建空父对象。 如果映射失败，因为其输入不存在且未配置缺省映射，那么缺省行为是不对输出映射进行任何更改。 选中此复选框可为目标映射的父代创建空对象，从而模拟 IBM® API Management Version 4.0的行为。

  示例

  map 策略将定义到 output.a.b.c 的映射。

  如果存在输入数据，那么输出如下所示：

  {
    "a": {
      "b": {
        "c": "inputvalue"
      }
    }
  }

  如果无输入数据，并且选择为失败的映射创建空的父对象选项，那么输出如下所示：

  {
    "a": {
      "b": {
      }
    }
  }

  将创建属性 a 和 b，但是 b 的值是空对象。

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

以下示例显示了 Map 策略的 inputs 和 outputs 部分。

          inputs:
            input_string:
              schema:
                type: string
              variable: request.parameters.name_in
            input_integer:
              schema:
                type: integer
              variable: request.parameters.age_in
          outputs:
            output:
              schema:
                $ref: '#/definitions/output'
              variable: message.body

通过以下方式使用 actions 部分中包含的字段：

set

如果要将 value 字段的结果分配给 set 字段中指定的输出变量，并替换输出变量的现有值，那么请使用 set 字段。 只能指定一个输出变量，但此变量可以是数组或对象。

create

如果要使用 value 字段的结果为 create 字段中指定的输出数组创建新条目，并将其附加到该数组，请使用 create 字段。 只能指定一个输出变量，但此变量可以是数组或对象。

from

指定哪些变量用作操作中的单个变量或变量数组，其中变量可以是数组或对象。 如果未使用任何输入，那么不会包含 from 字段。

value

使用 GatewayScript 以提供生成输出变量的脚本。 在将单个输入映射到单个输出时，可以省略 value 字段，并在 from 中设置或创建变量以分别作为 set 或 create 中的变量。

default

提供在未提供输入值时应用于输出的静态值或内联变量引用。 有关内联变量引用的信息，请参阅 内联引用。

foreach

如果要针对每个数组条目执行关联的 actions 字段，请指定变量。 该变量可以来自 Map 策略的输入或输出。

actions

使用 actions 字段将操作嵌套在操作中。 因为如果仅应用一次，其他操作可能实现相同的结果，因此它主要与 foreach 字段一起使用。

from、set 和 create

每个操作都必须具有一个 set 或 create 字段，用于指定要对其应用操作的输出变量。 每个操作还可具有一个包含一个或多个条目的 from 字段，这些条目用于指定在操作中使用的输入变量。

set 和 create 字段都用于将值分配给输出变量。

• set 替换输出变量的当前值或创建变量（如果尚不存在）。
• create 将新的数组条目追加到输出变量中。

对于 set 和 create，使用 output_variable_name.variable_name 来指定要使用的已定义输出变量，其中 output_variable_name 是在 映射 策略的输出部分中定义的， variable_name 是指属于输出变量的可选字段。

对于 from，请使用 input_variable_name.variable_name 来指定要使用的已定义输出变量，其中 input_variable_name 是在 Map 策略的输出部分中定义的， variable_name 是指属于输出变量的可选字段。

foreach

使用 foreach 字段以指定一个输入数组，将针对数组的每个条目执行以下 actions 或 value 字段。

例如：

foreach: input.in
actions:
   actions

其中，input.in 是输入变量（数组），而 actions 是与父部分格式相同的一个或多个操作。 在此示例中，将针对 input.in 的每个数组条目，执行一次 actions 中指定的指令。

引用 foreach 字段中指定的输入变量将引用当前迭代所对应的数组条目。

如果在 foreach 字段中使用单个变量而不是数组，那么以下 actions 或 value 字段将应用于或基于单个变量一次，然后循环终止。

通过 from 字段使用名称或者使用前置“$”且包含在括号中的数字来引用变量。 变量从 1 开始编号，其中 1 是数组中的第一个变量，或者当 from 字段仅列出单个变量时，是唯一的变量。 例如：

value: '$(1) + $(2)'

或

value: '$(variable_1) + $(variable_2)'

其中每个变量都是包含在 from 字段中的变量。

在 foreach 循环期间，可以引用 $(0)。 $(0) 变量启动 foreach 空循环，但是在迭代后，将变为与迭代的输出相同，然后可重新引用。 通过此方式，您可以将数组应用于单个值。 例如：

- set: out.total
from: in.input
foreach: in.input
value: '$(0) + $(in.input)'

其中，out.total 由 $(0) 引用。 在每次迭代中，将对 out.total 的当前值和 in.input 的当前数组条目进行求和，并且将 out.total 的值设置为此总和。