> ## 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.

# CSV Map 端口

> 使用視覺化設計器或 ArcScript 指令碼檢視，將平面 XML 檔案轉換為 CSV、TSV 和 PSV 格式。

CSV Map 端口使用 ArcScript 將平面 XML 檔案轉換為 CSV、TSV 和 PSV 檔案格式。平面 XML 檔案是指除根元素之外深度不超過兩層的檔案。

## 核心功能

* 使用 ArcScript 範本將扁平 XML 檔案轉換為 CSV、TSV 和 PSV 格式
* 提供用於簡單對映的視覺化設計器（支援欄位自動匹配），併為複雜轉換提供程式碼檢視
* 支援透過 XPath 導航從巢狀 XML 結構中提取值，並具備動態範本生成功能

## 概覽

CSV Map 端口有兩種操作模式，視覺化**設計器**和以指令碼為中心的**指令碼**。設計器支援在文件型別之間視覺化地建立簡單的關係。更復雜的翻譯需要指令碼，指令碼利用強大的 ArcScript 指令碼語言在 XML 和平面檔案結構之間建立對映範本。

首先，在"設定"索引標籤中上傳一個範例**來源檔案**和**目的檔案**。如果兩個範例檔案的結構都允許設計器驅動的對映，則視覺化設計器將填充源和目標欄位。該應用程式還將嘗試用儘可能多的目標結構填充指令碼視窗。

## 端口配置

本節包含所有可配置的端口屬性。

### 對映索引標籤

*上傳檔案以啟動源欄位和目標欄位的設計驅動對映。*

點選 **上傳檔案**，然後選擇您的來源檔案和目的檔案。

* **來源檔案** 代表輸入文件的 XML 結構。端口處理的任何檔案都應具有匹配的 XML 結構。要支援設計驅動對映，此檔案必須是簡單的 XML、CSV、PSV 或 TSV 結構。
* **目的檔案** 代表輸出文件的結構。要使用設計驅動對映，此檔案必須是簡單的 XML、CSV、PSV 或 TSV 結構。

#### 對映

