使用 Visual Studio Code 建立對應以在邏輯應用程式工作流程中轉換資料

適用於：Azure Logic Apps (標準)

當您在邏輯應用程式工作流程中交換使用不同 XML 或 JSON 格式的訊息時，必須指定如何將資料從來源格式轉換成目標格式，例如 XML 文件之間或 JSON 文件之間的資料。 這項工作很重要，特別是當您在來源和目標結構描述中的資料結構之間有間距時。 結構描述描述 XML 或 JSON 文件中的資料元素、屬性和資料類型。

若要定義資料結構之間的轉換，並橋接任何間距，您可以建立對應 (.xslt 檔案)，以指定來源和目標結構描述中資料元素之間的關聯性。 您可以視覺化方式建立或編輯對應，方法是使用 Visual Studio Code 搭配標準邏輯應用程式專案的內容中的 Azure Logic Apps (標準) 延伸模組。 資料對應工具提供使用拖放手勢進行對應和轉換的整合體驗、用於建立運算式的預先建置函式，以及手動測試您在工作流程中使用這些函式的對應方式。

建立對應之後，您可以直接從邏輯應用程式專案中的工作流程或從 Azure 入口網站中的標準邏輯應用程式工作流程呼叫該對應。 針對此工作，您可以在工作流程中使用名為 [使用對應程式工具 XSLT 轉換] 的資料對應程式作業動作。

本操作指南示範如何建立空白資料對應、選擇來源和目標結構描述、在結構描述元素之間建立各種對應、儲存及測試您的對應，然後從邏輯應用程式專案中的工作流程呼叫對應。

限制與已知問題

• 資料對應程式目前只能在 Visual Studio Code 中使用，而不是 Azure 入口網站，而且僅能從標準邏輯應用程式專案內，而不是使用量邏輯應用程式專案。

  Data Mapper 的前端體驗可在 Azure Logic Apps 小組的公用 GitHub 存放庫中以開放原始碼的形式提供。 如需詳細資訊，請參閱下列資源：

  • 歡迎使用 Azure Logic Apps UX

  • Azure Logic Apps 中新增和改進的資料映射器 UX

• 資料對應程式目前只能在 Windows 作業系統上執行的 Visual Studio Code 中運作。

• 資料對應工具目前不支援使用逗號分隔值 (.csv) 檔案格式的結構描述。

• 資料對應工具中的 [程式碼] 窗格目前是唯讀的。

• 在數據對應器介面上，函式的配置和位置是可移動的，但架構節點是靜態的。

• 「Filter」函式會正確處理以雙引弧括住的數值條件，例如 ">=10"。 不過，此函式目前對於字串比較的行為並不一致，例如檢查項目名稱是否為 "= 'Pen'"。

• 當您在來源和目標結構描述中建立父陣列元素之間的對應時，對應工具會自動新增迴圈來逐一查看陣列項目元素。 不過，您仍必須明確建立來源與目標陣列項目元素之間的對應。

• 若要呼叫使用資料對應工具建立的對應，您只能使用名為 [使用資料對應工具 XSLT 轉換] 的資料對應程式作業動作。 針對任何其他工具建立的對應，請使用名為 [轉換 XML] 的 XML 作業動作。

• 若要使用您利用 Azure 入口網站中的工作流程透過資料對應工具建立的對應，但在 Azure 入口網站中，您必須將其直接新增至標準邏輯應用程式資源。

針對非封鎖錯誤或功能要求，請在 Azure Logic Apps 小組的 GitHub 存放庫中開啟具有 數據對應程式 標籤的專案。

先決條件

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

• Visual Studio Code 和 Azure Logic Apps (標準) 延伸模組用來建立標準邏輯應用程式工作流程。

  附註

  先前分開的資料對應程式延伸模組，現在會與 Azure Logic Apps (標準) 延伸模組合併。 為了避免衝突，當您安裝或更新 Azure Logic Apps (標準) 延伸模組時，會移除任何現有的資料對應程式延伸模組版本。 在延伸模組安裝或更新之後，請重新啟動 Visual Studio Code。

• 描述要轉換的資料類型的來源和目標結構描述檔案。 這些檔案可以有下列其中一種格式：

  • 副檔名為 .xsd 的 XML 結構描述定義檔案

  • 副檔名為 .json 的 JavaScript 物件標記法檔案

