通过使用 Liquid 模板作为使用 Azure 逻辑应用的工作流中的映射来转换 JSON 和 XML

项目
02/20/2024

适用范围：Azure 逻辑应用（消耗型 + 标准型）

若要在逻辑应用工作流中执行基本的 JSON 转换，可以使用内置数据操作，例如“撰写”操作或“分析 JSON”操作。但是，某些方案可能需要高级且复杂的转换，这些转换包括迭代、控制流、变量等元素。对于 JSON 到 JSON、JSON 到文本、XML 到 JSON 或 XML 到文本之间的转换，可以使用 Liquid 开源模板语言创建描述所需映射或转换的模板。向工作流添加 Liquid 内置操作时，可以选择此模板。可在多租户消耗型逻辑应用工作流和单租户标准型逻辑应用工作流中使用 Liquid 操作。

虽然没有“Liquid”触发器可用，但你可以使用任何触发器或操作将源 JSON 或 XML 内容馈送到你的工作流。例如，可使用内置连接器触发器、可用于 Azure 逻辑应用的托管或 Azure 托管连接器触发器，甚至其他应用。

本文演示如何完成以下任务：

创建 Liquid 模板。
将模板上传到用于消耗型逻辑应用工作流的集成帐户或标准型逻辑应用资源，以便在任何子工作流中使用。
向工作流添加 Liquid 操作。
选择模板作为要使用的映射。

有关详细信息，请查看以下文档：

先决条件

Azure 帐户和订阅。如果没有订阅，可以注册 Azure 帐户。
逻辑应用资源和工作流。 Liquid 操作没有任何可用的触发器，因此工作流必须至少包含一个触发器。有关详细信息，请参阅以下文档：
- 在多租户 Azure 逻辑应用中创建示例消耗逻辑应用工作流
- 在单租户 Azure 逻辑应用中创建标准逻辑应用工作流
根据你使用的是消耗型还是标准型逻辑应用工作流，需要集成帐户资源。通常，当你想要定义和存储项目以将其用于企业集成和 B2B 工作流时，你需要此资源。

重要

若要协同工作，集成帐户和逻辑应用资源必须存在于同一 Azure 订阅和 Azure 区域中。
- 如果使用消耗型逻辑应用工作流，则集成帐户需要一个指向逻辑应用资源的链接。
- 如果使用标准型逻辑应用工作流，则可以根据以下情况将集成帐户链接到逻辑应用资源并且/或者直接将映射上传到逻辑应用资源：
  - 如果你已经有一个包含所需项目或要使用的项目的集成帐户，可以将该集成帐户链接到你要在其中使用项目的多个标准型逻辑应用资源。这样，就不必将映射上传到每个单独的逻辑应用。有关详细信息，请查看将逻辑应用资源链接到集成帐户。
  - 通过 Liquid 内置连接器，可选择以前上传到逻辑应用资源或链接集成帐户的映射，但不能同时上传到这两者。然后，可以在同一逻辑应用资源中跨所有子工作流使用这些项目。
  因此，如果你没有集成帐户，或者你不需要集成帐户，可以使用上传选项。否则，可以使用链接选项。采用上述任一方式，都可以在同一逻辑应用资源中跨所有子工作流使用这些项目。
关于 Liquid 模板语言的基本知识。 Azure 逻辑应用使用 DotLiquid 2.0.361。

注意

名为“将 JSON 转换为 JSON”的 Liquid 操作遵循 Liquid 的 DotLiquid 实现，在特定情况下不同于 Liquid 的 Shopify 实现。有关详细信息，请参阅 Liquid 模板注意事项。

步骤 1：创建模板

在逻辑应用工作流中执行 Liquid 转换之前，必须先创建一个 Liquid 模板，用于定义所需的映射。

创建要用作 JSON 转换映射的 Liquid 模板。可以使用任何想要的编辑工具。

本文中的 JSON 到 JSON 转换示例使用以下示例 Liquid 模板：

{%- assign deviceList = content.devices | Split: ', ' -%}

{
   "fullName": "{{content.firstName | Append: ' ' | Append: content.lastName}}",
   "firstNameUpperCase": "{{content.firstName | Upcase}}",
   "phoneAreaCode": "{{content.phone | Slice: 1, 3}}",
   "devices" : [
      {%- for device in deviceList -%}
         {%- if forloop.Last == true -%}
         "{{device}}"
         {%- else -%}
         "{{device}}",
         {%- endif -%}
      {%- endfor -%}
   ]
}

使用 Liquid 模板 (.liquid) 文件扩展名保存模板。此示例使用 SimpleJsonToJsonTemplate.liquid。

步骤 2：上传 Liquid 模板

创建 Liquid 模板后，现在必须基于以下方案上传模板：

