配置映射

下图为已完成的 XML Map 映射页面，其中已对屏幕上的每个元素进行了注释（EDI 文档映射类似）。每个数字对应下面的一个描述。

文档或端口名称。
端口类型。
映射的测试状态。值为测试成功、测试有错误或未测试。
切换 XML 流的开启或关闭（默认开启）。开启时，映射引擎会在完成循环后丢弃映射中最顶层 Foreach 当前迭代的文档对象模型 (DOM)。这可以显著提高大型 XML 文档的性能。当映射引擎无法解析映射时，它会自动关闭 XML 流。
在映射的常规视图和紧凑视图之间切换（紧凑视图对于大型模板文件很有帮助）。
切换是否显示或隐藏 XML 属性。
刷新映射。
启动 AI 辅助映射工具。
打开测试映射页面。测试结果显示在 #3 中。（有关更多信息，请参阅测试映射。）
保存映射。
选定的源模板文件。
映射的方向。
选定的目标模板文件。
源端和目标端的搜索栏。
源 XML 的结构。
父节点的名称。
叶节点的名称。
目标文档的结构。
已完成的映射。

了解源和目标

要定义映射，请点击左侧窗格中的节点并将其拖动到右侧窗格中其对应的对象上。选中某个节点后，其连接线为蓝色，其他所有线均为黑色。

在源树或目标树中拖放元素时，拖放节点上的一条或两条蓝线会变暗/处于活动状态，如下图所示。如果两条蓝线都处于活动状态，则被拖动的节点将创建为拖放节点的兄弟。如果只有右侧的蓝线处于活动状态，则被拖动的节点将创建为拖放节点的子级。在下图中，N103 节点从 N104 下方移至 N102 节点的直接兄弟，因此两条蓝线均突出显示。

要移除映射，请将鼠标悬停在映射的一端，然后点击移除映射。完成映射定义后，点击保存。

映射节点

父节点和叶节点定义 XML 数据的层次结构，其中父节点将相关元素分组，叶节点表示要映射的实际数据值。

父节点：XML 映射树中包含叶元素但没有值的节点。父节点类似于 TPMC 中的表节点。
叶节点：包含值但没有子元素的节点。叶节点类似于 TPMC 中的列节点。

以下部分详细介绍了父节点和叶节点选项。

父节点

XML 父元素

如前所述，映射编辑器中的树有两种类型的节点：

父节点 有子节点但没有值。
叶节点 有值但没有子节点。

源中的父节点只能拖动到目标中的父节点上。将源父节点拖动到目标父节点上会在源节点和目标节点之间建立 Foreach 关系。这意味着源元素的每次出现都会生成一个对应的目标元素，包括目标元素的所有子元素。一旦建立了 Foreach 关系，目标中就会出现一个 xpath，如下图所示。输入 XML 中此路径上的元素会生成输出节点及其子节点的新实例。换句话说，Foreach 关系指示映射引擎循环遍历源中的给定 xpath，并为找到的每个元素生成映射的目标结构。目标树视图中的 xpath 就是映射引擎循环遍历的 xpath。

虚拟循环

虚拟循环是一种特殊节点，可以将其添加到目标结构中，但该节点不会直接出现在输出 XML 中。它提供了一个机会，可以实现影响输出中其他（非虚拟）节点的外观和/或值的逻辑。它的功能与父节点之间的 Foreach 映射相同，只是父节点不会出现在输出 XML 中。这允许您将源中的重复元素展平为目标中的非层次结构。通过示例更容易理解这一点。以以下输入 XML 为例：

<!-- example input -->
<Items>
  <DataReading>
    <Temperature>212.5</Temperature>
  </DataReading>
  <DataReading>
    <Temperature>9.2</Temperature>
  </DataReading>
  <DataReading>
    <Temperature>5.1</Temperature>
  </DataReading>
</Items>

这需要映射到包含所有 DataReading 数据的平面结构：