• 標準邏輯應用程式專案，其包含至少一個觸發程序的具狀態或無狀態工作流程。 如果您沒有專案，請在 Visual Studio Code 中遵循這些步驟：

  1. 連線至您的 Azure 帳戶 (如果您尚未這樣做)。

  2. 建立本機資料夾、標準邏輯應用程式工作區和專案，以及具狀態或無狀態工作流程。 在工作流程建立期間，選取 [在目前視窗中開啟]。

• 如果您想要測試對應並檢查轉換是否如預期般運作，請對輸入資料取樣。

建立資料對應

1. 在 Visual Studio Code 中，開啟您標準邏輯應用程式專案的資料夾。

2. 在 Visual Studio Code 左側功能表上，選取 Azure 圖示。

3. 在 [Azure] 視窗的 [資料對應工具] 底下，選取 [建立資料對應]。

   

   在 Visual Studio Code 標題列上，會開啟提示方塊，以便提供對應的名稱。

4. 在提示方塊中，輸入對應的名稱。

   針對本指南，這些步驟會使用 Example-data-map 名稱。

   

   資料對應工具會建立並開啟空白的資料對應。

5. 請遵循這些步驟選擇您的來源和目標結構描述：

   1. 在 [來源] 窗格中，選取 [新增]>[瀏覽] 以尋找並上傳您的來源結構描述。

      

      新增來源結構描述之後，[來源] 窗格會填入來源結構描述中資料類型的 XML 元素「nodes」，例如：

      

   2. 在 [目的地] 窗格中，選取 [新增]>[瀏覽] 以尋找並上傳您的目標結構描述。

      

      新增目標結構描述之後，[目的地] 窗格會填入目標結構描述中資料類型的 XML 元素「nodes」，例如：

      

結構描述資料類型

下表描述可能出現在結構描述中的可能資料類型：

符號	類型	其他資訊
	複雜 (陣列)	包含項目或重複的項目節點。 陣列元素也會顯示下列連接點：
	Bool	僅限 True 或 false
	複雜	具有子系屬性的 XML 物件，類似於物件 JSON 類型
	Datetime
	Decimal
	整數	僅限整數
	繩子

建立元素之間的直接對應

若要在來源和目標結構描述中具有相同類型的元素之間指定直接轉換，請遵循下列步驟：

1. 若要在建立對應時檢視程式碼中發生的情況，請在對應工具的右上角選取 [檢視程式碼]。

2. 在對應工具介面的 [來源] 窗格中，尋找您要對應的來源元素。

   • 根據預設，父元素會自動展開以顯示其子系。

   • 此範例會從來源元素開始對應，但您可以選擇從目標元素開始對應。

3. 將滑鼠指標移至來源元素名稱旁的圓形，直到指標變更為加號 (+) 為止。

   此範例會從 [員工識別碼] 來源元素開始建立對應。

   

4. 拖曳並繪製線條，讓來源元素連線到 [目的地] 窗格中目標元素的圓形。

   此範例會使用 [識別碼] 目標元素完成對應，其資料類型與來源元素相同。

   

   您現在已在兩個具有相同資料類型的元素之間建立直接對應。

   

   [程式碼] 窗格會顯示您所建立的對應關聯性：

   

   秘訣

   若要檢查您的對應是否有任何問題，請選取 [檢視問題]。 例如，如果您在具有不相符資料類型的項目之間建立對應，警告隨即會出現在 [警告] 索引標籤上的 [問題] 清單中：

   

建立元素之間的複雜對應

若要指定來源和目標結構描述中元素之間更複雜的轉換，例如，您想要合併或擁有不同資料類型的元素，可以使用一或多個函式來執行對應中所需的轉換。

在對應工具介面上，函式標籤會根據函式群組進行色彩編碼。 函式名稱旁會出現函式的符號，例如：

下表列出您可以使用的函式群組和一些範例函式。 如需完整清單，請參閱資料對應工具中的 [函式] 清單。

新增不含對應的函式

本節中的範例會將來源元素中的資料從 String 轉換成 DateTime，這是目標元素類型。 此範例會在不先建立對應的情況下開始，並使用接受單一輸入的 To Date 函式。

1. 若要在建立對應時檢視程式碼中發生的情況，請在對應工具的右上角選取 [檢視程式碼]。

2. 在 [函式] 清單中，尋找並選取您想要使用的函式，以將函式新增至對應工具介面。 如果 [函式] 清單已折疊，請在對應工具的左上角選取函式圖示 ()。

   此範例會選取 [轉換函式] 群組中的 To Date 函式。

   

   附註

   如果對應中沒有對應，或當您將函式新增至對應時選取了對應，則函式會出現，但未連線到任何元素或其他函式，例如：

   

