在 Azure Logic Apps 中，使用 Liquid 範本作為工作流程中的對應來轉換 JSON 和 XML

適用於：Azure Logic Apps (使用量 + 標準)

當您要在邏輯應用程式工作流程中執行基本 JSON 轉換時，可以使用內建資料作業，例如撰寫動作或剖析 JSON動作。 不過，某些案例可能需要執行進階且複雜的轉換，其中包含反覆運算、控制流程和變數等元素。 針對 JSON 到 JSON、JSON 到文字、XML 到 JSON 或 XML 到文字之間的轉換，您可以使用 Liquid 開放原始碼範本語言來建立範本，其中描述必要對應或轉換。 當您將 Liquid 內建動作新增至工作流程時，可以選取此範本。 您可以在多租用戶使用量邏輯應用程式工作流程和單一租用戶標準邏輯應用程式工作流程中使用 Liquid 動作。

雖然沒有可用的 Liquid 觸發程序，但您可以使用任何觸發程序或動作，將來源 JSON 或 XML 內容饋送至工作流程。 例如，您可以使用內建連接器觸發程序、適用於 Azure Logic Apps 的受控或 Azure 裝載連接器觸發程序，甚或是另一個應用程式。

本文示範如何完成下列工作：

• 建立 Liquid 範本。
• 將範本上傳至用於取用邏輯應用程式工作流程的企業整合帳戶，或上傳至標準邏輯應用程式資源，以便用於任何子工作流程。
• 將 Liquid 動作新增至工作流程。
• 選取範本作為您要使用的對應。

如需詳細資訊，請參閱下列文件：

• 在 Azure Logic Apps 中執行資料作業
• Liquid 開放原始碼範本語言
• 取用與標準邏輯應用程式
• 整合帳戶內建連接器
• 適用於 Azure Logic Apps 的內建連接器概觀
• 適用於 Azure Logic Apps 的受控或 Azure 裝載的連接器概觀和 Azure Logic Apps 中的受控或 Azure 裝載的連接器

必要條件

• Azure 帳戶和訂用帳戶。 如果您沒有訂用帳戶，請註冊一個免費的 Azure 帳戶。

• 邏輯應用程式資源和工作流程。 Liquid 作業沒有任何可用的觸發程序，因此您的工作流程必須至少包含觸發程序。 如需詳細資訊，請參閱下列文件：

  • 在多租用戶 Azure Logic Apps 中建立範例使用量邏輯應用程式工作流程

  • 在單一租用戶 Azure Logic Apps 中建立範例標準邏輯應用程式工作流程

• 無論您是使用取用或標準邏輯應用程式工作流程，都需要企業整合帳戶資源。 當您想要定義及儲存用於企業整合和 B2B 工作流程的成本時，通常需要此資源。

  重要

  若要共同作業，您的企業整合帳戶和邏輯應用程式資源必須存在於相同的 Azure 訂用帳戶和 Azure 區域中。

  • 如果您正在處理取用邏輯應用程式工作流程，則企業整合帳戶需要邏輯應用程式資源的連結。

  • 如果您正在處理標準邏輯應用程式工作流程，您可以根據下列情節，將企業整合帳戶連結至邏輯應用程式資源、直接上傳對應至邏輯應用程式資源，或兩者：

    • 如果您的企業整合帳戶已經含有需要或想要使用的成品，您可以將該企業整合帳戶連結至您想要在其中使用成品的多個標準邏輯應用程式資源。 如此一來，您就不需要將對應上傳至每一個個別邏輯應用程式。 如需詳細資訊，請參閱將邏輯應用程式資源連結至企業整合帳戶。

    • Liquid 內建連接器可讓您選取您先前上傳至邏輯應用程式資源或連結整合帳戶的對應，但無法同時選取兩者。 然後，您可以在相同邏輯應用程式資源的所有子工作流程中使用這些成品。

    因此，如果您沒有或不需要企業整合帳戶，則可以使用上傳選項。 否則，您可以使用連結選項。 不管怎樣，您都可以在相同邏輯應用程式資源的所有子工作流程中使用這些成品。

• Liquid 範本語言的基本知識。 Azure Logic Apps 使用 DotLiquid 2.0.361。

  注意

  Liquid 動作將 JSON 轉換成 JSON 遵循 Liquid 的 DotLiquid 實作，這在特定案例中會與 Liquid 的 Shopify 實作不同。 如需詳細資訊，請參閱 Liquid 範本考量。

• 安裝或使用可傳送 HTTP 要求以測試解決方案的工具，例如：

  • Visual Studio Code 搭配 Visual Studio Marketplace 的延伸模組
  • PowerShell Invoke-RestMethod
  • Microsoft Edge - 網路主控台工具
  • Bruno
  • curl

  警告

  如果您有敏感資料，例如認證、秘密、存取權杖、API 金鑰和其他類似資訊，請務必使用一項工具，以必要的安全性功能保護資料、離線或本機運作、不將資料同步處理至雲端，而且不需要您登入線上帳戶。 如此一來，您就可以降低向公眾公開敏感資料的風險。

