使用 Visual Studio Code 创建映射以转换 Azure 逻辑应用中的数据

适用于：Azure 逻辑应用（标准）

若要交换 Azure 逻辑应用工作流中具有不同 XML 或 JSON 格式的消息，必须将数据从一种格式转换为另一种格式，尤其是在源架构和目标架构结构之间存在差距时。 数据转换有助于弥合这些差距。 对于此任务，需要创建一个映射，用于定义源架构和目标架构中的数据元素之间的转换。

若要直观地创建和编辑映射，可以在标准逻辑应用项目的上下文中将 Visual Studio Code 与 Azure 逻辑应用（标准）扩展配合使用。 Data Mapper 工具为使用拖放手势的 XSLT 映射和转换提供了统一体验、用于创建表达式的预生成函数库，以及手动测试在工作流中创建和使用的映射的方法。

创建映射后，可以直接从逻辑应用项目中的工作流或 Azure 门户中的工作流调用该映射。 对于此任务，可以在工作流中使用名为使用 Data Mapper XSLT 进行转换的 Data Mapper Operations 操作。

本操作指南介绍如何创建空白数据映射、选择源架构和目标架构、选择架构元素以开始映射、创建各种映射、保存和测试映射，以及从逻辑应用项目中的工作流调用映射。

限制和已知问题

• Data Mapper 目前仅适用于在 Windows 操作系统上运行的 Visual Studio Code。

• Data Mapper 目前仅在 Visual Studio Code 中可用，不适用于 Azure 门户，并且仅在标准型逻辑应用项目中可用，不适用于消耗型逻辑应用项目。

• Data Mapper 目前不支持逗号分隔值 (.csv) 文件。

• Data Mapper 的“代码视图”窗格当前为只读。

• 映射布局和项位置目前是自动的，并且是只读的。

• 若要使用 Data Mapper 工具调用创建的映射，只能使用名为使用 Data Mapper XSLT 进行转换的 Data Mapper Operations 操作。 对于由任何其他工具创建的映射，请使用名为转换 XML 的 XML Operations 操作。

• 若要使用通过 Data Mapper 工具在 Azure 门户中创建的映射，必须将它们直接添加到标准型逻辑应用资源。

先决条件

• 使用 Visual Studio Code 和 Azure 逻辑应用（标准）扩展来创建标准型逻辑应用工作流。

  注意

  以前独立的 Data Mapper 扩展现已与 Azure 逻辑应用（标准）扩展合并。 为了避免冲突，安装或更新 Azure 逻辑应用（标准）扩展时，应删除任何现有版本的 Data Mapper 扩展。 安装或更新扩展后，请重启 Visual Studio Code。

• 描述要转换的数据类型的源和目标架构文件。 这些文件可以具有以下格式之一：

  • 具有 .xsd 文件扩展名的 XML 架构定义文件
  • 具有 .json 文件扩展名的 JavaScript 对象表示法文件

• 包含至少具有一个触发器的有状态或无状态工作流的标准型逻辑应用项目。 如果没有项目，请按照 Visual Studio Code 中的以下步骤操作：

  1. 连接到 Azure 帐户（如果尚未连接）。

  2. 创建本地文件夹、本地标准型逻辑应用项目以及有状态或无状态工作流。 在创建工作流期间，选择“在当前窗口中打开”。

• 如果要测试映射并检查转换是否按预期工作，请对输入数据进行采样。

• 若要使用 Run XSLT 函数，XSLT 代码片段必须存在于使用 .xml 或 .xslt 文件扩展名的文件中。 必须将 XSLT 代码片段放入以下本地项目文件夹结构的 InlineXslt 文件夹中：Artifacts > DataMapper > Extensions > InlineXslt。 如果此文件夹结构不存在，请创建缺少的文件夹。

创建数据映射

1. 在 Visual Studio Code 左侧菜单上，选择 Azure 图标。

2. 在 Azure 窗格中的“Data Mapper”部分下，选择“创建新数据映射”。

   

3. 提供数据映射的名称。