3. 將函式連接到來源和目標元素。

   1. 在來源元素與函式左邊緣圓形之間拖曳並繪製線條。 您可以從來源元素或函式開始。

      

   2. 在函式右邊緣與目標元素之間拖曳並繪製線條。 您可以從目標元素或從函式開始。

      

   [程式碼] 窗格會顯示您所建立的對應關聯性：

   

4. 在對應工具介面上，選取函式圖形以檢視函式詳細資料。

5. 在 [輸入] 索引標籤上，確認或編輯要使用的輸入。

   

   某些案例需要定義超越立即配對來源和目標元素的轉換。 例如，若要定義一組陣列與其項目之間的轉換，您需要在陣列之間建立迴圈。 或者，若要在元素的值符合條件時執行工作，您需要在元素之間新增條件。

新增使用多個輸入的函式

本節中的範例會將多個來源元素串連為輸入，並將單一輸出對應至目標元素。 範例會使用可接受多個輸入的 Concat 函式。

1. 若要在建立對應時檢視程式碼中發生的情況，請在對應工具的右上角選取 [檢視程式碼]。

2. 在 [函式] 清單中，尋找並選取您想要使用的函式，以將函式新增至對應工具介面。

   如果 [函式] 清單已折疊，請在對應工具的左上角選取函式圖示 ()。

   此範例會選取 String 函式群組中的 Concat 函式。

   

   附註

   如果對應中沒有對應，或當您將函式新增至對應時選取了對應，則函式會出現，但未連線到任何元素或其他函式，例如：

   

3. 在對應工具介面上，選取函式圖形以檢視函式詳細資料。

4. 在 [輸入] 索引標籤上，選取要作為輸入的來源結構描述元素。

   此範例會選取 FirstName 和 LastName 來源結構描述元素作為函式輸入。 對應工具會自動新增來源元素與函式之間的個別對應。

   

5. 若要完成對應，請在函式的右邊緣與目標元素之間拖曳並繪製線條。 您可以從目標元素或從函式開始。

   

   [程式碼] 窗格會顯示您所建立的對應關聯性：

   

逐一查看陣列

如果您的來源和目標結構描述包含陣列，則可以建立迴圈來逐一查看陣列的項目。 本節中的範例會透過 Employee 來源陣列和 Person 目標陣列，以及陣列項目之間的對應建立迴圈。

1. 若要在建立對應時檢視程式碼中發生的情況，請在對應工具的右上角選取 [檢視程式碼]。

2. 在對應工具介面的 [來源] 和 [目的地] 窗格中，尋找您要對應的陣列。

3. 拖曳並繪製陣列項目配對之間的線條。 您可以從 [來源] 窗格或 [目的地] 窗格開始。

   下列範例會從 [來源] 窗格開始，並對應 Employee 來源陣列和 Person 目標陣列中的 [名稱] 項目：

   

   完成對應第一組陣列項目之後，對應工具會自動在來源與目標陣列父元素之間新增迴圈，其具有下列連接點類型：

   下列範例會反白顯示來源 Employee 與目標 Person 父陣列之間的自動新增迴圈：

   

   [程式碼] 窗格會顯示您所建立的對應和迴圈：

   

4. 繼續對應其他陣列元素，例如：

   

評估條件以執行工作

假設您想要新增評估條件的對應，並在符合條件時執行工作。 在此案例中，您可以使用多個函式。

在下列範例中，購買數量超過 20 個項目時，對應會使用下列函式計算要套用的折扣：

1. 在 [來源] 和 [目的地] 窗格中，尋找您案例中要對應的元素。

   此範例會使用下列元素：

   • [來源] 窗格：ItemPrice 和 ItemQuantity

   • [目的地]Destination 窗格：ItemPrice、ItemQuantity 和 ItemDiscount

     

2. 在 [函式] 清單中，尋找並選取您想要使用的函式，以將函式新增至對應工具介面。

   • 如果 [函式] 清單已折疊，請在對應工具的左上角選取函式圖示 ()。

   • 如有必要，請移動對應工具介面上的函式圖形，使其更容易選取。

   本範例會將下列函式新增至對應工具介面：Greater、If 和 Multiply

   

3. 若要在建立對應時檢視程式碼中發生的情況，請在對應工具的右上角選取 [檢視程式碼]。

