共用方式為

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

  • 發行項

適用於：Azure Logic Apps (標準)

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

若要定義數據結構之間的轉換，並橋接任何間距，您可以建立對應 （.xslt 檔案），以指定來源和目標架構中數據元素之間的關聯性。 您可以在標準邏輯應用程式項目的內容中使用 Visual Studio Code 搭配 Azure Logic Apps （Standard） 延伸模組，以可視化方式建立或編輯地圖。 數據對應工具提供統一的對應和轉換體驗，使用拖放手勢、用於建置表達式的預先建置函式，以及在工作流程中使用地圖之前手動測試地圖的方法。

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

本作說明指南示範如何建立空的數據對應、選擇來源和目標架構、在架構元素之間建立各種對應、儲存和測試對應，然後從邏輯應用程式專案中的工作流程呼叫對應。

限制和已知問題

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

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

  • 數據對應程式目前不支援使用逗號分隔值 （.csv） 檔案格式的架構。

  • 數據對應工具中的 [ 程序代碼 ] 窗格目前是唯讀的。

  • 數據對應工具中的版面配置和專案位置目前為自動且只讀。

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

  • 當您在來源和目標架構中建立父陣列元素之間的對應時，對應程式會自動新增迴圈來逐一查看陣列項目元素。 不過，您仍然必須明確建立來源和目標數位專案專案項目之間的對應。

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

  • 若要使用您在 Azure 入口網站 中使用數據對應工具建立的對應，您必須將它們直接新增至標準邏輯應用程式資源。

  • 此版本目前不支援自定義函式。

必要條件

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

    注意

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

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

    • 副檔名為 .xsd 的 XML 結構描述定義檔案
    • 副檔名為 .json 的 JavaScript 物件標記法檔案

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

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

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

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

  • 若要使用執行 XSLT 函式，您的 XSLT 程式碼片段必須存在於使用 .xml 或 .xslt 副檔名的檔案中。 您必須將 XSLT 程式碼片段放在本機專案資料夾結構的 InlineXslt 資料夾中：Artifacts>DataMapper>Extensions>InlineXslt。 如果此資料夾結構不存在，請建立遺漏的資料夾。

建立資料對應

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

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

  3. 在 Azure 視窗的 [資料對應程式] 底下，選取 [建立數據對應]。

    顯示 Visual Studio Code 的螢幕快照，其中包含 Azure 視窗和 [建立數據對應] 的已選取按鈕。

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

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

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

    顯示提示方塊和範例數據對應名稱的螢幕快照。

    數據對應工具會建立並開啟空白的數據對應。

  5. 請遵循下列步驟來選擇您的來源和目標架構：

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

      顯示 [數據對應程式] 和 [來源] 窗格的螢幕快照，其中包含 [新增] 和 [流覽] 的選取選項。

      新增來源架構之後，[ 來源 ] 窗格會填入來源架構中數據類型的 XML 元素 「nodes」，例如：

      顯示 [來源] 窗格的螢幕快照，其中包含來源架構 XML 元素節點。

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

      顯示 [數據對應程式] 和 [目的地] 窗格的螢幕快照，其中包含 [新增] 和 [流覽] 的選取選項。

      新增目標架構之後， [目的地 ] 窗格會填入目標架構中數據類型的 XML 元素 “nodes”，例如：

      此螢幕快照顯示已填入來源架構 XML 元素節點的 [目的地] 窗格。

提示

如果您在載入架構時遇到問題，您可以在本機將來源和目標架構檔案新增至邏輯應用程式專案的 Artifacts/Schemas 資料夾。 在此案例中，若要在 [數據對應程式] 中指定您的來源和目標架構，請在 [來源 ] 和 [目的地 ] 窗格中開啟 [ 選取現有的 清單]，而不是使用 [新增]，然後選取您的架構。

架構數據類型

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

符號 類型 其他資訊
代表陣列數據類型的圖示。 複雜 （陣列） 包含專案或重複的項目節點。

陣列元素也會顯示下列連接點：

陣列項目連接點的圖示。
代表Bool資料類型的圖示。 Bool 僅限 True 或 false
代表複雜數據類型的圖示。 Complex 具有子系屬性的 XML 物件，類似於物件 JSON 類型
代表 DateTime 資料類型的圖示。 Datetime
代表十進位數據類型的圖示。 Decimal
代表 Integer 資料類型的圖示。 整數 僅限整數
代表 String 數據類型的圖示。 String

建立元素之間的直接對應

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

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

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

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

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

  3. 將滑鼠指標移至來源項目名稱旁邊的圓形，直到指標變更為加號 （+）。

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

    此螢幕快照顯示具有來源元素指標的數據對應程式。

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

    此範例會使用 標識符 目標元素完成對應，其數據類型與來源專案相同。

    此螢幕快照顯示數據對應程式、目標元素上的指標，以及來源和目標元素之間的一行。

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

    螢幕快照顯示來源和目標架構中 EmployeeID 與標識碼之間的完整對應。

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

    此螢幕快照顯示 [程序代碼] 窗格，分別對應來源和目標架構中的 EmployeeID 和 ID。

    提示

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

    此螢幕快照顯示不相符數據類型之間的對應。

建立元素之間的複雜對應

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

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

顯示範例函式標籤的螢幕快照。

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