<!-- desired output -->
<Items>
  <OutputData>
    <TemperatureReading>212.5</TemperatureReading>
    <TemperatureReading>9.2</TemperatureReading>
    <TemperatureReading>5.1</TemperatureReading>
  </OutputData>
</Items>

可以通过与目标中与源中每个 DataReading 元素对应的循环节点建立 Foreach 关系来实现此目的：

如果在 DataReading 和 OutputData 之间建立 Foreach 关系，则结果中会重复 OutputData 元素。循环节点可以避免这种层级重复，并将值展平到单个 OutputData 元素中。要添加上例中所示的循环节点，请按以下步骤操作：

右键单击 TemperatureReading 节点，或单击省略号，然后选择添加节点 > 添加循环。为循环指定一个有意义的名称，然后点击复选标记进行保存。
将源 DataReading 节点拖到循环上以创建 Foreach 关系。
将源 Temperature 节点映射到目标 TemperatureReading 节点。

虚拟条件

虚拟条件基于共享条件将输出元素组合在一起。如果条件为真，则条件节点的所有子节点都会出现在输出中；如果条件为假，则不会出现。这在功能上相当于将相同的条件分别添加到每个单独的节点。对于影响多个不同节点的条件，通常更方便的做法是创建一个条件节点，然后将所有相关的输出节点设为该条件节点的子节点。要创建条件虚拟节点，请按以下步骤操作：

右键单击目标节点或单击省略号，然后选择添加节点 > 添加条件。
单击新条件旁边的漏斗图标以创建条件规则。有关详细信息，请参阅使用条件编辑器。

叶节点

XML 叶元素

将源叶节点拖放到目标叶节点上，会指示映射引擎使用源元素的值填充目标元素。拖放到目标节点后，目标树视图中将显示读取值的 xpath，如下图所示。

目标树视图中显示的 xpath 是绝对或相对的。绝对 xpath 以斜杠 (/) 开头，描述源中的完整 xpath，从文档的根开始。相对 xpath 不以斜杠开头，它们相对于父节点中设置的 Foreach 循环。相对 xpath 可以相对于多个 Foreach 循环（只要元素有多个父元素，并且每个父元素都映射了 Foreach 关系）。要找到任何给定相对 xpath 的绝对 xpath，只需连接每个父级的 Foreach xpath，从文档顶部开始，直到到达当前节点。

XML 属性

除了元素值之外，要使用 XML 属性，请确保已启用映射页面顶部的显示属性设置（

）。启用后，编辑器将显示检测到的作为其所属元素子元素的所有属性。所有 XML 属性名称都以 @ 为前缀（@ 符号在 XML 元素名称中无效）。此字符仅用于显示，在读取或写入属性时会被删除。

从源读取 XML 属性

启用显示属性开关后，XML 源中的任何属性都会在映射编辑器中显示为节点。您可以像其他节点一样将这些值拖放到目标节点上。节点显示 @ 前缀，表示它们是 XML 属性，而不是 XML 元素，如下图所示。

在目标中写入 XML 属性

包含 XML 属性的目标模板会将属性节点显示为其所属元素的子节点，并且这些节点可以像任何其他值一样进行映射。要向目标节点添加新属性，请右键单击或点击节点上的省略号，然后选择添加节点 > 添加属性。

属性名称始终以 @ 前缀开头（此字符不包含在输出 XML 中）。

标头

标头节点允许您将值映射为映射输出消息的标头。这些标头节点不包含在输出 XML 中，但会作为元数据消息标头添加到输出消息中。这些标头在整个流程中与消息保持一致，并且任何下游端口都可以根据需要引用它们的值，从而可以轻松跟踪数据在应用程序中的进度。标头节点会自动添加到节点值编辑器中的消息头选项卡中。要添加标头节点，请右键单击或点击现有节点上的省略号，然后选择添加 > 添加标头。标头节点不会添加到跟踪头。您可以通过点击节点上的省略号并选择添加跟踪将非标头目标节点添加到跟踪头。有关更多信息，请参阅消息头。