4. 視您的案例需要，依特定順序連結來源元素、函式和目標元素。

   此範例會以指定的順序連線下列項目，以正確建立對應：

   Start	結束
   ItemPrice 來源元素	ItemPrice 目標元素
   ItemQuantity 來源元素	圖形左邊緣的 Greater 函式輸入。 此輸入會提供函式詳細資料中 [值 1] 欄位的資料。
   圖形右邊緣的 Greater 函式輸出	如果 If 函式的輸入位於圖形的左邊緣。 此輸入會提供函式詳細資料中 [條件] 欄位的資料。
   ItemPrice 來源元素	將函式的輸入 Multiply 以圖形左邊緣。 此輸入會提供函式詳細資料中 [Multiplicand] 欄位的資料。
   圖形右邊緣的 Multiply 函式輸出。	如果 If 函式的輸入位於圖形的左邊緣。 此輸入會提供函式詳細資料中 [值] 欄位的資料。
   圖形右邊緣的 If 函式輸出。	ItemDiscount 目標元素

   下列範例顯示此時的對應：

   

5. 在下列函式詳細資料中，於 [輸入] 索引標籤上確認或提供下列值：

   函式	輸入欄位和值
   大於	- Value 1：ItemQuantity 來源元素 - 值 2：20 作為自訂值
   Multiply	- Multiplicand 1：ItemPrice 來源元素 - Multiplicand 2：.10 作為自訂值
   If	- 條件：is-greater-than(ItemQuantity, 20) - 值：multiply(ItemPrice, .10)

   下圖顯示完成的範例：

   

   [程式碼] 窗格會顯示您所建立的對應：

   

儲存您的對應

完成時，在對應工具列上，選取 [儲存]。

Visual Studio Code 會將資料對應儲存為下列成品：

• 在 <> 專案資料夾中的資料對應工具 (your-map-name>.lml) 檔案
• 在 <> 專案資料夾中的資料對應 (your-map-name>.xslt) 檔案

測試您的對應

若要確認轉換如預期般運作，您需要範例輸入資料。

1. 在測試對應之前，請先儲存對應以產生目前的 <your-map-name>.xslt 檔案。

2. 在您的對應工具列上，選取 [開啟測試面板]。

3. 在 [測試對應] 窗格的 [範例資料] 方塊中，貼上您的範例輸入，然後選取 [測試]。

   [結果] 方塊會顯示測試結果。

從專案中的工作流程呼叫您的對應

1. 在 Visual Studio Code 活動列上，選取 [總管] (檔案圖示) 以檢視邏輯應用程式專案結構。

2. 展開具有您的工作流程名稱的資料夾。 從 workflow.json 檔案的捷徑功能表中，選取 [開啟設計工具]。

3. 在工作流程設計工具上，遵循下列一般步驟，來新增名為使用對應程式工具 XSLT 轉換的資料對應程式作業內建動作。

4. 在設計工具上，選取 [使用資料對應程式 XSLT 轉換] 動作。

5. 在出現的動作資訊窗格中，指定 [內容] 值，並將 [對應來源] 設定為 [LogicApp]。

6. 開啟 [對應名稱] 清單，然後選取您的對應 (.xslt 檔案)。

   

   若要在 Azure 入口網站中使用相同的使用資料對應程式 XSLT 轉換動作，您必須將對應新增至標準邏輯應用程式資源。

從資料對應執行 XSLT

您可以使用執行 XSLT 函式，在資料對應 (.xslt) 檔案內執行可執行檔 XSLT 程式碼片段。 當您使用此函式時，會取得包含實際可執行檔 XSLT 的資料對應檔案。 資料對應工具 (.lml) 檔案包含可執行檔 XSLT (.xslt 或 .xml) 檔案的參考。

若要執行這項工作，請遵循下列步驟：

1. 建立新的資料對應 (.xslt 或 .xml) 檔案，其中包含您要執行的可執行檔 XSLT 程式碼片段。

2. 將 XSLT 程式碼片段檔案放入或移至下列項目資料夾中：

   工件>DataMapper/擴充功能>嵌入式XSLT

   

   附註

   如果您在 Visual Studio Code 中建立或儲存此可執行檔 XSLT 檔案，該檔案會自動出現在「Artifacts」>「Maps」專案資料夾中。 請務必將 XSLT 程式碼片段檔案移至 InlineXslt 資料夾。

3. 開啟您要從其中執行 XSLT 的資料對應。

4. 從 [函式] 窗格的 [公用程式] 底下，選取 [執行 XSLT] 將函式新增至對應工具介面。