群組 函式範例
集合 Average、Count、Direct Access、Distinct values、Filter、Index、Join、Maximum、Minimum、Reverse、Sort、Subsequence、Sum
轉換 至日期、整數、數位、字串
日期和時間 新增天數、目前日期、目前時間、等於日期
邏輯比較 Equal、Exists、Greater、Greater 或 equal、If、If Else、Is Nil、Is Null、is number、is string、less、less 或 equal、logical AND、Logical NOT、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
String 字串、Concat、Contains、End with、Length、Lowercase、Name、Regular Expression Matches、Regular Expression Replace、Replace、Replace、Starts with、String to Codepoints、Substring、Substring after、Substring before、Trim、Trim Left、Trim Right、Uppercase
Utility Copy、Error、Execute XPath、Format DateTime、Format Number、Run XSLT

新增不含對應的函式

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

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

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

    此範例會選取 [轉換函式] 群組中的 [到日期] 函式。

    此螢幕快照顯示名為 To Date 的選取函式。

    注意

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

    此螢幕快照顯示名為 To Date 的已中斷連線函式。

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

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

      此螢幕快照顯示來源專案與函式之間的對應。

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

      此螢幕快照顯示函式與目標專案之間的對應。

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

    顯示程式代碼窗格的螢幕快照，其中包含來源與目標專案之間的直接對應關聯性。

  4. 在對應器介面上，選取函式圖形以檢視函式詳細數據。

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

    此螢幕快照顯示名為 To Date 之函式的 [輸入] 索引標籤。

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

新增使用多個輸入的函式

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

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

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

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

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

    此螢幕快照顯示名為 Concat 的選取函式。

    注意

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

    此螢幕快照顯示名為 Concat 的已中斷連線函式。

  3. 在對應器介面上，選取函式圖形以檢視函式詳細數據。

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

    此範例會 選取 FirstName 和 LastName 來源架構元素作為函式輸入。 對應程式會自動新增來源專案與函式之間的個別對應。

    顯示多個來源元素作為函式輸入的螢幕快照。

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

    此螢幕快照顯示多個輸入、Concat 函式和目標元素之間的完成對應。

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

    此螢幕快照顯示具有 Concat 函式的程式代碼窗格，其中包含多個輸入和單一輸出。

逐一查看陣列

如果您的來源和目標架構包含陣列，您可以建立循環來逐一查看陣列的專案。 本節中的範例會透過 Employee 來源陣列和 Person 目標陣列建立迴圈，以及數位專案之間的對應。

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

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

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

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

    此螢幕快照顯示對應程式介面，並繪製來源 Employee 和目標 Person 陣列中 [名稱] 專案之間的對應。

    完成對應第一組陣列之後，對應程式會自動在來源和目標陣列父元素之間新增迴圈，其具有下列連接點類型： 陣列元素已完成連接點的圖示。

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

    此螢幕快照顯示來源 Employee 與目標 Person 父陣列之間的循環對應。

    [程序 代碼 ] 窗格會顯示您所建立的對應和循環：

    顯示程式代碼窗格的螢幕快照，其中包含來源和目標父陣列與陣列專案之間的循環對應。

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

    此螢幕快照顯示來源和目標陣列中其他陣列專案之間的更多對應。

評估條件以執行工作

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

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

函式群組 函式 此範例中的用途
比較 大於 檢查購買數量是否超過 20。
比較 If 檢查 Greater 函式是否傳回 true。
數學運算 乘積 如果 condition 為 true，請將項目價格乘以 10% 以計算折扣。

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

    此範例使用下列元素：

    • 來源 窗格： ItemPrice 和 ItemQuantity

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

      顯示地圖工具介面和數據元素的螢幕快照，例如條件案例。

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

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

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

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

    顯示地圖工具介面、數據元素和函式的螢幕快照，例如條件案例。

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

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

    此範例會以指定的順序連接下列專案，以正確建立對應：

    啟動 尾端
    ItemPrice 來源專案 ItemPrice 目標元素
    ItemQuantity 來源專案 圖形左邊緣的更大 函式輸入。 此輸入會提供函式詳細數據中 [值 1] 欄位的數據。
    圖形右邊緣的更大 函式輸出 如果 函式的輸入位於圖形的左邊緣。 此輸入會提供函式詳細數據中 [條件] 欄位的數據。
    ItemPrice 來源專案 將函式的輸入乘 以圖形左邊緣。 此輸入會提供函式詳細數據中 Multiplicand 欄位的數據。
    將函式的輸出乘 以圖形右邊緣。 如果 函式的輸入位於圖形的左邊緣。 此輸入會提供函式詳細數據中 [值] 欄位的數據。
    如果 函式的輸出位於圖形的右邊緣。 ItemDiscount 目標專案

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

    此螢幕快照顯示對應程式介面、數據元素和函式，以及範例條件案例的對應。

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

    函式 輸入域和值
    大於 - 值 1： ItemQuantity 來源元素
    - 值 2： 20 做為自定義值
    乘積 - Multiplicand 1： ItemPrice 來源元素
    - 多重和 2： .10 做為自定義值
    If - 條件： 大於（ItemQuantity， 20）
    - 值：multiply(ItemPrice, .10)

    下圖顯示完成的範例：

    顯示已完成條件範例的螢幕快照。

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

    此螢幕快照顯示程式代碼窗格，其中包含來源和目標專案之間的條件式對應，使用函式、較大、乘法和 If。

儲存您的對應

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

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

  • your-map-name.love> my life file in the Artifacts>MapDefinitions project folder <
  • 在 Artifacts>Maps 專案資料夾中的 <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 檔案）。

    顯示 Visual Studio Code、標準工作流程設計工具的螢幕快照，其中包含使用數據對應程式 XSLT 和動作屬性命名為 Transform 的選取動作。

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

相關內容