代码脚本

代码脚本虚拟节点提供了编写自定义 Script 的机会，这些脚本无需返回输出值。通常，这些节点使用变量或特殊的 _map 项来存储稍后需要在映射中引用但不需要在当前上下文中输出的值。例如，映射项部分中描述的场景就非常适合使用虚拟代码脚本节点。订单项成本总和需要在计算该值的 Foreach 循环之外作为输出返回。因此，Foreach 循环中的虚拟代码脚本节点可以计算该值但不输出。然后，该值可以在循环之外的非虚拟节点中作为输出引用。要创建代码脚本虚拟节点，请按以下步骤操作：

右键单击目标节点或点击省略号，然后选择添加节点 > 添加代码脚本。
输入脚本名称。
提供脚本。编辑器会在您输入时验证表达式，因此如果您看到无效脚本消息，则表示存在语法问题。完成后，点击添加脚本。

变量节点

在映射中的某个位置设置变量，并在之后的映射中再次引用这些变量会很有用。有关详细信息和示例，请参阅变量。

节点选项

要处理单个节点，请将鼠标悬停在节点上，然后右键单击或单击省略号以从一组附加选项中进行选择。选项会根据正在处理的节点类型而有所不同。本节介绍处理父节点、叶节点或文档节点时可用的选项。有关这些节点类型的详细信息，请参阅表节点和列节点。

重命名节点 允许更改节点的名称。
编辑 XPath 允许编辑节点 XPath（仅限已映射为 Foreach 的元素）。
删除节点 允许您从文档中删除节点。
添加节点
- 添加兄弟节点 可在所选节点的同一级别添加一个节点。
- 添加属性 可为所选节点添加属性。
- 添加子节点 会将一个节点添加为所选节点的子节点。
- 添加标头 会创建一个标头节点，您可以将值映射到该标头节点。映射的值不会包含在输出文件中，但会作为标头添加到映射输出消息中。
- 添加循环 会在所选节点上方创建一个循环节点，该节点将嵌套在循环节点中。有关更多信息，请参阅映射循环。
- 添加条件 会打开条件编辑器，您可以在其中添加条件，以便只有当条件为真时，数据才会更新插入到目标。
- 添加代码脚本 会创建一个新的脚本节点作为目标元素的同级节点。使用添加脚本窗口命名脚本并提供自定义 Script。
- 添加变量 会在所选节点下方创建一个变量节点。有关更多信息，请参阅变量。
剪切节点 将从当前位置剪切所选节点。
复制节点 复制所选节点。
粘贴为子节点 将剪切或复制的节点粘贴为所选节点的子节点。
添加跟踪 将跟踪头添加到映射中。启用跟踪的节点会显示指南针图标。

还可以使用编辑节点打开编辑节点值页面。请参阅使用节点值编辑器。

AI 辅助映射

在实例上设置 AI 设置并上传或设置源和目标模板文件后，可以使用任何受支持的大语言模型 (LLM) 来协助构建映射。此功能通过提供智能映射建议解决了映射配置难题，从而显著简化了创建精确数据转换的过程。

使用的 LLM 必须支持结构化输出。已确认以下模型提供可靠的结构化输出：

Claude: Opus 4.6
Gemini: gemini-3-pro
Grok: grok-4-fast-non-reasoning
Ollama Cloud: glm-4.6
OpenAI: gpt-5.4

要让 AI 生成整个映射，请点击页面顶部的

图标。如果尝试使用不支持结构化输出的模型，该图标将被禁用。或者，可以让 AI 在节点级别生成映射。右键单击源或目标端的父节点或使用省略号，选择 AI 辅助映射，然后选择以下选项之一：

映射节点
映射子节点
节点和子节点

AI 生成映射后，可以根据需要进行调整。