步驟 1：建立範本

您必須先建立 Liquid 範本來定義您想要的對應，才能在邏輯應用程式工作流程中執行 Liquid 轉換。

1. 建立您用來做為 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 -%}
      ]
   }
   

2. 使用 Liquid 範本 (.liquid) 副檔名來儲存範本。 此範例使用 SimpleJsonToJsonTemplate.liquid。

步驟 2：上傳 Liquid 範本

建立 Liquid 範本之後，您現在必須根據下列情節上傳範本：

• 如果您正在處理取用邏輯應用程式工作流程，請將範本上傳至您的企業整合帳戶。

• 如果您正在處理標準邏輯應用程式工作流程，可以將範本上傳至企業整合帳戶，或將範本上傳至邏輯應用程式資源。

將範本上傳到企業整合帳戶

1. 在 Azure 入口網站 中，使用您的 Azure 帳戶認證登入。

2. 在 Azure 入口網站的搜尋方塊中輸入整合帳戶，然後選取 [企業整合帳戶]。

   

3. 尋找並選取您的整合帳戶。

   

4. 在企業整合帳戶的導覽功能表，選取 [設定] 下的 [對應]。

   

5. 在 [對應] 窗格中，選取 [新增]。 提供有關對應的下列資訊：

   屬性	數值	描述
   名稱	JsonToJsonTemplate	對應的名稱，在此範例中是 "JsonToJsonTemplate"
   對應類型	Liquid	對應的類型。 對於 JSON 到 JSON 轉換，您必須選取 [Liquid]。
   地圖	SimpleJsonToJsonTemplate.liquid	用於轉換的現有 Liquid 範本或對應檔案，在此範例中是 "SimpleJsonToJsonTemplate.liquid"。 若要尋找此檔案，您可以使用檔案選擇器。 如需對應大小限制，請參閱限制和設定。

   

將範本上傳至標準邏輯應用程式

1. 在 Azure 入口網站中，尋找並開啟邏輯應用程式資源。 請確定您位於資源層級，而不是工作流程層級。

2. 在邏輯應用程式資源的導覽功能表上，選取 [成品] 下的 [對應]。

3. 在 [對應] 窗格工具列上，選取 [新增]。

4. 在 [新增對應] 窗格上，提供有關範本的下列資訊：

   屬性	數值	描述
   名稱	JsonToJsonTemplate	對應的名稱，在此範例中是 "JsonToJsonTemplate"
   對應類型	Liquid	對應的類型。 對於 JSON 到 JSON 轉換，您必須選取 [Liquid]。
   地圖	SimpleJsonToJsonTemplate.liquid	用於轉換的現有 Liquid 範本或對應檔案，在此範例中是 "SimpleJsonToJsonTemplate.liquid"。 若要尋找此檔案，您可以使用檔案選擇器。 如需對應大小限制，請參閱限制和設定。

5. 完成時，選取確定。

   在您的對應檔案完成上傳之後，對應會出現在 [對應] 清單中。 在整合帳戶的 [概觀] 頁面上，於 [成品] 下，已上傳的對應也會出現。

步驟 3：新增 Liquid 轉換動作

下列步驟示範如何為取用和標準邏輯應用程式工作流程新增 Liquid 轉換動作。

耗用

1. 在 Azure 入口網站的設計工具中，開啟邏輯應用程式工作流程 (如果尚未開啟)。

2. 如果工作流程沒有觸發程序或工作流程所需要的任何其他動作，請先新增這些作業。 Liquid 作業沒有任何可用的觸發程序。

   此範例會繼續使用名為收到 HTTP 要求時的要求觸發程序。

3. 在工作流程設計工具上，在您要新增 Liquid 動作的步驟下，選取 [新增步驟]。

4. 在 [選擇作業] 搜尋方塊底下，選取 [全部]。 在搜尋方塊中輸入 liquid。

5. 從動作清單中，選取您要使用的 Liquid 動作。

   此範例會繼續使用名為將 JSON 轉換為 JSON 的動作。

   

6. 在動作的 Content 屬性中，遵循下列步驟以提供觸發程序或先前要轉換動作的 JSON 輸出。

   1. 在 [內容] 方塊內按一下，動態內容清單隨即顯示。

   2. 從動態內容清單中，選取您要轉換的 JSON 資料。

      在此範例中，從動態內容清單的收到 HTTP 要求時下方，選取 [本文] 權杖，其代表觸發程序的本文內容輸出。

      

7. 從 [對應] 清單中，選取您的 Liquid 範本

   此範例會繼續使用名為 JsonToJsonTemplate 的範本。

   

   注意

   如果對應清單是空的，您的邏輯應用程式資源不會連結至您的整合帳戶，或您的整合帳戶不包含任何對應檔案。

   完成時，此動作會類似下列範例：

   