4. 按照以下步骤指定源架构和目标架构：

   1. 在映射图面上，选择“添加源架构”。

      

   2. 在打开的“配置”窗格中，选择“新增>浏览”。

   3. 查找并选择源架构文件，然后选择“添加”。

      如果源架构未显示在“打开”窗口中，请从文件类型列表中，将“XSD 文件 (*.xsd)”更改为“所有文件 (*.*)”。

      映射图面现在显示源架构中的数据类型。 对于本指南中的示例，

   4. 在映射图面上，选择“添加目标架构”。

   5. 在打开的“配置”窗格中，选择“新增>浏览”。

   6. 查找并选择目标架构文件，然后选择“添加”。

      如果目标架构未显示在“打开”窗口中，请从文件类型列表中，将“XSD 文件 (*.xsd)”更改为“所有文件 (*.*)”。

      映射图面现在显示目标架构中的数据类型。

   或者，还可以将源和目标架构文件本地添加到“生成工件/架构”文件夹中的逻辑应用项目，以让它们显示在 Visual Studio Code 中。 在这种情况下，可以通过选择“选择现有”而不是“新增”，在“配置”窗格上的 Data Mapper 工具中指定源和目标架构。

   完成后，你的映射将如以下示例所示：

   

下表描述了可能出现在架构中的数据类型：

符号	类型	更多信息
	Array	包含项或重复项节点
	二进制
	Bool	仅 True 或 false
	Complex	具有子属性的 XML 对象，类似于对象 JSON 类型
	DateTime
	十进制
	Integer	仅整数
	Null	不是数据类型，但在存在错误或无效类型时显示
	Number	JSON 整数或十进制
	对象	具有子属性的 JSON 对象，类似于复杂 XML 类型
	字符串

导航映射

若要在映射上移动，可以使用以下选项：

• 若要四处平移，请在映射图面周围拖动指针。 或者，按住鼠标滚轮，同时移动鼠标或轨迹球。

• 移动到映射的下一层后，映射左下角会出现一个导航栏，可在其中从以下选项中进行选择：

  

  选项	替代手势
  缩小	在映射图面上，按 Shift + 双击选择。 -或- 鼠标滚轮向下滚动。
  放大	在映射图面上，双击选择。 - 或 - 鼠标滚轮向上滚动。
  缩放到合适大小	无
  显示（隐藏）微型映射	无

• 若要在映射上向上移动一个级别，请在映射顶部的痕迹导航路径上，选择上一个级别。

选择要映射的目标元素和源元素

1. 在映射图面上，从右侧开始，在目标架构区域中，选择要映射的目标元素。 如果需要的元素是父元素的子元素，请首先查找并展开父元素。

2. 现在，在左侧的源架构区域中，选择“选择元素”。

3. 在显示的“源架构”窗口中，选择要在映射上显示的一个或多个源元素。

   • 若要包含父级和直接子级，请打开父级的快捷菜单，然后选择“添加子级”。

   • 若要包括父级和该父级的所有子级（包括任何子父级），请打开顶级父级的快捷菜单，然后选择“添加子级（递归）”。

4. 完成后，可以关闭源架构窗口。 总是可以稍后添加更多的源元素。 在映射的左上角，选择“显示源架构”（）。

在元素之间创建直接映射

若要在源架构和目标架构中具有相同类型的元素之间进行直接转换，请执行以下步骤：

1. 若要查看创建映射时代码中发生的情况，请在映射的右上角选择“显示代码”。

2. 如果尚未选择，请在映射上选择目标元素，然后选择要映射的源元素。

3. 将指针移到源元素上，以便同时显示圆圈和加号 (+)。

   

4. 将线条拖到目标元素上，使线条连接到显示的圆圈。

   

   现已在两个元素之间创建了直接映射。

   

   代码视图窗口反映了创建的映射关系：

   

在元素之间创建复杂的映射

对于源架构和目标架构中的元素之间的更复杂的转换（例如要合并的元素或具有不同数据类型的元素），可以使用一个或多个函数执行该转换的任务。

下表列出了可用的函数组和可以使用的示例函数：