如果在 XML Map 端口上使用此功能，可以自定义应用程序用于创建映射的用户提示和系统提示。有关详细信息，请参阅 XML Map 高级设置。

映射循环

创建父节点映射会在源节点和目标节点之间建立 Foreach 关系。这意味着源元素的每次出现都会生成一个对应的目标元素，包括目标元素的所有叶节点。创建叶节点映射会指示映射引擎使用源元素的值填充目标元素。先映射父节点（Foreach 循环），然后再映射叶节点。建立循环关系需要了解源和目标 XML 结构：每当源中的重复元素应导致目标中的重复元素时，这些元素都应在 Foreach 关系中一起映射。在 Foreach 循环中，叶元素 xpath 是相对于映射的 Foreach xpath 的。作为一个非常简单的示例，请考虑以下源和目标 XML，其中嵌套 XML 结构应转换为扁平 XML 结构：

<Source>
  <customer>
    <name>
      <first></first>
      <last></last>
    </name>
    <address>
      <streetLine1></streetLine1>
      <streetLine2></streetLine2>
      <city></city>
      <state></state>
    </address>
  </customer>
</Source>

<Destination>
  <customerInfo>
    <firstName></firstName>
    <lastName></lastName>
    <addressLine1></addressLine1>
    <addressLine2></addressLine2>
    <city></city>
    <state></state>
  </customerInfo>
</Destination>

源中每次重复 customer 元素，目标中都会生成一个 customerInfo 元素，因此这些父元素应该映射在一起，形成 Foreach 关系。这样，每个叶元素的映射就很简单了：

请注意，叶元素的 xpath 是相对于父元素中的 xpath（定义 Foreach 关系的 xpath）。

映射多个循环

映射通常需要在同一文档中建立多个 Foreach 循环关系。映射循环的原则保持不变：源文档中任何重复的父元素，如果在目标文档中应该生成重复的元素，都应该映射为循环。先映射外层循环，再映射内层循环（换句话说，从结构的顶部开始向下映射）。所有循环关系都应在映射任何叶元素之前进行映射。举一个常见的例子，考虑将传入的采购订单报告映射到目标数据库。此类映射包含两个可能重复的不同元素结构，因此每个结构都需要一个 Foreach 关系：(1) 单个报告可能包含多个单独的订单，以及 (2) 单个订单可能包含多个行项目。

示例输入

源模板结构可能如下所示：

<OrderReport>
  <WebOrder>
    <CustomerName>John Doe</CustomerName>
    <PurchaseDate>12/21/22</PurchaseDate>
    <Line>
      <ItemName>Hammer</ItemName>
      <ItemCost>1500</ItemCost>
      <ItemQuantity>1</ItemQuantity>
      <ItemDescription>Standard claw hammer</ItemDescription>
    </Line>
    <Line>
      <ItemName>Nail</ItemName>
      <ItemCost>10</ItemCost>
      <ItemQuantity>20</ItemQuantity>
      <ItemDescription>Ten penny nails</ItemDescription>
    </Line>
    <Subtotal>1700</Subtotal>
    <TaxPercent>4</TaxPercent>
  </WebOrder>
</OrderReport>

为简洁起见，此示例仅包含一个 WebOrder 元素，但映射应该处理同一个 OrderReport 中包含多个 WebOrder 部分的情况。

示例输出

此映射的输出应与数据库插入的 XML 模型匹配。数据库插入的 XML 模型由数据库端口（例如 MySQL、SQLite 和 CData 端口）自动创建，数据库端口中的模板文件部分介绍了如何在 XML Map 端口中将这些 XML 模型用作模板文件。正确的数据库设计建议将数据插入两个单独的表中，一个用于 Orders，一个用于 Line Items。为此方法生成合适的输入映射可以生成如下模板结构：

<Items>
  <Order>
    <FirstName></FirstName>
    <LastName></LastName>
    <Date></Date>
    <OrderLine>
      <Name></Name>
      <Desc></Desc>
      <Price></Price>
      <Amount></Amount>
    </OrderLine>
  </Order>