定義輸入和輸出檔案之間的對映關係。設計器檢視可以對映簡單的 XML、CSV、TSV 和 PSV 結構，而指令碼檢視可以對映更復雜的 XML 結構。有關更多詳細資訊，請參見[使用設計器](#使用設計器)和[使用指令碼檢視](#使用指令碼檢視)。

### 設定索引標籤

#### 端口配置

*與端口核心操作有關的設定。*

<table><thead><tr><th>設定</th>
<th>描述</th></tr></thead>
<tbody><tr><td>**端口 Id**</td>
<td>端口的靜態、唯一識別碼。</td></tr>
<tr><td>**端口型別**</td>
<td>顯示端口型別及其用途的描述。</td></tr>
<tr><td>**端口描述**</td>
<td>一個可選欄位，用於提供端口及其在流中的角色的自由格式描述。</td></tr></tbody></table>

### 進階設定

#### 進階設定

| 設定 | 描述 |
| - | - |
| **處理延遲** | **交易**索引標籤中檔案的處理延遲時間（秒）。這是一個遺留設定。最佳實踐是[使用檔案端口](https://docs.kasoftware.com/26.4/self-hosted/zh-Hant/flows/designing-a-flow.md#與本地檔案系統互動)來管理本地檔案系統，而不是使用此設定。 |
| **本地檔名格式** | 為端口輸出的訊息分配檔名的方案。可以在檔名中動態使用宏來包含識別碼和時間戳等資訊。有關更多資訊，請參閱[宏](#宏)。 |

#### 訊息

*訊息設定確定端口如何搜尋訊息並在處理後管理它們。*

**注意：**以下設定已棄用，預設處於隱藏狀態。只有先前已啟用這些設定或將其配置為非預設值的端口才會顯示它們。若要保留成功處理的檔案副本，請在工作流程中右鍵單擊該端口，選擇**顯示成功路徑**，然後將成功路徑連線到 [File 端口](https://docs.kasoftware.com/26.4/self-hosted/zh/connectors/file.md)。

<table><thead><tr><th>設定</th><th>描述</th></tr></thead>
<tbody><tr><td>**儲存到已傳送資料夾**（已棄用）</td>
<td>將端口處理的檔案複製到 Sent 資料夾。預設停用。儲存到 Sent 資料夾中的檔案不受[靜態加密](https://docs.kasoftware.com/26.4/self-hosted/zh/getting-started/administration/settings/encryption-at-rest.md)保護。</td></tr>
<tr><td>**已傳送資料夾方案**（已棄用）</td>
<td>按所選時間間隔對 **Sent** 資料夾中的檔案進行分組。僅在啟用**儲存到已傳送資料夾**時適用。</td></tr></tbody></table>

#### 日誌

*用於管理日誌建立和儲存的設定。*

<table><thead><tr><th>設定</th>
<th>描述</th></tr></thead>
<tbody><tr><td>**日誌級別**</td>
<td>指定要記錄在端口日誌目錄中的資訊型別：
<ul><li>**None** - 不建立任何日誌。</li>
<li>**Error** - 僅當端口遇到錯誤時才建立日誌。</li>
<li>**Warning** - 僅當端口發出警告時才建立日誌。</li>
<li>**Info** - 記錄工作流程的一般資訊，包括任何錯誤和警告（如果適用）。</li>
<li>**Debug** - 記錄成功和失敗工作流程的詳細偵錯資訊。</li>
<li>**Trace** - 記錄成功和失敗工作流程的詳細跟蹤資訊。</li></ul>
\*\*請注意：\*\***Debug** 和 **Trace** 級別的日誌可能會記錄敏感資訊，包括訊息內容和 SSL 憑證。儘管連線屬性（例如密碼）被遮蔽了，但在與您的組織外部共享它們之前，請檢視此級別的日誌以避免洩漏敏感資訊。</td></tr>
<tr><td>**日誌資料夾結構**</td>
<td>指示端口根據選定的時間間隔將日誌資料夾中的檔案分組。例如，**Weekly** 選項指示端口每週建立一個新的子資料夾，並將該周的所有日誌儲存在該資料夾中。空白設定告訴端口將所有日誌直接儲存在日誌資料夾中。對於處理許多交易的端口，使用子資料夾有助於保持日誌的有序性並提高效能。</td></tr>
<tr><td>**保留訊息副本**</td>
<td>指示端口在日誌目錄中儲存最新訊息副本的切換。請注意，端口每個子資料夾只保留一個訊息，並且端口在再次執行時會覆蓋以前儲存的訊息。</td></tr></tbody></table>

#### 其他

*特殊設定適用於特定用例。*

<table><thead><tr><th>設定</th>
<th>描述</th></tr></thead>
<tbody><tr><td>**其他設定**</td>
<td>允許在以分號分隔的清單中配置隱藏的端口設定，例如 `setting1=value1;setting2=value2`。正常的端口用例和功能不需要使用這些設定。</td></tr></tbody></table>

### 自動化索引標籤

#### 自動化

*與端口自動處理檔案相關的設定。*

| 設定 | 描述 |
| - | - |
| **傳送** | 到達端口的訊息是否會被自動處理。 |

#### 效能

*與端口資源分配相關的設定。*

<table><thead><tr><th>設定</th>
<th>描述</th></tr></thead>
<tbody><tr><td>**最大工作執行緒數**</td>
<td>此端口上處理檔案時從執行緒池中消耗的最大工作執行緒數。如果設定，則會覆蓋 [進階設定](https://docs.kasoftware.com/26.4/self-hosted/zh/getting-started/administration/settings/advanced-settings.md) 頁面的 [效能設定](https://docs.kasoftware.com/26.4/self-hosted/zh/getting-started/administration/settings/performance-settings.md) 部分的預設設定。</td></tr>
<tr><td>**最大檔案數**</td>
<td>分配給端口的每個執行緒傳送的最大檔案數。如果設定，則會覆蓋 [進階設定](https://docs.kasoftware.com/26.4/self-hosted/zh/getting-started/administration/settings/advanced-settings.md) 頁面的 [效能設定](https://docs.kasoftware.com/26.4/self-hosted/zh/getting-started/administration/settings/performance-settings.md) 部分的預設設定。</td></tr></tbody></table>

### 通知索引標籤

*與配置通知相關的設定。*

在執行服務級別協議 (SLA) 之前，需要設定電子郵件通知以接收通知。預設情況下，知行之桥 使用 [通知](https://docs.kasoftware.com/26.4/self-hosted/zh/getting-started/administration/settings/alerts.md) 索引標籤上的全域設定。要為此端口使用其他設定，請啟用 **覆蓋全域設定**。

預設情況下，錯誤通知處於啟用狀態，這意味著每當出現錯誤時都會傳送電子郵件。要關閉錯誤通知，請取消選中 **啟用** 核取方塊。

輸入 **主題**（必填）。勾選**允許在主題中使用 ArcScript**，即可在**主題**欄位中使用 ArcScript。選中後會顯示 **ArcScript 編輯器**按鈕（![ArcScript 編輯器按鈕](https://docs.kasoftware.com/26.4/images/rest_arcscript_editor.png)）。

（可選）輸入以逗號分隔的**收件人**電子郵件地址清單。

### SLA 索引標籤

*與配置服務級別協議 (SLA) 相關的設定。*

SLA 允許配置預期流程中端口傳送或接收的資料量，並設定預期達到該資料量的時間範圍。當 SLA 未達到時，知行之桥 會傳送電子郵件警告使用者，並將 SLA 標記為 *存在風險*，這意味著如果 SLA 未能儘快達到，則會被標記為 *已違反*。這讓使用者有機會介入並確定 SLA 未達到的原因，並採取適當的措施。如果在風險時間段結束時仍未達到 SLA，則會將 SLA 標記為已違反，並再次通知使用者。

SLA 轉換為 *存在風險* 或 *已違反* 狀態時，也會寫入[應用程式日誌](https://docs.kasoftware.com/26.4/self-hosted/zh/getting-started/administration/activity.md#应用程序日志)，這意味著應用程式效能監控 (APM) 和日誌擷取工具也可以針對這些狀態發出警示。

要定義 SLA，請啟用 **預期資料量**，然後點選 **設定** 索引標籤。

![SLA Empty](https://docs.kasoftware.com/26.4/images/sla_empty.png)
<ul><li>如果端口具有單獨的傳送和接收操作，請使用選項按鈕指定 SLA 適用的方向。</li>
<li>在視窗的 **預計至少** 部分中：
<ul><li>設定預計處理的最小交易數量（交易量）</li>
<li>使用 **每個** 欄位指定時間範圍</li>
<li>指示 SLA 生效的時間。如果選擇 **開始於**，請填寫日期和時間欄位。</li>
<li>勾選希望 SLA 生效的星期幾對應的核取方塊。如有必要，請使用下拉功能表選擇 **每天**。</li></ul></li>
<li>在視窗的 **將狀態設定為“有風險”** 部分中，指定應將 SLA 標記為有風險的時間。
<ul><li>預設情況下，只有在違反 SLA 的情況下才會傳送通知。要更改此設定，請勾選 **傳送“有風險”通知**。</li></ul></li></ul>

以下範例顯示了為端口配置的 SLA，該端口預計在週一至週五每天接收 1000 個檔案。如果尚未收到 1000 個檔案，則會在時間段結束前 1 小時傳送風險通知。

![SLA Configuration Example](https://docs.kasoftware.com/26.4/images/sla_defined.png)

> [!NOTE]
>
> 如果有必要，可以關閉 SLA 通知。這在維護視窗期間非常有用。點選導覽列上的 **設定**，然後跳轉到 **通知 > 通用通知**。點選平板和鉛筆圖示進行編輯，並取消勾選 **SLA 通知** 設定。

## 使用設計器

視覺化設計器僅適用於結構簡單的 XML、CSV、TSV 和 PSV 檔案。下面是一個簡單的 XML 文件作為來源檔案的例子：

```xml theme={null}
<actor table="actor">
  <actor_id key="true">124455</actor_id>
  <first_name>Bob</first_name>
  <last_name>Smith</last_name>
</actor>
```

此範例來源檔案可以與以下 CSV 文件配對作為目的檔案：

```csv theme={null}
id,first name,last name,time
124455,Bob,Smith,2017-07-18T17:38:53-04:00
```

當這些檔案被配置為來源檔案和目的檔案時，設計器將在 **源** 列中顯示來源檔案中每一行的行（actor\_id, first\_name,和 last\_name）。對於源中的每個欄位，使用下拉功能表選擇適當的 **目標** 列。應用程式將根據列名自動嘗試匹配源欄位和目標欄位。在上面的範例中，*actor\_id* 行將自動與 *id* 列匹配。

![對映設計器](https://mintcdn.com/qiao/HyyOl9gYIsxaiGgh/26.4/images/map_connector_designer.png?fit=max\&auto=format\&n=HyyOl9gYIsxaiGgh\&q=85\&s=4e4aa07f970d9e453edfc972f4a4a142)

## 使用指令碼檢視

指令碼檢視提供了使用 ArcScript 手動生成對映範本的能力。這允許對可能的輸入和輸出格式進行更精細的控制。指令碼檢視定義了目的檔案呈現後的外觀，ArcScript 元素使用源文件中的值動態填充範本。ArcScript 元素都以 *arc* 字首開頭，例如 `<arc:set>`。指令碼檢視中任何不是 ArcScript 的內容都將作為輸出檔案的一部分。

### 導航 XML 輸出

ArcScript 支援導航複雜的 XML 結構，以便從來源檔案中解析出值。[xmlDOMSearch](https://docs.kasoftware.com/26.4/self-hosted/zh-Hant/scripting/operations/op-xml-dom-search.md) 函式將 xpath 作為輸入，並在給定的路徑上載入 XML 結構。該操作針對在源文件中找到的 xpath 的每個例項進行迴圈；要載入整個文件並避免迴圈，請將 XML 源的根元素作為輸入提供給 [xmlDOMSearch](https://docs.kasoftware.com/26.4/self-hosted/zh-Hant/scripting/operations/op-xml-dom-search.md)。例如：

```xml theme={null}
<arc:call op=xmlDOMSearch?xpath=/root>
  <!-- Inside this operation call the parsed XML elements can be accessed -->
</arc:call>
```

一旦載入了 XML 文件，[xpath 格式化器](https://docs.kasoftware.com/26.4/self-hosted/zh-Hant/scripting/value-formatters/function-formatters.md#xpath-xpath)支援在指定的路徑從 XML 中讀取值。格式化器接受絕對 XPath 以及相對於 [xmlDOMSearch](https://docs.kasoftware.com/26.4/self-hosted/zh-Hant/scripting/operations/op-xml-dom-search.md) 載入的路徑的 XPath。與所有格式化器一樣，*xpath* 格式化器只能在方括號 \[] 內使用。例如：

```xml theme={null}
<arc:call op="xmlDOMSearch?xpath=/root/author">
  [xpath('name')]
</arc:call>
```

以下 XML 作為上述指令碼的範例輸入：

```xml theme={null}
<root>
  <author>
    <name>Stephen King</name>
  </author>
  <author>
    <name>Kurt Vonnegut</name>
  </author>
</root>
```

在本例中，[xmlDOMSearch](https://docs.kasoftware.com/26.4/self-hosted/zh-Hant/scripting/operations/op-xml-dom-search.md) 操作將迴圈存取 `root` 中的每個 `author` 元素。在每個 `author` 迴圈中，來自 `name` 元素的值在輸出檔案中作為內容讀取。這種情況下的輸出檔案如下所示：

```
Stephen King
Kurt Vonnegut
```

### 範本輸出資料

指令碼檢視用作輸出檔案的範本，而 ArcScript 將值填充到定義的範本中。舉個簡單的例子，如果資料應該被格式化為逗號分隔的值，那麼這些逗號可以作為指令碼檢視的一部分被包括進來，以便為 ArcScript 函式提供結構。因此，CSV 檔案可以從更復雜的 XML 結構中生成。

以下面的 XML 為例，它包含巢狀元素，不適合使用設計器方式：

```xml theme={null}
<actor table="actor">
  <actor_id key="true">12445</actor_id>
  <name>
    <first_name>Viggo</first_name>
    <last_name>Mortensen</last_name>
  </name>
  <actor_id key="true">12522</actor_id>
  <name>
    <first_name>Gal</first_name>
    <last_name>Gadot</last_name>
  </name>
</actor>
```

透過將適當的路徑傳遞給 ArcScript 的 [xpath 格式化器](https://docs.kasoftware.com/26.4/self-hosted/zh-Hant/scripting/value-formatters/function-formatters.md#xpath-xpath)，可以輕鬆檢索巢狀元素。這些格式化器可以放在逗號內和標題名稱之後，以提供所需的 CSV 結構，並且一個附加的 [csvescape 格式化器](https://docs.kasoftware.com/26.4/self-hosted/zh-Hant/scripting/value-formatters/encoding-decoding-string-formatters.md#csvescape)確保這些值被正確引用：

```xml theme={null}
id,first name,last name
<arc:call op="xmlDOMSearch?xpath=actor">
[xpath('actor_id') | csvescape],[xpath('name/first_name') | csvescape],[xpath('name/last_name') | csvescape]
</arc:call>
```

透過常數範本資料和 ArcScript 的結合使用，可以生成各種文字檔案。

### 附加指令碼功能

由於完整的 ArcScript 在指令碼檢視中可用，因此可能需要利用 ArcScript [運算器](https://docs.kasoftware.com/26.4/self-hosted/zh-Hant/scripting/operations/operations.md)。例如，如果來源檔案只包含資料庫中某個項的標識，但需要該項的實際名稱，則 [dbQuery](https://docs.kasoftware.com/26.4/self-hosted/zh-Hant/scripting/operations/op-db-query.md) 操作可以用來查詢對應的 Id 的名稱。

ArcScript 還支援對映範本中的條件邏輯。`arc:if` 關鍵字是可用於幫助在範本中執行條件邏輯的關鍵字之一。例如，如果來源檔案包含有關 QuickBooks 中客戶的資訊，則可能需要對未清餘額的客戶執行不同的業務邏輯，對已全額付款的客戶執行不同的業務邏輯。這個用例的一個簡單範例可能如下所示：

```xml theme={null}
<arc:set item="Customer" attr="paidinfull" value="true" />
<arc:call op="xmlDOMSearch?xpath=Customer">
  <arc:if exp="[xpath('balance')] > 0">
    <arc:set item="Customer" attr="paidinfull" value="false" />
  </arc:if>
</arc:call>
id,first name,last name, paid in full
[xpath('customer_id') | csvescape],[xpath('first_name') | csvescape],[xpath('last_name') | csvescape],[Customer.paidinfull]
```

## 宏

在檔案命名策略中使用宏可以提高組織效率和對資料的上下文理解。透過將宏合併到檔名中，可以動態地包含相關資訊，例如識別碼、時間戳和訊息頭資訊，從而為每個檔案提供有價值的上下文。這有助於確保檔名反映對組織重要的詳細資訊。

知行之桥 支援這些宏，它們都使用以下語法：`%Macro%`。

<table><thead><tr><th>宏</th><th>描述</th></tr></thead>
<tbody><tr><td>ConnectorID</td><td>替換為端口的 ConnectorID。</td></tr>
<tr><td>ConnectorName</td><td>替換為端口名稱。可用於在檔名或路徑中包含連線名稱，例如按生成備份檔案的資料庫連線標記檔案。</td></tr>
<tr><td>Ext</td><td>替換為端口當前正在處理的檔案的副檔名。</td></tr>
<tr><td>Filename</td><td>替換為端口當前正在處理的檔案的檔名（包括副檔名）。</td></tr>
<tr><td>FilenameNoExt</td><td>替換為端口當前正在處理的檔案的檔名（不帶副檔名）。</td></tr>
<tr><td>MessageId</td><td>計算端口輸出的訊息的 MessageId。</td></tr>
<tr><td>RegexFilename:*pattern*</td><td>將規則運算式模式應用於端口當前正在處理的檔案的檔名。</td></tr>
<tr><td>Header:*headername*</td><td>替換為端口正在處理的當前訊息的目標訊息頭（`headername`）的值。</td></tr>
<tr><td>LongDate</td><td>以常規格式計算系統的當前日期時間（例如，2024 年 1 月 24 日星期三）。</td></tr>
<tr><td>ShortDate</td><td>以 yyyy-MM-dd 格式計算系統的當前日期時間（例如 2024-01-24）。</td></tr>
<tr><td>DateFormat:*format*</td><td>以指定格式（`format`）計算系統的當前日期時間。有關可用的日期時間格式，請參閱 [範例日期格式](https://docs.kasoftware.com/26.4/self-hosted/zh/scripting/value-formatters/date-formatters.md#date-formats-with-literal-characters)。</td></tr>
<tr><td>Vault:*vaultitem*</td><td>計算指定保管庫專案的值。</td></tr></tbody></table>

### 範例

某些宏（例如 %Ext% 和 %ShortDate%）不需要參數，但其他宏則需要。所有帶有參數的宏都使用以下語法：`%Macro:argument%`

以下是帶有參數的宏的一些範例：

<ul><li>%Header:headername%：其中 `headername` 是訊息上訊息頭的名稱。</li>
<li>%Header:mycustomheader% 解析為輸入訊息上設定的 `mycustomheader` 訊息頭的值。</li>
<li>%Header:ponum% 解析為輸入訊息上設定的 `ponum` 訊息頭的值。</li>
<li>%RegexFilename:pattern%：其中 `pattern` 是規則運算式模式。例如，`%RegexFilename:^([\w][A-Za-z]+)%` 匹配並解析為檔名中的第一個單詞，並且不區分大小寫（`test_file.xml` 解析為 `test`）。</li>
<li>%Vault:vaultitem%：其中 `vaultitem` 是 [vault](https://docs.kasoftware.com/26.4/self-hosted/zh/getting-started/administration/settings/global-settings-vault.md) 中專案的名稱。例如，`%Vault:companyname%` 解析為儲存在保管庫中的 `companyname` 項的值。</li>
<li>%DateFormat:format%：其中 `format` 是可接受的日期格式（有關詳細資訊，請參閱 [範例日期格式](https://docs.kasoftware.com/26.4/self-hosted/zh/scripting/value-formatters/date-formatters.md#sample-date-formats)）。例如，`%DateFormat:yyyy-MM-dd-HH-mm-ss-fff%` 解析為檔案上的日期和時間戳。</li></ul>

還可以建立更復雜的宏，如以下範例所示：

<ul><li>將多個宏組合在一個檔名中：`%DateFormat:yyyy-MM-dd-HH-mm-ss-fff%%EXT%`</li>
<li>包括宏之外的文字：`MyFile_%DateFormat:yyyy-MM-dd-HH-mm-ss-fff%`</li>
<li>在宏中包含文字：`%DateFormat:'DateProcessed-'yyyy-MM-dd_'TimeProcessed-'HH-mm-ss%`</li></ul>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.