Group	示例函数
集合	Average、Count、Direct Access、Distinct values、Filter、Index、Join、Maximum、Minimum、Reverse、Sort、Subsequence、Sum
转换	To date、To integer、To number、To string
日期和时间	加天数
逻辑比较	Equal、Exists、Greater、Greater or equal、If、If else、Is nil、Is null、Is number、Is string、Less、Less or equal、Logical AND、Logical NOT、Logical OR、Not equal
数学	Absolute、Add、Arctangent、Ceiling、Cosine、Divide、Exponential、Exponential (base 10) 、Floor、Integer divide、Log、Log (base 10) 、Module、Multiply、Power、Round、Sine、Square root、Subtract、Tangent
字符串	Code points to string、Concat、Contains、Ends with、Length、Lowercase、Name、Regular expression matches、Regular expression replace、Replace、Starts with、String to code-points、Substring、Substring after、Substring before、Trim、Trim left、Trim right、Uppercase
实用工具	Copy、Error、Execute XPath、Format date-time、Format number、Run XSLT

在映射上，函数的标签如以下示例所示，并根据函数组进行了颜色编码。 在函数名称的左侧，将显示函数的符号。 在函数名称的右侧，将显示函数输出的数据类型的符号。

添加没有映射关系的函数

本节中的示例将源元素类型从 String 类型转换为与目标元素类型匹配的 DateTime 类型。 此示例使用 To date 函数，它接受单个输入。

1. 若要查看创建映射时代码中发生的情况，请在映射的右上角选择“显示代码”。

2. 如果尚未选择，请在映射上选择目标元素，然后选择要映射的源元素。

3. 在映射的左上角，选择“显示函数”（）。

   

4. 从打开的函数列表中，找到并选择要使用的函数，这样会将函数添加到映射。 如果函数在映射上不可见，请尝试在映射图面上缩小。

   此示例选择 To date 函数。 还可以使用相同的方法查找和选择任何自定义函数。 有关详细信息，请参阅创建自定义函数。

   

   注意

   如果在向映射添加函数时不存在或未选择映射线，则函数将在映射上显示，但与任何元素或其他函数断开连接，例如：

   

5. 展开函数形状以显示函数的详细信息和连接点。 若要展开函数形状，请在形状内部选择。

6. 将函数连接到源元素和目标元素。

   1. 在源元素和函数的左边缘之间拖动并绘制一条线。 可以从源元素或函数开始。

      

   2. 在函数的右边缘和目标元素之间拖动并绘制一条线。 可以从目标元素或函数开始。

      

7. 在函数的“属性”选项卡上，确认或编辑要使用的输入。

   

   对于某些数据类型（如数组），转换的范围也可能显示为可用。 此范围通常是直接元素（如数组），但在某些情况下，范围可能存在于直接元素之外。

   代码视图窗口反映了创建的映射关系：

   

例如，若要循环访问数组项，请参阅创建数组之间的循环。 若要在元素的值满足条件时执行任务，请参阅在元素之间添加条件。

将函数添加到现有映射关系

当源元素和目标元素之间已存在映射关系时，可以按照以下步骤添加函数：

1. 在映射上，选择所创建的映射的线条。

2. 将指针移到所选线条上，然后选择出现的“插入函数”加号 (+)，例如：

   

3. 从打开的函数列表中，找到并选择要使用的函数。

   函数将出现在映射上，并在源元素和目标元素之间自动连接。

添加具有多个输入的函数

本部分中的示例连接多个源元素类型，以便可以将结果映射到目标元素类型。 此示例使用 Concat 函数，它接受多个输入。

1. 若要查看创建映射时代码中发生的情况，请在映射的右上角选择“显示代码”。

2. 如果尚未选择，请在映射上选择目标元素，然后选择要映射的源元素。

3. 在映射的左上角，选择“显示函数”（）。

   

4. 从打开的函数列表中，找到并选择要使用的函数，这样会将函数添加到映射。 如果函数在映射上不可见，请尝试在映射图面上缩小。

   此示例选择了 Concat 函数：

   

   注意

   如果在向映射添加函数时不存在或未选择映射线，则函数将在映射上显示，但与任何元素或其他函数断开连接。 如果函数需要配置，则函数的右上角会显示一个红点，例如：

   

5. 展开函数形状以显示函数的详细信息和连接点。 若要展开函数形状，请在形状内部选择。