</Items>

在此示例中，Order 元素表示向 Orders 表中插入数据，而 OrderLine 元素表示向 Line Items 表中插入数据。生成的模板仅包含一个代表每个表的元素，但映射期间建立的 Foreach 关系可确保创建适当数量的插入数据。 Order 的其他子元素（FirstName、LastName、Date）表示 Orders 表中的列，而 OrderLine 的子元素（SKU、Price 等）表示 Line Items 表中的列。

建立循环关系

源中的 WebOrder 元素应该会在 Orders 表中插入一条新数据，因此应将其拖放到目标中的 Order 元素上。同样，源中的 Line 元素应该会在 Line Items 表中插入一条新数据，因此应将其拖放到目标中的 OrderLine 元素上。建立这两个 Foreach 关系后，映射编辑器应如下所示：

建立循环关系并删除所有不必要的目标元素后，可以映射叶元素以填充目标值：

不必要的父节点

建立 Foreach 关系时，源文件和目标文件中只需存在一个映射元素实例。换句话说，Foreach 关系负责确保输出元素的数量与相应输入元素的数量匹配。为了更清楚地说明这一点，假设在映射循环示例中，源文件（输入 XML 的模板）包含多组 customer 元素组。在 customer（源）和 customerInfo（目标）之间建立单个 Foreach 关系，可确保 customerInfo 元素组的数量与任何输入文件中的 customer 元素组数量匹配。由于只需一个 customer 元素即可建立此 Foreach 关系，因此所有其他 customer 元素与映射无关，可以忽略或删除。同样，如果上例中的目标文件包含多个 customerInfo 元素，则应删除除一个之外的所有元素。customer 和 customerInfo 之间的 Foreach 关系确保在 XML 输出中出现适当数量的 customerInfo 元素组。

测试映射

使用测试映射按钮检查映射是否按预期工作。测试会使用源文件中的值填充目标元素，如下所示：

如果测试失败，目标窗格将提供失败的解释。

映射最佳实践

Foreach 循环是映射目标文件中重复元素的强大工具。但是，遵循以下最佳实践至关重要，以确保功能正常并避免性能问题：

使用大型 XML 文件时，避免将整个文件映射为 Foreach 循环。这种映射方式会指示映射引擎将整个文件加载到内存中，这可能会导致较长的处理时间。
相反，最佳做法是牢记完整的源文档结构，并且只为已知重复的元素创建 Foreach 关系（如上文建立循环关系中所述）。这种做法可以最大限度地减少与 Foreach 关系相关的性能影响。

入门指南

工作流

EDI 交易伙伴管理控制台

端口

映射

操作指南

脚本编写

软件许可和第三方版权

了解源和目标

映射节点

父节点

XML 父元素

虚拟循环

虚拟条件

叶节点

XML 叶元素

XML 属性

从源读取 XML 属性

在目标中写入 XML 属性

标头

代码脚本

变量节点

节点选项

AI 辅助映射

映射循环

映射多个循环

示例输入

示例输出

建立循环关系

不必要的父节点

测试映射

映射最佳实践

​了解源和目标

​映射节点

​父节点

​XML 父元素

​虚拟循环

​虚拟条件

​叶节点

​XML 叶元素

​XML 属性

从源读取 XML 属性

在目标中写入 XML 属性

​标头

​代码脚本

​变量节点

​节点选项

​AI 辅助映射

​映射循环

​映射多个循环

​示例输入

​示例输出

​建立循环关系

​不必要的父节点

​测试映射

​映射最佳实践

了解源和目标

映射节点

父节点

XML 父元素

虚拟循环

虚拟条件

叶节点

XML 叶元素

XML 属性

标头

代码脚本

变量节点

节点选项

AI 辅助映射

映射循环

映射多个循环

示例输入

示例输出

建立循环关系

不必要的父节点

测试映射

映射最佳实践