5. 在對應工具介面上，選取 [執行 XSLT]。

6. 從 [檔案] 下拉式清單中，選取您新增至 InlineXSLT 資料夾的可執行檔 .xslt 檔案，例如：

   

7. 將執行 XSLT 函式連線到您要套用 XSLT 邏輯的目的地節點，例如：

   

   當 XSLT 邏輯僅適用於目的地節點時，您不必將執行 XSLT 函式連線到來源節點。

8. 測試您的對應，以確認預期的結果出現在目的地結構描述中。

針對部署，您只需要具有內嵌可執行檔 XSLT 的結果資料對應。

存取巢狀 XML 中的節點

假設您有具有巢狀 XML 節點的結構描述，且您想要以下列方式使用這些節點：

• 存取屬性或巢狀元素。
• 根據傳入資料的結構或內容套用邏輯。

若要完成這些工作，請使用 Execute XPath 函式：

1. 開啟您要處理的資料對應。

2. 從 [函式] 窗格的 [公用程式] 底下，選取 [執行 XPath] 將函式新增至對應工具介面。

3. 在對應工具介面上，選取 [執行 XPath]。

4. 在 [XPATH 運算式] 方塊中，輸入執行所需工作的運算式。

   如需運算式語法的相關資訊，請參閱 XPath 語法。

   此範例會使用 //Address 運算式搭配測試承載：

   

   附註

   雙斜線 (//) 會從符合選取範圍的目前節點中選取節點，而不論節點存在的位置為何。

5. 將 Execute XPath 函式連線到您要執行函式的目的地節點。

   此範例會將函式連線至目的地結構描述中的 [位址] 節點：

   

   附註

   節點名稱會自動以雙引號 (" ") 括住。

6. 測試您的對應，以確認預期的結果出現在目的地結構描述中。

   此範例會使用測試承載，並正確地產生具有多個 [地址] 節點的結果，因為來源 [地址] 節點存在於 Employee 陣列中，而目的地 [地址] 節點則存在於 Person 陣列中。

   

   附註

   如果您在來源和目標結構描述中建立陣列之間的對應，對應工具介面上會自動顯示迴圈來逐一查看陣列元素。 不過，您仍必須在來源與目標陣列元素之間建立對應。 如需循環陣列的相關資訊，請參閱逐一查看陣列。

建立自訂 XML 函式

若要在整個對應中定義可重複使用的邏輯，您可以建立自訂 XML 函式，以提供下列優點：

• 減少重複，並支持結構描述特定的轉換。
• 將複雜的邏輯包裝成可管理的元件。
• 處理結構描述特定的邊緣案例。

若要建立自訂 XML 函式，請遵循下列步驟：

1. 建立 XML (.xml) 檔案，其具有可描述函式用途的有意義名稱。

   您的 XML 檔案必須針對函式定義使用特定的結構描述。 如果您有多個相關函式，則可以針對這些函式使用單一檔案。 雖然您可以使用任何檔案名稱，但有意義的檔案名稱或類別可讓您的函式更容易識別、尋找和探索。

2. 將此 XML 檔案新增至下列資料夾中的邏輯應用程式專案：

   工件>DataMapper\擴充元件>函數

3. 開啟您想要在其中使用函式的資料對應。

4. 從 [函式] 窗格的 [公用程式] 底下，選取您的自訂函式，現在會出現在對應工具介面上。

5. 在對應工具介面上，選取您的函式。 提供函式需要運作的輸入。

6. 將函式連線到必要的端點。

   下列範例顯示名為 Age 的自訂函式，會傳回所提供出生日期的年齡。 函式會連線到 Dat_of_Birth 來源節點和 [其他] 目的地節點。 若要檢閱此自訂函式的定義，請參閱檢閱範例函式定義。

   

7. 測試您的對應，以確認預期的結果出現在目的地結構描述中，例如：

   

檢閱函式定義的結構描述

在您的 XML 檔案中，必須針對函式定義使用下列結構描述。 每個具有 "function" 名稱的 XML 元素會實作 XSLT 3.0 樣式函式，並多加一些屬性。 資料對應程式函式清單包含函式名稱、描述、參數名稱和參數類型。

<?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>

檢閱範例函式定義

下列 SampleFunctions.xml 檔案顯示下列函式的實作：

• "age"
• "custom-if-then-else"

<?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>

相關內容

• 新增對應來使用 Azure Logic Apps 以進行工作流程中的轉換