如果使用的是消耗型逻辑应用工作流，请将模板上传到集成帐户。
如果使用的是标准型逻辑应用工作流，可以将模板上传到集成帐户，或将模板上传到逻辑应用资源。

将模板上传到集成帐户

在 Azure 门户中，使用 Azure 帐户凭据登录。
在 Azure 门户搜索框中，输入“集成帐户”，然后选择“集成帐户”。
找到并选择你的集成帐户。
在集成帐户的导航菜单的“设置”下，选择“映射”。

在“映射”窗格上选择“添加”。提供有关映射的以下信息：

属性	价值	描述
名称	`JsonToJsonTemplate`	映射的名称，在此示例中为“JsonToJsonTemplate”
映射类型	Liquid	你的映射的类型。对于 JSON 到 JSON 转换，必须选择“Liquid”。
Map	`SimpleJsonToJsonTemplate.liquid`	用于转换的现有 Liquid 模板或映射文件，在此示例中为“SimpleJsonToJsonTemplate.liquid”。若要查找此文件，可使用文件选取器。有关映射大小限制，请参阅限制和配置。

Screenshot showing

将模板上传到标准型逻辑应用

在 Azure 门户中，查找并打开逻辑应用资源。请确保你位于资源级别，而不是工作流级别。
在逻辑应用资源导航菜单中的“项目”下，选择“映射”。
在“映射”窗格工具栏中选择“添加” 。

在“添加映射”窗格中，提供有关模板的以下信息：

属性	价值	描述
名称	`JsonToJsonTemplate`	映射的名称，在此示例中为“JsonToJsonTemplate”
映射类型	Liquid	你的映射的类型。对于 JSON 到 JSON 转换，必须选择“Liquid”。
Map	`SimpleJsonToJsonTemplate.liquid`	用于转换的现有 Liquid 模板或映射文件，在此示例中为“SimpleJsonToJsonTemplate.liquid”。若要查找此文件，可使用文件选取器。有关映射大小限制，请参阅限制和配置。

完成后，请选择“确定”。

完成映射文件上传后，该映射将显示在“映射”列表中。在集成帐户“概述”页的“项目”下，也会显示上传的映射。

步骤 3：添加 Liquid 转换操作

以下步骤演示如何为消耗型和标准型逻辑应用工作流添加 Liquid 转换操作。

消耗
标准

在 Azure 门户的设计器中打开逻辑应用工作流（如果尚未打开）。
如果工作流没有触发器或所需的任何其他操作，请先添加这些操作。 Liquid 操作没有任何可用的触发器。

此示例继续使用名为“收到 HTTP 请求时”的请求触发器。
在工作流设计器中，在要添加 Liquid 操作的步骤下，选择“新步骤”。
在“选择操作”搜索框中，选择“所有” 。在搜索框中输入“liquid”。
从操作列表中选择要使用的 Liquid 操作。

此示例继续使用名为“将 JSON 转换为 JSON”的操作。
在操作的 Content 属性中，按照以下步骤提供触发器或要转换的上一操作的 JSON 输出。
1. 在“内容”框中单击，以显示动态内容列表。
2. 从动态内容列表中，选择要转换的 JSON 数据。
  
  对于此示例，请从“收到 HTTP 请求时”下的动态内容列表中选择“正文”令牌，该令牌表示触发器的正文内容输出。
从“映射”列表中选择你的 Liquid 模板。

此示例继续使用名为 JsonToJsonTemplate 的模板。

注意

如果映射列表为空，则逻辑应用资源不会链接到集成帐户，或者集成帐户不包含任何映射文件。

完成后，操作类似于以下示例：
保存工作流。在设计器工具栏上选择“保存”。

测试工作流

通过使用 Postman（或类似的工具）和 POST 方法，向请求触发器的 URL 发送调用（该 URL 显示在请求触发器的 HTTP POST URL 属性中），并添加要转换的 JSON 输入，例如：
```
{
   "devices": "Surface, Mobile, Desktop computer, Monitors",
   "firstName": "Dean",
   "lastName": "Ledet",
   "phone": "(111)0001111"
}
```
工作流完成运行后，转到工作流的运行历史记录，并检查“将 JSON 转换为 JSON”操作的输入和输出，例如：

其他 Liquid 转换

可以使用 Liquid 来执行其他转换，例如：

JSON 到文本
XML 到 JSON
XML 到文本

将 JSON 转换为文本

以下 Liquid 模板显示了 JSON 到文本的示例转换：

{{content.firstName | Append: ' ' | Append: content.lastName}}

以下示例演示示例输入和输出：

Screenshot showing example output for JSON to text transformation.

将 XML 转换为 JSON

以下 Liquid 模板显示了 XML 到 JSON 的示例转换：

[{% JSONArrayFor item in content -%}
      {{item}}
  {% endJSONArrayFor -%}]