6. 在函数信息窗格中的“属性”选项卡上的“输入”下，选择要用作输入的源数据元素。

   此示例选择 FirstName 和 LastName 源元素作为函数输入，它们会自动在映射上添加相应的连接。

   

7. 若要完成映射，请在函数的右边缘和目标元素之间拖动并绘制一条线。 可以从目标元素或函数开始。

   

   代码视图窗口反映了创建的映射关系：

   

在数组之间创建循环

如果源架构和目标架构包含数组，则可以创建循环映射关系来循环访问这些数组中的项。 本节中的示例循环访问 Employee 源数组和 Person 目标数组。

1. 若要查看创建映射时代码中发生的情况，请在映射的右上角选择“显示代码”。

2. 在映射上的目标架构区域中，选择要映射的目标数组元素和目标数组项元素。

3. 在映射上的目标架构区域中，展开目标数组元素和数组项。

4. 在源架构区域中，将源数组元素和数组项元素添加到映射。

5. 在源元素和目标元素之间创建直接映射。

   

   首次在匹配的数组项对之间创建映射关系时，会在父数组级别自动创建映射关系。

   

   代码视图窗口反映了创建的映射关系：

   

6. 继续映射其他数组元素。

   

设置条件和任务以在元素之间执行

若要添加计算条件并在满足条件时执行任务的映射关系，可以使用多个函数，例如 If 函数、比较函数（如 Greater）和要执行的任务（如 Multiply）。

本部分中的示例使用以下函数计算当购买数量超过 20 件商品时要应用的折扣：

• Greater：检查商品数量是否大于 20。
• If：检查 Greater 函数是否返回 true。
• Multiply：通过将商品价格乘以 10% 再乘商品数量来计算折扣。

1. 若要查看创建映射时代码中发生的情况，请在映射的右上角选择“显示代码”。

2. 如果尚未选择，请在映射上选择目标元素，然后选择要映射的源元素。

   此示例选择以下元素：

   

3. 在映射的左上角，选择“显示函数”（）。

4. 将以下函数添加到映射：Greater、If 和 Multiply

5. 展开所有函数形状以显示函数详细信息和连接点。

6. 按如下所示连接源元素、函数和目标元素：

   • 源架构的 ItemPrice 元素到目标架构的 ItemPrice 元素
   • 源架构的 ItemQuantity 元素到 Greater 函数的 Value 字段
   • Greater 函数的输出到 If 函数的 Condition 字段
   • 源架构的 ItemPrice 元素到 Multiply 函数的 Multiplicand 0* 字段
   • Multiply 函数的输出到 If 函数的 Value 字段
   • If 函数的输出到目标架构的 ItemDiscount 元素

   注意

   在 If 函数中，函数名称的右侧显示 ANY 一词，表示可以将输出值分配给任何项。

7. 在以下函数的“属性”选项卡上，指定以下值：

   函数	输入参数和值
   更强大	- Value #1：名为 ItemQuantity 的 的源元素 - Value #2：20
   乘	- Multiplicand #1：名为 ItemPrice 的源元素 - Multiplicand #2：.10
   If	- Condition：is-greater-than(ItemQuantity,20) - Value：multiply(ItemPrice, .10)

   以下映射显示了完成的示例：

   

   代码视图窗口反映了创建的映射关系：

   

保存映射

完成后，在映射工具栏上选择“保存”。

Visual Studio Code 将你的映射保存为以下工件：

• 一个 <your-map-name>.yml 文件，在 Artifacts>MapDefinitions 项目文件夹中
• 一个 <your-map-name>.xslt 文件，在 Artifacts>Maps 项目文件夹中

随时生成 XSLT 文件

若要随时生成 <your-map-name>.xslt 文件，请在映射工具栏上选择“生成 XSLT”。

测试映射

若要确认转换是否按预期工作，需要示例输入数据。

1. 在测试映射之前，请务必生成最新的 <your-map-name.xslt> 文件。

2. 在映射工具栏上，选择“测试”。

3. 在“测试映射”窗格的“输入”窗口中，粘贴示例输入数据，然后选择“测试”。

   测试窗格会切换到“输出”选项卡，并显示测试的状态代码和响应正文。

从项目中的工作流调用映射

