> ## Documentation Index > Fetch the complete documentation index at: https://docs.kasoftware.com/llms.txt > Use this file to discover all available pages before exploring further. # 配置對映 > 如何在知行之橋中配置對映，包括帶註釋的介面元素、節點型別、Foreach 迴圈、AI 輔助對映和最佳實踐。 export const companyName = "知行軟件"; export const siteNameShort = "知行之橋"; 下圖為已完成的 [XML Map](../connectors/xml-map/xml-map) 對映頁面，其中已對螢幕上的每個元素進行了註釋（[EDI 文件對映](../tpmc/edi-mapping) 類似）。每個數字對應下面的一個描述。 1. 文件或端口名稱。 2. 端口型別。 3. 對映的測試狀態。值為**測試成功**、**測試有錯誤**或**未測試**。 4. 切換 XML 流的開啟或關閉（預設開啟）。開啟時，對映引擎會在完成迴圈後丟棄對映中最頂層 `Foreach` 當前迭代的文件物件模型 (DOM)。這可以顯著提高大型 XML 文件的效能。當對映引擎無法解析對映時，它會自動關閉 XML 流。 5. 在對映的常規檢視和緊湊檢視之間切換（緊湊檢視對於大型範本檔案很有幫助）。 6. 切換是否顯示或隱藏 XML 屬性。 7. 重新整理對映。 8. 啟動 [AI 輔助對映](#ai-輔助對映)工具。 9. 開啟**測試對映**頁面。測試結果顯示在 #3 中。（有關更多資訊，請參閱[測試對映](#測試對映)。） 10. 儲存對映。 11. 選定的源範本檔案。 12. 對映的方向。 13. 選定的目標範本檔案。 14. 源端和目標端的搜尋欄。 15. 源 XML 的結構。 16. 父節點的名稱。 17. 葉節點的名稱。 18. 目標文件的結構。 19. 已完成的對映。 ## 瞭解源和目標 要定義對映，請點選左側窗格中的節點並將其拖動到右側窗格中其對應的物件上。選中某個節點後，其連線線為藍色，其他所有線均為黑色。 在源樹或目標樹中拖放元素時，拖放節點上的一條或兩條藍線會變暗/處於活動狀態，如下圖所示。如果兩條藍線都處於活動狀態，則被拖動的節點將建立為拖放節點的*兄弟*。如果只有右側的藍線處於活動狀態，則被拖動的節點將建立為拖放節點的*子級*。在下圖中，N103 節點從 N104 下方移至 N102 節點的直接兄弟，因此兩條藍線均突出顯示。 要移除對映，請將滑鼠懸停在對映的一端，然後點選**移除對映**。完成對映定義後，點選**儲存**。 ## 對映節點 父節點和葉節點定義 XML 資料的層次結構，其中父節點將相關元素分組，葉節點表示要對映的實際資料值。 * **父節點**：XML 對映樹中包含葉元素但沒有值的節點。父節點類似於 [TPMC](../tpmc/tpmc) 中的[表節點](../tpmc/edi-mapping#table-nodes)。 * **葉節點**：包含值但沒有子元素的節點。葉節點類似於 TPMC 中的[列節點](../tpmc/edi-mapping#column-nodes)。 以下部分詳細介紹了父節點和葉節點選項。 ### 父節點 #### XML 父元素 如前所述，對映編輯器中的樹有兩種型別的節點： * *父節點* 有子節點但沒有值。 * *葉節點* 有值但沒有子節點。 源中的父節點只能拖動到目標中的父節點上。 將源父節點拖動到目標父節點上會在源節點和目標節點之間建立 `Foreach` 關係。這意味著源元素的每次出現都會生成一個對應的目標元素，包括目標元素的所有子元素。 一旦建立了 Foreach 關係，目標中就會出現一個 xpath，如下圖所示。輸入 XML 中此路徑上的元素會生成輸出節點及其子節點的新例項。換句話說，Foreach 關係指示對映引擎迴圈遍歷源中的給定 xpath，併為找到的每個元素生成對映的目標結構。目標樹檢視中的 xpath 就是對映引擎迴圈遍歷的 xpath。 #### 虛擬迴圈 虛擬迴圈是一種特殊節點，可以將其新增到目標結構中，但該節點不會直接出現在輸出 XML 中。它提供了一個機會，可以實現影響輸出中其他（非虛擬）節點的外觀和/或值的邏輯。 它的功能與父節點之間的 Foreach 對映相同，只是父節點不會出現在輸出 XML 中。這允許您將源中的重複元素展平為目標中的非層次結構。透過範例更容易理解這一點。 以以下輸入 XML 為例： ```xml theme={null} 212.5 9.2 5.1 ``` 這需要對映到包含所有 *DataReading* 資料的平面結構： ```xml theme={null} 212.5 9.2 5.1 ``` 可以透過與目標中與源中每個 *DataReading* 元素對應的迴圈節點建立 Foreach 關係來實現此目的： 如果在 *DataReading* 和 *OutputData* 之間建立 Foreach 關係，則結果中會重複 *OutputData* 元素。迴圈節點可以避免這種層級重複，並將值展平到單個 *OutputData* 元素中。 要新增上例中所示的迴圈節點，請按以下步驟操作： 1. 右鍵單擊 *TemperatureReading* 節點，或單擊省略號，然後選擇**新增節點 > 新增迴圈**。為迴圈指定一個有意義的名稱，然後點選複選標記進行儲存。 2. 將源 *DataReading* 節點拖到迴圈上以建立 Foreach 關係。 3. 將源 *Temperature* 節點對映到目標 *TemperatureReading* 節點。 #### 虛擬條件 虛擬條件基於共享條件將輸出元素組合在一起。如果條件為真，則條件節點的所有子節點都會出現在輸出中；如果條件為假，則不會出現。 這在功能上相當於將相同的條件分別新增到每個單獨的節點。對於影響多個不同節點的條件，通常更方便的做法是建立一個條件節點，然後將所有相關的輸出節點設為該條件節點的子節點。 要建立條件虛擬節點，請按以下步驟操作： 1. 右鍵單擊目標節點或單擊省略號，然後選擇**新增節點 > 新增條件**。 2. 單擊新條件旁邊的漏斗圖示以建立條件規則。有關詳細資訊，請參閱[使用條件編輯器](./mapping-condition-editor)。 ### 葉節點 #### XML 葉元素 將源葉節點拖放到目標葉節點上，會指示對映引擎使用源元素的值填充目標元素。拖放到目標節點後，目標樹檢視中將顯示讀取值的 xpath，如下圖所示。 目標樹檢視中顯示的 xpath 是*絕對*或*相對*的。絕對 xpath 以斜槓 (/) 開頭，描述源中的完整 xpath，從文件的根開始。相對 xpath 不以斜槓開頭，它們相對於父節點中設定的 Foreach 迴圈。 相對 xpath 可以相對於多個 Foreach 迴圈（只要元素有多個父元素，並且每個父元素都對映了 Foreach 關係）。要找到任何給定相對 xpath 的絕對 xpath，只需連線每個父級的 Foreach xpath，從文件頂部開始，直到到達當前節點。 #### XML 屬性 除了元素值之外，要使用 XML 屬性，請確保已啟用對映頁面頂部的**顯示屬性**設定（attributes）。啟用後，編輯器將顯示檢測到的作為其所屬元素子元素的所有屬性。 所有 XML 屬性名稱都以 `@` 為字首（`@` 符號在 XML 元素名稱中無效）。此字元僅用於顯示，在讀取或寫入屬性時會被刪除。 ##### 從源讀取 XML 屬性 啟用**顯示屬性**開關後，XML 源中的任何屬性都會在對映編輯器中顯示為節點。您可以像其他節點一樣將這些值拖放到目標節點上。節點顯示 `@` 字首，表示它們是 XML 屬性，而不是 XML 元素，如下圖所示。 ##### 在目標中寫入 XML 屬性 包含 XML 屬性的目標範本會將屬性節點顯示為其所屬元素的子節點，並且這些節點可以像任何其他值一樣進行對映。 要向目標節點新增新屬性，請右鍵單擊或點選節點上的省略號，然後選擇**新增節點 > 新增屬性**。 屬性名稱始終以 `@` 字首開頭（此字元不包含在輸出 XML 中）。 #### 標頭 標頭節點允許您將值對映為對映輸出訊息的標頭。這些標頭節點不包含在輸出 XML 中，但會作為中繼資料訊息標頭新增到輸出訊息中。這些標頭在整個流程中與訊息保持一致，並且任何下游端口都可以根據需要引用它們的值，從而可以輕鬆跟蹤資料在應用程式中的進度。標頭節點會自動新增到節點值編輯器中的**訊息頭**索引標籤中。要新增標頭節點，請右鍵單擊或點選現有節點上的省略號，然後選擇**新增 > 新增標頭**。 標頭節點不會新增到[跟蹤頭](../getting-started/administration/activity#tracked-headers)。您可以透過點選節點上的省略號並選擇**新增跟蹤**將非標頭目標節點新增到跟蹤頭。有關更多資訊，請參閱[訊息頭](./mapping-node-value-editor#message-headers)。 #### 程式碼指令碼 程式碼指令碼虛擬節點提供了編寫自定義 ArcScript 的機會，這些指令碼無需傳回輸出值。通常，這些節點使用[變數](./mapping-node-value-editor#variables)或特殊的 `_map` 項來儲存稍後需要在對映中引用但不需要在當前上下文中輸出的值。 例如，[對映項](../connectors/xml-map/xml-map-advanced#map-item)部分中描述的場景就非常適合使用虛擬程式碼指令碼節點。訂單項成本總和需要在計算該值的 `Foreach` 迴圈之外作為輸出傳回。因此，Foreach 迴圈中的虛擬程式碼指令碼節點可以計算該值但不輸出。然後，該值可以在迴圈之外的非虛擬節點中作為輸出引用。 要建立程式碼指令碼虛擬節點，請按以下步驟操作： 1. 右鍵單擊目標節點或點選省略號，然後選擇**新增節點 > 新增程式碼指令碼**。 2. 輸入**指令碼名稱**。 3. 提供指令碼。編輯器會在您輸入時驗證運算式，因此如果您看到**無效指令碼**訊息，則表示存在語法問題。完成後，點選**新增指令碼**。 #### 變數節點 在對映中的某個位置設定變數，並在之後的對映中再次引用這些變數會很有用。有關詳細資訊和範例，請參閱[變數](./mapping-node-value-editor#variables)。 ### 節點選項 要處理單個節點，請將滑鼠懸停在節點上，然後右鍵單擊或單擊省略號以從一組附加選項中進行選擇。選項會根據正在處理的節點型別而有所不同。本節介紹處理父節點、葉節點或文件節點時可用的選項。有關這些節點型別的詳細資訊，請參閱[表節點](../tpmc/edi-mapping#table-nodes)和[列節點](../tpmc/edi-mapping#column-nodes)。 * **重新命名節點** 允許更改節點的名稱。 * **編輯 XPath** 允許編輯節點 XPath（僅限已對映為 `Foreach` 的元素）。 * **刪除節點** 允許您從文件中刪除節點。 * **新增節點** * **新增兄弟節點** 可在所選節點的同一級別新增一個節點。 * **新增屬性** 可為所選節點新增屬性。 * **新增子節點** 會將一個節點新增為所選節點的子節點。 * **新增標頭** 會建立一個標頭節點，您可以將值對映到該標頭節點。對映的值不會包含在輸出檔案中，但會作為標頭新增到對映輸出訊息中。 * **新增迴圈** 會在所選節點上方建立一個迴圈節點，該節點將巢狀在迴圈節點中。有關更多資訊，請參閱[對映迴圈](#對映迴圈)。 * **新增條件** 會開啟[條件編輯器](./mapping-condition-editor)，您可以在其中新增條件，以便只有當條件為真時，資料才會更新插入到目標。 * **新增程式碼指令碼** 會建立一個新的指令碼節點作為目標元素的同級節點。使用**新增指令碼**視窗命名指令碼並提供自定義 ArcScript。 * **新增變數** 會在所選節點下方建立一個變數節點。有關更多資訊，請參閱[變數](./mapping-node-value-editor#variables)。 * **剪下節點** 將從當前位置剪下所選節點。 * **複製節點** 複製所選節點。 * **貼上為子節點** 將剪下或複製的節點貼上為所選節點的子節點。 * **新增跟蹤** 將[跟蹤頭](../getting-started/administration/activity#tracked-headers)新增到對映中。啟用跟蹤的節點會顯示指南針圖示。 還可以使用**編輯節點**開啟**編輯節點值**頁面。請參閱[使用節點值編輯器](./mapping-node-value-editor)。 ## AI 輔助對映 在例項上設定 [AI 設定](../getting-started/administration/settings/ai-settings)並上傳或設定源和目標範本檔案後，可以使用任何受支援的大語言模型 (LLM) 來協助構建對映。此功能透過提供智慧對映建議解決了對映配置難題，從而顯著簡化了建立精確資料轉換的過程。 使用的 LLM 必須支援結構化輸出。{companyName} 已確認以下模型提供可靠的結構化輸出： * Claude: Opus 4.6 * Gemini: gemini-3-pro * Grok: grok-4-fast-non-reasoning * Ollama Cloud: glm-4.6 * OpenAI: gpt-5.4 要讓 AI 生成整個對映，請點選頁面頂部的 AI Assisted Mapping 圖示。如果嘗試使用不支援結構化輸出的模型，該圖示將被停用。 或者，可以讓 AI 在節點級別生成對映。右鍵單擊源或目標端的父節點或使用省略號，選擇 **AI 輔助對映**，然後選擇以下選項之一： * 對映節點 * 對映子節點 * 節點和子節點 AI 生成對映後，可以根據需要進行調整。 如果在 [XML Map](../connectors/xml-map/xml-map) 端口上使用此功能，可以自定義應用程式用於建立對映的使用者提示和系統提示。有關詳細資訊，請參閱 [XML Map 進階設定](../connectors/xml-map/xml-map-configuration#advanced-settings)。 ## 對映迴圈 建立父節點對映會在源節點和目標節點之間建立 `Foreach` 關係。這意味著源元素的每次出現都會生成一個對應的目標元素，包括目標元素的所有葉節點。建立葉節點對映會指示對映引擎使用源元素的值填充目標元素。 先對映父節點（Foreach 迴圈），然後再對映葉節點。建立迴圈關係需要了解源和目標 XML 結構：每當源中的重複元素應導致目標中的重複元素時，這些元素都應在 Foreach 關係中一起對映。 在 Foreach 迴圈中，葉元素 xpath 是相對於對映的 Foreach xpath 的。 作為一個非常簡單的範例，請考慮以下源和目標 XML，其中巢狀 XML 結構應轉換為扁平 XML 結構： ```xml theme={null}
``` ```xml theme={null} ``` 源中每次重複 *customer* 元素，目標中都會生成一個 *customerInfo* 元素，因此這些父元素應該對映在一起，形成 Foreach 關係。這樣，每個葉元素的對映就很簡單了： 請注意，葉元素的 xpath 是相對於父元素中的 xpath（定義 Foreach 關係的 xpath）。 ### 對映多個迴圈 對映通常需要在同一文件中建立多個 Foreach 迴圈關係。對映迴圈的原則保持不變：源文件中任何重複的父元素，如果在目標文件中應該生成重複的元素，都應該對映為迴圈。先對映外層迴圈，再對映內層迴圈（換句話說，從結構的頂部開始向下對映）。所有迴圈關係都應在對映任何葉元素之前進行對映。 舉一個常見的例子，考慮將傳入的採購訂單報告對映到目標資料庫。此類對映包含兩個可能重複的不同元素結構，因此每個結構都需要一個 Foreach 關係：(1) 單個報告可能包含多個單獨的訂單，以及 (2) 單個訂單可能包含多個行專案。 ### 範例輸入 源範本結構可能如下所示： ```xml theme={null} John Doe 12/21/22 Hammer 1500 1 Standard claw hammer Nail 10 20 Ten penny nails 1700 4 ``` 為簡潔起見，此範例僅包含一個 *WebOrder* 元素，但對映應該處理同一個 *OrderReport* 中包含多個 *WebOrder* 部分的情況。 ### 範例輸出 此對映的輸出應與資料庫插入的 XML 模型匹配。資料庫插入的 XML 模型由資料庫端口（例如 MySQL、SQLite 和 CData 端口）自動建立，[資料庫端口中的範本檔案](../connectors/xml-map/xml-map-template-files#template-files-from-database-connectors)部分介紹瞭如何在 XML Map 端口中將這些 XML 模型用作範本檔案。 正確的資料庫設計建議將資料插入兩個單獨的表中，一個用於 Orders，一個用於 Line Items。為此方法生成合適的輸入對映可以生成如下範本結構： ```xml theme={null} ``` 在此範例中，*Order* 元素表示向 Orders 表中插入資料，而 *OrderLine* 元素表示向 Line Items 表中插入資料。生成的範本僅包含一個代表每個表的元素，但對映期間建立的 Foreach 關係可確保建立適當數量的插入資料。 *Order* 的其他子元素（*FirstName*、*LastName*、*Date*）表示 Orders 表中的列，而 *OrderLine* 的子元素（*SKU*、*Price* 等）表示 Line Items 表中的列。 ### 建立迴圈關係 源中的 *WebOrder* 元素應該會在 Orders 表中插入一條新資料，因此應將其拖放到目標中的 *Order* 元素上。同樣，源中的 *Line* 元素應該會在 Line Items 表中插入一條新資料，因此應將其拖放到目標中的 *OrderLine* 元素上。 建立這兩個 Foreach 關係後，對映編輯器應如下所示： 建立迴圈關係並刪除所有不必要的目標元素後，可以對映葉元素以填充目標值： ## 不必要的父節點 建立 Foreach 關係時，來源檔案和目的檔案中只需存在一個對映元素例項。換句話說，Foreach 關係負責確保輸出元素的數量與相應輸入元素的數量匹配。 為了更清楚地說明這一點，假設在[對映迴圈](#對映迴圈)範例中，來源檔案（輸入 XML 的範本）包含多組 *customer* 元素組。在 *customer*（源）和 *customerInfo*（目標）之間建立單個 Foreach 關係，可確保 *customerInfo* 元素組的數量與任何輸入檔案中的 *customer* 元素組數量匹配。由於只需一個 *customer* 元素即可建立此 Foreach 關係，因此所有其他 *customer* 元素與對映無關，可以忽略或刪除。 同樣，如果上例中的目的檔案包含多個 *customerInfo* 元素，則應刪除除一個之外的所有元素。*customer* 和 *customerInfo* 之間的 Foreach 關係確保在 XML 輸出中出現適當數量的 *customerInfo* 元素組。 ## 測試對映 使用**測試對映**按鈕檢查對映是否按預期工作。測試會使用來源檔案中的值填充目標元素，如下所示： 如果測試失敗，**目標**窗格將提供失敗的解釋。 ## 對映最佳實踐 Foreach 迴圈是對映目的檔案中重複元素的強大工具。但是，遵循以下最佳實踐至關重要，以確保功能正常並避免效能問題： * 使用大型 XML 檔案時，避免將整個檔案對映為 Foreach 迴圈。這種對映方式會指示對映引擎將整個檔案載入到記憶體中，這可能會導致較長的處理時間。 * 相反，最佳做法是牢記完整的源文件結構，並且只為已知重複的元素建立 Foreach 關係（如上文[建立迴圈關係](#建立迴圈關係)中所述）。這種做法可以最大限度地減少與 Foreach 關係相關的效能影響。