JSONArrayFor 循环是用于 XML 输入的自定义循环机制，允许创建避免尾部逗号的 JSON 有效负载。此外，此自定义循环机制的 where 条件使用 XML 元素的名称进行比较，而不是像其他 Liquid 筛选器一样使用元素的值。有关详细信息，请参阅深度学习 set-body 策略 - 事项集合。

以下示例演示示例输入和输出：

Screenshot showing example output for XML to JSON transformation.

将 XML 转换为文本

以下 Liquid 模板显示了 XML 到文本的示例转换：

{{content.firstName | Append: ' ' | Append: content.lastName}}

以下示例演示示例输入和输出：

Screenshot showing example output for XML to text transformation.

Liquid 模板注意事项

在 Azure 逻辑应用中，Liquid 模板遵循映射的文件大小限制。
“将 JSON 转换为 JSON”操作遵循 Liquid 的 DotLiquid 实现。此实现是从 Liquid 的 Shopify 实现到 .NET Framework 的端口，在特定情况下有所不同。

以下列表介绍了已知差异：
- “将 JSON 转换为 JSON”操作是以原生方式输出字符串，其中可能包括 JSON、XML、HTML 等。该 Liquid 操作仅指示来自 Liquid 模板的预期文本输出为 JSON 字符串。该操作指示逻辑应用将输入作为 JSON 对象进行分析，并应用包装器以使 Liquid 可以解释 JSON 结构。转换后，该操作会指示逻辑应用将来自 Liquid 的文本输出重新分析为 JSON。
  
  DotLiquid 不能以本机方式理解 JSON，因此请确保对反斜杠字符 (\) 和其他任何保留的 JSON 字符进行转义。
- 如果模板使用了 Liquid 筛选器，请确保遵循 DotLiquid 和 C# 命名约定，该约定要求“句子首字母大写”。对于所有 Liquid 转换，请确保模板中的筛选器名称也遵循句子首字母大写。否则，筛选器将不起作用。
  
  例如，使用 replace 筛选器时，请使用 Replace，而不是 replace。如果是在 DotLiquid online 上试用示例，也适用相同的规则。有关详细信息，请参阅 Shopify Liquid 筛选器和 DotLiquid Liquid 筛选器。 Shopify 规范中包含了每个筛选器的示例，因此可以在 DotLiquid - 在线试用上试用这些示例，以作比较。
- Shopify 扩展筛选器中的 json 筛选器当前未在 DotLiquid 中实现。通常情况下，可以使用此筛选器来准备用于 JSON 字符串分析的文本输出，但现在需要改用 Replace 筛选器。
- DotLiquid 实现中的标准 Replace 筛选器使用正则表达式 (RegEx) 匹配，Shopify 实现则使用简单字符串匹配。这两种实现看似工作原理一样，但是当在匹配参数中使用 RegEx 保留字符或转义字符时，区别就显现出来了。
  
  例如，若要对 RegEx 保留的反斜杠 (\) 转义字符进行转义，请使用 | Replace: '\\', '\\'，而不是 | Replace: '\', '\\'。以下示例显示了在尝试对反斜杠字符进行转义时，Replace 筛选器的行为方式有何不同。此版本运行成功时：
  
  { "SampleText": "{{ 'The quick brown fox "jumped" over the sleeping dog\\' | Replace: '\\', '\\' | Replace: '"', '\"'}}"}
  
  显示此结果：
  
  { "SampleText": "The quick brown fox \"jumped\" over the sleeping dog\\\\"}
  
  此版本失败时：
  
  { "SampleText": "{{ 'The quick brown fox "jumped" over the sleeping dog\\' | Replace: '\', '\\' | Replace: '"', '\"'}}"}
  
  显示此错误：
  
  { "SampleText": "Liquid error: parsing "\" - Illegal \ at end of pattern."}
  
  有关详细信息，请参阅替换标准筛选器使用 RegEx 模式匹配...。
- DotLiquid 实现中的 Sort 筛选器按属性对数组或集合中的各项进行排序，但存在以下差异：
  - 遵循 Shopify 的 sort_natural 行为，而非 Shopify 的 sort 行为。
  - 仅按字符串字母数字顺序排序。有关详细信息，请参阅数值排序。
  - 使用“不区分大小写”的顺序，而不是区分大小写。有关详细信息，请参阅 Sort 筛选器不遵循 Shopify 规范中的大小写行为。

通过使用 Liquid 模板作为使用 Azure 逻辑应用的工作流中的映射来转换 JSON 和 XML

先决条件

步骤 1：创建模板

步骤 2：上传 Liquid 模板

将模板上传到集成帐户

将模板上传到标准型逻辑应用

步骤 3：添加 Liquid 转换操作

测试工作流

其他 Liquid 转换

将 JSON 转换为文本

将 XML 转换为 JSON

将 XML 转换为文本

Liquid 模板注意事项

后续步骤

其他资源