8. 儲存您的工作流程您 在設計師工具列上選取儲存。

標準

1. 在 Azure 入口網站的設計工具中，開啟邏輯應用程式工作流程 (如果尚未開啟)。

2. 如果工作流程沒有觸發程序或工作流程所需要的任何其他動作，請先新增這些作業。 Liquid 作業沒有任何可用的觸發程序。

   此範例會繼續使用名為收到 HTTP 要求時的要求觸發程序。

3. 在設計工具上，在您要新增 Liquid 動作的步驟下，選取加號 (+)，然後選取 [新增動作]。

4. 在顯示的 [新增動作] 窗格中，選取搜尋方塊下方的 [內建]。

5. 在搜尋方塊中輸入 liquid。 從動作清單中，選取您要使用的 Liquid 動作。

   此範例會繼續使用名為將 JSON 轉換為 JSON 的動作。

   

6. 在動作的 Content 屬性中，遵循下列步驟以提供觸發程序或先前要轉換動作的 JSON 輸出。

   1. 在 [內容] 方塊內按一下，動態內容清單隨即顯示。

   2. 從動態內容清單中，選取您要轉換的 JSON 資料。

      在此範例中，從動態內容清單的收到 HTTP 要求時下方，選取 [本文] 權杖，其代表觸發程序的本文內容輸出。

      

   注意

   如果本文屬性未出現在動態內容清單中，請選取 [收到 HTTP 要求時]區段標籤旁的 [查看更多]。 您也可以將要解碼的內容直接輸入在 [內容] 方塊中。

7. 從 [來源] 清單中，選取 LogicApp 或 IntegrationAccount 作為 Liquid 範本來源。

   此範例會在選取 IntegrationAccount 後繼續。

   

8. 從 [名稱] 清單中，選取您的 Liquid 範本。

   此範例會繼續使用名為 JsonToJsonTemplate 的範本。

   

   注意

   如果清單是空的，可能表示邏輯應用程式資源未連結至您的企業整合帳戶。 請務必將邏輯應用程式資源連結至具有 Liquid 範本或對應的企業整合帳戶。

   完成時，此動作會類似下列範例：

   

9. 儲存您的工作流程您 在設計師工具列上選取儲存。

測試工作流程

若要觸發工作流程，請遵循下列步驟：

1. 在 [要求] 觸發程序中，尋找 HTTP POST URL 屬性，然後複製該 URL。

2. 開啟 HTTP 要求工具並使用其指示，將 HTTP 要求傳送至複製的 URL，包括要求觸發程序預期的方法。

   這個範例會使用 POST 方法搭配 URL。

3. 包括要轉換的 JSON 輸入，例如：

   {
      "devices": "Surface, Mobile, Desktop computer, Monitors",
      "firstName": "Dean",
      "lastName": "Ledet",
      "phone": "(111)0001111"
   }
   

4. 工作流程執行完成之後，請移至工作流程的執行歷程記錄，並檢查將 JSON 轉換到 JSON 動作的輸入和輸出，例如：

   

其他 Liquid 轉換

您可以使用 Liquid 來執行其他轉換，例如：

• JSON 到文字
• XML 到 JSON
• XML 到文字

JSON 轉換為文字

下列 Liquid 範本顯示 JSON 轉換為文字的範例：

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

下列範例顯示範例輸入和輸出：

XML 轉換為 JSON

下列 Liquid 範本顯示 XML 轉換為 JSON 的範例：

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

JSONArrayFor 迴圈是 XML 輸入的自訂迴圈機制，因此您可以建立可避免尾端逗號的 JSON 承載。 此外，此自訂迴圈機制的條件會 where 使用 XML 元素的名稱進行比較，而不是像其他 Liquid 篩選一樣元素的值。 如需詳細資訊，請參閱 Set-body 原則的深入探討 - 項目集合。

下列範例顯示範例輸入和輸出：

XML 轉換為文字

下列 Liquid 範本顯示 XML 轉換為文字的範例：

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

下列範例顯示範例輸入和輸出：

Liquid 範本考量

• Liquid 範本會遵循 Azure Logic Apps 中地圖的檔案大小限制。

• 將 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 範例，則適用相同的規則。 如需詳細資訊，請參閱 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 的排序行為。

    • 僅以字串英數位元順序排序。 如需詳細資訊，請參閱數值排序。

    • 使用不區分大小寫的順序，而不是區分大小寫的順序。 如需詳細資訊，請參閱排序篩選不符合 Shopify 規格的大小寫行為。

下一步

• Shopify Liquid 語言和範例
• DotLiquid
• DotLiquid - 線上試用
• DotLiquid GitHub
• DotLiquid GitHub 問題
• 深入了解對應