1. 在 Visual Studio Code 左侧菜单上，选择“资源管理器”（文件图标）以查看逻辑应用项目结构。

2. 展开具有你的工作流名称的文件夹。 从 workflow.json 文件的快捷菜单上，选择“打开设计器”。

3. 在工作流设计器中，按照常规步骤添加名为“使用 Data Mapper XSLT 进行转换”的 Data Mapper Operations 内置操作。

4. 在设计器中，选择“使用 Data Mapper XSLT 进行转换”操作。

5. 在出现的“操作信息”窗格中，指定“内容”值，并将“映射源”设置为“逻辑应用”。 从“映射名称”列表中，选择要使用的映射文件 (.xslt)。

   

   若要在 Azure 门户中使用相同的“使用 Data Mapper XSLT 进行转换”操作，必须将映射添加到标准型逻辑应用资源。

创建自定义函数

若要自行创建可与 Data Mapper 工具结合使用的函数，请执行以下步骤：

1. 创建一个 XML (.xml) 文件，为它指定一个描述函数用途的有意义的名称。

   如果有多个相关函数，则可以为这些函数使用同一个文件。 尽管可以使用任何文件名，但有意义的文件名或类别可以使函数容易识别、查找和发现。

2. 在 XML 文件中，必须为函数定义使用以下架构：

   <?xml version="1.0" encoding="utf-8"?>
   <xs:schema attributeFormDefault="unqualified" elementFormDefault="qualified" xmlns:xs="http://www.w3.org/2001/XMLSchema">
      <xs:element name="customfunctions">
         <xs:complexType>
            <xs:sequence>
               <xs:element maxOccurs="unbounded" name="function">
                  <xs:complexType>
                     <xs:sequence>
                        <xs:element maxOccurs="unbounded" name="param">
                           <xs:complexType>
                               <xs:attribute name="name" type="xs:string" use="required" />
                               <xs:attribute name="as" type="xs:string" use="required" />
                           </xs:complexType>
                        </xs:element>
                        <xs:any minOccurs="0" />
                     </xs:sequence>
                     <xs:attribute name="name" type="xs:string" use="required" />
                     <xs:attribute name="as" type="xs:string" use="required" />
                     <xs:attribute name="description" type="xs:string" use="required" />
                  </xs:complexType>
               </xs:element>
            </xs:sequence>
         </xs:complexType>
      </xs:element>
   </xs:schema>
   

   每个名为“function”的 XML 元素都实现了一个具有少量其他属性的 XSLT3.0 样式函数。 Data Mapper 函数列表包括函数名称、说明、参数名称和参数类型。

   以下示例演示 SampleFunctions.xml 文件的实现：

   <?xml version="1.0" encoding="utf-8" ?>
   <xs:schema attributeFormDefault="unqualified" elementFormDefault="qualified" xmlns:xs="http://www.w3.org/2001/XMLSchema">
   <customfunctions>
      <function name="age" as="xs:float" description="Returns the current age.">
         <param name="inputDate" as="xs:date"/> 
         <value-of select="round(days-from-duration(current-date() - xs:date($inputDate)) div 365.25, 1)"/>
      </function> 
      <function name="custom-if-then-else" as="xs:string" description="Evaluates the condition and returns corresponding value.">
         <param name="condition" as="xs:boolean"/>
         <param name="thenResult" as="xs:anyAtomicType"/>
         <param name="elseResult" as="xs:anyAtomicType"/>
         <choose>
            <when test="$condition">
               <value-of select="$thenResult"></value-of>
            </when>
            <otherwise>
               <value-of select="$elseResult"></value-of>
            </otherwise>
         </choose>
      </function>
   </customfunctions>
   

3. 在本地计算机上，打开标准型逻辑应用项目的文件夹。

4. 打开 Artifacts 文件夹，然后创建以下文件夹结构（如果不存在）：DataMapper > Extensions > Functions。

5. 在 Functions 文件夹中，保存函数的 XML 文件。

6. 若要在 Data Mapper 工具的函数列表中查找自定义函数，请搜索该函数，或展开“自定义函数”集合。

后续步骤

• 有关在 Azure 逻辑应用中使用 B2B 操作的数据转换，请参阅使用 Azure 逻辑应用在工作流中添加转换映射