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

# Flat File 端口

> Flat File 端口可實現平面檔案和 XML 檔案的互相轉換，支援位置分隔和字元分隔格式。

export const SlasTab = ({siteName = "知行之桥"}) => <>
    <p><em>與配置服務級別協議 (SLA) 相關的設定。</em></p>
    <p>
      SLA 允許配置預期流程中端口傳送或接收的資料量，並設定預期達到該資料量的時間範圍。當 SLA 未達到時，{siteName} 會傳送電子郵件警告使用者，並將 SLA 標記為 <em>存在風險</em>，這意味著如果 SLA 未能儘快達到，則會被標記為 <em>已違反</em>。這讓使用者有機會介入並確定 SLA 未達到的原因，並採取適當的措施。如果在風險時間段結束時仍未達到 SLA，則會將 SLA 標記為已違反，並再次通知使用者。
    </p>
    <p>
      要定義 SLA，請啟用 <strong>預期資料量</strong>，然後點選 <strong>設定</strong> 索引標籤。
    </p>
    <img src="/public/images/sla_empty.png" alt="SLA Empty" />
    <ul>
      <li>如果端口具有單獨的傳送和接收操作，請使用選項按鈕指定 SLA 適用的方向。</li>
      <li>在視窗的 <strong>預計至少</strong> 部分中：
        <ul>
          <li>設定預計處理的最小交易數量（交易量）</li>
          <li>使用 <strong>每個</strong> 欄位指定時間範圍</li>
          <li>指示 SLA 生效的時間。如果選擇 <strong>開始於</strong>，請填寫日期和時間欄位。</li>
          <li>勾選希望 SLA 生效的星期幾對應的核取方塊。如有必要，請使用下拉功能表選擇 <strong>每天</strong>。</li>
        </ul>
      </li>
      <li>在視窗的 <strong>將狀態設定為“有風險”</strong> 部分中，指定應將 SLA 標記為有風險的時間。
        <ul>
          <li>預設情況下，只有在違反 SLA 的情況下才會傳送通知。要更改此設定，請勾選 <strong>傳送“有風險”通知</strong>。</li>
        </ul>
      </li>
    </ul>
    <p>
      以下範例顯示了為端口配置的 SLA，該端口預計在週一至週五每天接收 1000 個檔案。如果尚未收到 1000 個檔案，則會在時間段結束前 1 小時傳送風險通知。
    </p>
    <img src="/public/images/sla_defined.png" alt="SLA Configuration Example" />
    <Note>
      如果有必要，可以關閉 SLA 通知。這在維護視窗期間非常有用。點選導覽列上的 <strong>設定</strong>，然後跳轉到 <strong>通知 &gt; 通用通知</strong>。點選平板和鉛筆圖示進行編輯，並取消勾選 <strong>SLA 通知</strong> 設定。
    </Note>
  </>;

export const AlertsTab = ({siteNameShort = "知行之桥"}) => <>
    <p><em>與配置通知相關的設定。</em></p>
    <p>
      在執行服務級別協議 (SLA) 之前，需要設定電子郵件通知以接收通知。預設情況下，{siteNameShort} 使用 <a href="/26.3/self-hosted/zh/getting-started/administration/settings/alerts">通知</a> 索引標籤上的全域設定。要為此端口使用其他設定，請啟用 <strong>覆蓋全域設定</strong>。
    </p>
    <p>
      預設情況下，錯誤通知處於啟用狀態，這意味著每當出現錯誤時都會傳送電子郵件。要關閉錯誤通知，請取消選中 <strong>啟用</strong> 核取方塊。
    </p>
    <p>
      輸入 <strong>主題</strong>（必填）。勾選<strong>允許在主題中使用 ArcScript</strong>，即可在<strong>主題</strong>欄位中使用 ArcScript。選中後會顯示 <strong>ArcScript 編輯器</strong>按鈕（<img src="/public/images/rest_arcscript_editor.png" alt="ArcScript 編輯器按鈕" style={{
  display: 'inline',
  verticalAlign: 'middle',
  margin: 0
}} />）。
    </p>
    <p>
      （可選）輸入以逗號分隔的<strong>收件人</strong>電子郵件地址清單。
    </p>
  </>;

export const Message = () => <>
    <p><em>訊息設定確定端口如何搜尋訊息並在處理後管理它們。</em></p>
    <p><strong>注意：</strong>以下設定已棄用，預設處於隱藏狀態。只有先前已啟用這些設定或將其配置為非預設值的端口才會顯示它們。若要保留成功處理的檔案副本，請在工作流程中右鍵單擊該端口，選擇<strong>顯示成功路徑</strong>，然後將成功路徑連線到 <a href="/26.3/self-hosted/zh/connectors/file">File 端口</a>。</p>
    <table>
      <thead>
        <tr><th>設定</th><th>描述</th></tr>
      </thead>
      <tbody>
        <tr>
          <td><strong>儲存到已傳送資料夾</strong>（已棄用）</td>
          <td>將端口處理的檔案複製到 Sent 資料夾。預設停用。儲存到 Sent 資料夾中的檔案不受<a href="/26.3/self-hosted/zh/getting-started/administration/settings/encryption-at-rest">靜態加密</a>保護。</td>
        </tr>
        <tr>
          <td><strong>已傳送資料夾方案</strong>（已棄用）</td>
          <td>按所選時間間隔對 <strong>Sent</strong> 資料夾中的檔案進行分組。僅在啟用<strong>儲存到已傳送資料夾</strong>時適用。</td>
        </tr>
      </tbody>
    </table>
  </>;

export const MiscConnector = () => <>
    <p><em>特殊設定適用於特定用例。</em></p>
    <table>
      <thead>
        <tr>
          <th>設定</th>
          <th>描述</th>
        </tr>
      </thead>
      <tbody>
        <tr>
          <td><strong>其他設定</strong></td>
          <td>允許在以分號分隔的清單中配置隱藏的端口設定，例如 <code>setting1=value1;setting2=value2</code>。正常的端口用例和功能不需要使用這些設定。</td>
        </tr>
      </tbody>
    </table>
  </>;

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

export const MacrosExamples = ({extraMacros = []}) => <>
    <p>
      某些宏（例如 %Ext% 和 %ShortDate%）不需要參數，但其他宏則需要。所有帶有參數的宏都使用以下語法：<code>%Macro:argument%</code>
    </p>

    <p>以下是帶有參數的宏的一些範例：</p>

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

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

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

export const MacrosTable = ({siteName = "知行之桥", extraMacros = []}) => <>
    <p>
      在檔案命名策略中使用宏可以提高組織效率和對資料的上下文理解。透過將宏合併到檔名中，可以動態地包含相關資訊，例如識別碼、時間戳和訊息頭資訊，從而為每個檔案提供有價值的上下文。這有助於確保檔名反映對組織重要的詳細資訊。
    </p>

    <p>{siteName} 支援這些宏，它們都使用以下語法：<code>%Macro%</code>。</p>

    <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:<em>pattern</em></td><td>將規則運算式模式應用於端口當前正在處理的檔案的檔名。</td></tr>
        <tr><td>Header:<em>headername</em></td><td>替換為端口正在處理的當前訊息的目標訊息頭（<code>headername</code>）的值。</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:<em>format</em></td><td>以指定格式（<code>format</code>）計算系統的當前日期時間。有關可用的日期時間格式，請參閱 <a href="/26.3/self-hosted/zh/scripting/value-formatters/date-formatters#date-formats-with-literal-characters">範例日期格式</a>。</td></tr>
        <tr><td>Vault:<em>vaultitem</em></td><td>計算指定保管庫專案的值。</td></tr>
        {extraMacros.map(item => <tr key={item.name}>
            <td>{item.name}</td>
            <td>{item.description}</td>
          </tr>)}
      </tbody>
    </table>
  </>;

export const Performance = () => <>
    <p><em>與端口資源分配相關的設定。</em></p>
    <table>
      <thead>
        <tr>
          <th>設定</th>
          <th>描述</th>
        </tr>
      </thead>
      <tbody>
        <tr>
          <td><strong>最大工作執行緒數</strong></td>
          <td>此端口上處理檔案時從執行緒池中消耗的最大工作執行緒數。如果設定，則會覆蓋 <a href="/26.3/self-hosted/zh/getting-started/administration/settings/advanced-settings">進階設定</a> 頁面的 <a href="/26.3/self-hosted/zh/getting-started/administration/settings/performance-settings">效能設定</a> 部分的預設設定。</td>
        </tr>
        <tr>
          <td><strong>最大檔案數</strong></td>
          <td>分配給端口的每個執行緒傳送的最大檔案數。如果設定，則會覆蓋 <a href="/26.3/self-hosted/zh/getting-started/administration/settings/advanced-settings">進階設定</a> 頁面的 <a href="/26.3/self-hosted/zh/getting-started/administration/settings/performance-settings">效能設定</a> 部分的預設設定。</td>
        </tr>
      </tbody>
    </table>
  </>;

export const siteNameShort = "知行之橋";

export const siteName = "知行之橋";

Flat File 端口可以實現平面檔案和 XML 檔案的互相轉換。

## 核心功能

* 為定長（位置分隔）和字元分隔格式提供雙向平面檔案/XML 解析
* 支援多種行型別，具備控制欄位識別功能
* 自動層級檢測，併為"主-詳"（Master-Detail）關係提供 XML 巢狀支援
* 提供完善的欄位對映，具備自定義資料型別處理功能

## 概觀

每個 Flat File 端口配置一個特定的平面檔案格式，從而實現與 XML 格式的互相轉換。Flat File 端口有兩個主要的模式：

* Position Delimited，端口配置有任意的欄位名稱、索引（即位置）和長度，表明資料在平面檔案中每一行出現的位置。

* Character Delimited，端口配置有分隔平面檔案中欄位值的字元。

更多詳情請查閱[定義平面檔案格式](#定義平面檔案格式)部分。

<Note>如果還需要一個數字控制欄位，請按照[非標準 XML 控制欄位](#非標準-xml-控制欄位)中的說明進行設定。</Note>

Flat File 端口支援定義多種平面檔案中不同型別的行。例如，平面檔案中可能有一個 "header" 行，代表訂單的日期，有多個 "item" 行，代表訂單中的行專案。

定義多種行型別的關鍵是指定**控制欄位**；控制欄位值決定了在平面檔案中特定的行型別（例如，header 行可能有一個控制欄位值為 "HEAD"，item 行可能有一個控制欄位值為 "ITEM"）。更多配置多種行型別的詳情請查閱[多種行型別](#多種行型別)部分。

平面檔案格式配置完後，端口會轉換與此格式匹配的檔案到 XML。最終的 XML 結構在 [XML 格式](#xml-格式)部分有詳細解釋。Flat File 端口也可以將匹配這種結構的 XML 轉換為定義的平面檔案格式。

某些平面檔案在不同行有隱含的上下級關係。關於更多在轉換平面檔案為 XML 時而保留上下級關係的詳情，請查閱[多行層級關係](#多行層級關係)部分。

## 端口配置

### 檔案詳情索引標籤

| 設定        | 描述                                                                                                   |
| --------- | ---------------------------------------------------------------------------------------------------- |
| **端口 ID** | 端口的靜態唯一識別碼。                                                                                          |
| **端口型別**  | 顯示端口名稱及其功能描述。                                                                                        |
| **端口描述**  | 一個可選欄位，用於對端口及其在工作流程中的角色進行自由說明。                                                                       |
| **檔案型別**  | **Position Delimited** — 平面檔案中的欄位顯示在每一行的特定位置。**Character Delimited** — 平面檔案中的欄位由**分隔符號**欄位定義的特定字元分隔。 |
| **分隔符號**  | 如果**檔案型別**設定為 **Character Delimited**，則指定平面檔案中分隔各個欄位的字元。                                             |

#### 控制欄位：位置分隔

*和控制欄位有關的設定，決定了在平面檔案格式中定義的不同的行型別。*

| 設定         | 描述                                                                                                |
| ---------- | ------------------------------------------------------------------------------------------------- |
| **多行模式**   | 平面檔案是否包括多種行型別。更多資訊請查閱[多種行型別](#多種行型別)部分。                                                           |
| **起始索引**   | 如果**多行模式**啟用，該值就是行中**控制欄位**開始的索引。例如，如果某一行中的第一個欄位是控制欄位，那麼起始索引就是 0。                                 |
| **控制欄位長度** | （可選）如果**多行模式**啟用，這個值定義了從**起始索引**開始讀取**控制欄位**的長度。                                                  |
| **當前列標題**  | 如果不啟用**多行模式**，這個設定決定了平面檔案中的第一行是否應該被解析為列標題（即每個欄位的名稱而不是實際的資料）。啟用此設定，就會使端口在將檔案從 XML 轉換為平面檔案時生成一個標題行。 |

#### 控制欄位：字元分隔

*和控制欄位有關的設定，決定了在平面檔案格式中定義的不同的行型別。*

| 設定              | 描述                                                                                                |
| --------------- | ------------------------------------------------------------------------------------------------- |
| **多行模式**        | 平面檔案是否包括多種行型別。更多資訊請查閱[多種行型別](#多種行型別)部分。                                                           |
| **欄位索引**        | 如果**多行模式**啟用，該值就是行中（索引從 0 開始）**控制欄位**的索引。例如，如果某一行中的第二個欄位定義了行的型別（即第二個欄位是控制欄位），那麼欄位索引就是 1。          |
| **生成欄位／行型別名稱**  | 如果**多行模式**啟用，那麼該設定提供了一個選項，在平面檔案中 *不* 指定欄位和行的名稱和索引。當啟用這個設定，端口將會自動為下面**行型別**中沒有明確定義的欄位和行生成 XML 元素。  |
| **當前列標題**       | 如果不啟用**多行模式**，這個設定決定了平面檔案中的第一行是否應該被解析為列標題（即每個欄位的名稱而不是實際的資料）。啟用此設定，就會使端口在將檔案從 XML 轉換為平面檔案時生成一個標題行。 |
| **使用自動生成的欄位名稱** | 如果**多行模式**沒有啟用，這個設定決定了端口是否生成通用欄位名稱。不啟用該選項，在**行型別**部分手動指定欄位名稱。                                     |

#### 行型別

該部分允許以平面檔案格式定義欄位名和位置。更多定義平面格式的詳情請查閱[定義平面檔案格式](#定義平面檔案格式)部分。

如果**檔案型別**是 *Position Delimited* 且**多行模式**啟用，使用**新增行型別**按鈕定義。每個行型別有一個**控制欄位值**，來標識行型別。例如，header 行可能有值為 *HEAD* 的控制欄位值，item 行可能有值為 *ITEM* 的控制欄位值。

如果**檔案型別**設定為 *Character Delimited*，**多行模式**啟用，**生成欄位／行型別名稱**啟用，那麼為平面檔案中存在的所有欄位和行型別提供名稱和索引就不是必需的。在這種情況下，端口將會為任何未定義的欄位或行型別自動生成 XML 元素。取消**生成欄位／行型別名稱**以手動指定欄位名稱。

### 設定索引標籤

#### 配置

*與端口核心配置相關的設定。*

| 設定             | 描述                                                                                                                     |
| -------------- | ---------------------------------------------------------------------------------------------------------------------- |
| **端口 ID**      | 端口的靜態唯一識別碼。                                                                                                            |
| **端口型別**       | 顯示端口名稱及其功能描述。                                                                                                          |
| **端口描述**       | 一個可選欄位，用於對端口及其在工作流程中的角色進行自由說明。                                                                                         |
| **填充字元**       | 當建立平面檔案但欄位值不能填滿整個欄位長度時，這個欄位會被用來填滿剩餘部分。                                                                                 |
| **無效的XML名稱字首** | 某些欄位名對於 XML 元素時無效的（例如，以數字開頭的欄位像 "123ABC"），所以在從平面檔案生成 XML 時必須設定一個字首。同樣的，當從 XML 轉換平面檔案時，端口會查詢該字首並去除它。                    |
| **行分隔符號**      | 指定端口在寫入檔案時用於行結束的控制字元。選項為 **LF**（預設）和 **CRLF**。                                                                         |
| **巢狀行型別**      | 該設定僅在從平面檔案轉換到 XML 檔案時，且在平面檔案中有多種行型別時才相關。如果**多行模式**啟用，端口將會根據平面檔案的控制欄位行增加層級關係到最終的 XML。更多關於該自動層級關係請查閱[多行層級關係](#多行層級關係)部分。 |
| **行尾填充**       | 預設設定下，端口會在遇到例外的行尾時擲回錯誤。當啟用時，該設定告知端口填充行而不是擲回錯誤。                                                                         |
| **始終使用單元格分割符** | 如果**檔案型別**設定為 *Character Delimited*，開啟此設定以使端口始終使用單元格分隔符號（`"`）包裝所有值，關閉此設定後端口僅會包裝含有分隔符號的值。                               |
| **本地檔案命名規則**   | 用於為端口輸出訊息分配檔名的規則。可以在檔名中使用宏動態包含識別碼和時間戳等資訊。更多資訊，請參見[宏](#宏)。                                                              |

### 高階頁面

#### 訊息

<Message />

#### 日誌

<Logging />

#### 其他設定

| 設定       | 描述                                                                                                                                      |
| -------- | --------------------------------------------------------------------------------------------------------------------------------------- |
| **處理延遲** | **交易**索引標籤中檔案處理延遲的時間（秒）。這是一箇舊版設定。最佳做法是[使用 File 端口](../flows/designing-a-flow#interacting-with-the-local-file-system)來管理本地檔案系統，而不是使用此設定。 |

#### 其他設定

<MiscConnector />

### 自動化頁面

| 設定     | 描述               |
| ------ | ---------------- |
| **傳送** | 到達端口的檔案是否自動進行處理。 |

#### 效能

<Performance />

### 告警索引標籤

<AlertsTab />

### SLA 索引標籤

<SlasTab />

## 定義平面檔案格式

配置 Flat File 端口的第一步就是定義平面檔案的格式。本部分介紹具有單行型別的格式，換句話說，平面檔案中的每一行都具有相同的欄位集。對於有多個不同行型別的平面檔案，請查閱[多種行型別](#多種行型別)部分。

### Character Delimited 的單行格式

對於 *Character Delimited* 的平面檔案，定義格式很簡單：透過**分隔符號**屬性指定平面檔案中分隔不同欄位的字元。

**當前列標題**欄位說明了平面檔案中的第一行是否是標題行；換句話說，它包含了欄位名稱而不是實際資料。如果這些列標題存在，端口將會使用這些標題名稱作為最終轉換成的 XML 中的 XML 元素名。同樣的，端口也會使用 XML 元素名稱在從 XML 轉換為平面檔案時生成一個標題行。

如果列標題不存在，端口支援透過在**行型別**中新增欄位，手動指定每一個欄位的名稱。這些欄位名稱按照索引順序應用，意味著**行型別**中的第一個項目將會是平面檔案行中第一個欄位的名稱，以此類推。

端口也可以透過啟用**使用自動生成的欄位名稱**來自動生成通用的欄位名稱。

### Position Delimited 的單行格式

對於 *Position Delimited* 的平面檔案，定義格式需要指定在格式中每個欄位的位置。端口設定中**行型別**部分為平面檔案中存在的行增加任意數量的欄位。每個欄位必須使用名稱和其在平面檔案中出現的位置進行標識。

**當前列標題**欄位表明了平面檔案中的第一行是否為標題行；換句話說，它包括了欄位名稱而不是實際資料。欄位名稱仍然需要在**行型別**部分中配置，且這個設定簡單地保證了標題行不被識別為實際資料。

### 非標準 XML 控制欄位

平面檔案資料可能包含完全數字或以數字開頭的控制欄位的行。雖然這在平面檔案資料中很正常，但在將該平面檔案資料轉換為 XML 時卻帶來了挑戰，因為 XML 元素不能以數字開頭。它們必須以字母或下劃線開頭。為了在平面檔案端口中適應這種情況，如果控制欄位以數字開頭，{siteNameShort} 會自動在輸出 XML 中的該值前面新增兩個下劃線 (\_\_)。此外，還會向該元素新增一個 `lineType` 屬性，其值對應於原始控制欄位值。例如，以下平面檔案資料包括兩種線型，控制欄位分別為 `000` 和 `111`：

```
000 12345     01222025 NC Yes
000 02468     01242025 MD Yes
111 82390     01202025 FL No
111 67524     01132025 CO No
```

此資料的平面檔案配置如下所示：

<img src="https://mintcdn.com/qiao/bVtjD3fvHFZBo1vE/public/images/flat_file_control_fields.png?fit=max&auto=format&n=bVtjD3fvHFZBo1vE&q=85&s=11943629560f57dd7426bf8ce3ffe286" width="600" data-path="public/images/flat_file_control_fields.png" />

當使用此配置透過端口執行此平面檔案資料時，輸出如下所示：

```xml theme={null}
<Items>
	<__000 lineType="000">
		<ID>12345</ID>
		<Date>01222025</Date>
		<State>NC</State>
		<Paid>Yes</Paid>
	</__000>
	<__000 lineType="000">
		<ID>02468</ID>
		<Date>01242025</Date>
		<State>MD</State>
		<Paid>Yes</Paid>
	</__000>
	<__111 lineType="111">
		<ID>82390</ID>
		<Date>01202025</Date>
		<State>FL</State>
		<Paid>No</Paid>
	</__111>
	<__111 lineType="111">
		<ID>67524</ID>
		<Date>01132025</Date>
		<State>CO</State>
		<Paid>No</Paid>
	</__111>
</Items>
```

請注意，每種線型都帶有兩個下劃線字首，並且 XML 元素具有與原始控制欄位值相對應的 `lineType` 屬性。這允許平面檔案資料和 XML 完全雙向，這意味著當輸出 XML 作為輸入傳遞到平面檔案端口時，輸出是包含正確線型定義且不帶任何下劃線的平面檔案資料。

這也意味著，如果要從 XML 轉到平面檔案，並且需要以數字開頭（或全部為數字）的線型控制欄位，則需要在文件到達平面檔案端口之前，在文件對映中的相應 XML 元素上實現 `lineType` XML 屬性。

## 多種行型別

如果平面檔案格式包括了多種行型別，**多行模式**屬性應該被啟用。平面檔案中標識行型別的欄位被稱為**控制欄位**。

### Character Delimited 的多種行型別

當**檔案型別**為 *Character Delimited*，**欄位索引**設定決定了**控制欄位**出現在平面檔案中每一行的位置。該索引從 0 開始，意味著如果**控制欄位**是行中的第 5 個值，那麼**欄位索引**就應該是 4。

對於可能出現在**控制欄位**的每個值，在端口設定**行型別**單擊**新增行型別**按鈕。標識行型別的值應該在該行的**控制欄位值**中設定。

一旦每個可能的行型別透過特定的**控制欄位值**被新增和標識，在每行中將出現的欄位應根據索引順序指定。

如果**生成欄位／行型別名稱**啟用，為在平面檔案中存在的所有欄位或行型別（只有**控制欄位**必需）提供名稱和索引是不必要的。在這種情況下，端口將會為任何未定義的欄位或行型別自動生成 XML 元素。

### Position Delimited 的多種行型別

當**檔案型別**是 *Position Delimited*，**起始索引**設定決定了**控制欄位**在平面檔案中每一行出現（開始）的位置。這個索引從 0 開始，意味著如果**控制欄位**從行中第 15 個字元開始，那麼**起始索引**就應該是 14。

對於可能出現在**控制欄位**的每個值，在端口設定**行型別**單擊**新增行型別**按鈕。標識行型別的值應該在該行的**控制欄位值**中設定。

一旦每個可能的行型別透過特定的**控制欄位值**被新增和標識，在每行中將出現的欄位應根據所處（開始）的位置指定。

### 多行範例

例如，某個平面檔案包括兩種型別的行，一個 shipment 行和一個 package 行。shipment 行包括髮貨的日期、時間和地址資訊，package 行型別包括了發貨的專案資訊。每一行的第一個欄位是 "SHIP" 或 "PCKG" 來表明該行是什麼型別。

針對這種情況，**多行**模式應該被啟用，且**欄位索引**（或**起始索引**）應設定為 0，表明**控制欄位**是該行中的第一個欄位。然後，在**行型別**部分應該配置有兩種行型別；一種**控制欄位值**為 "SHIP"，包括 shipment 行的每個欄位（例如發貨日期，交付日期，收貨地址等），一種**控制欄位值**為 "PCKG"，包括 package 行的每個欄位（例如專案名稱，專案重量等）。

## XML 格式

在平面檔案轉換為 XML 檔案之後，結果應有如下的 XML 結構：

* 位於檔案根部的 *Items* 元素
* 平面檔案中的每一行有一個與該行**控制欄位值**相同的元素（如果未定義**控制欄位值**，則是"行"）
* 行中的每個欄位是**控制欄位值**元素的子元素

例如，如果平面檔案有 "SHIP" 和 "PCKG" 行，那麼輸出的 XML 會和此格式相似：

```xml theme={null}
<Items>
  <SHIP>
    <ShipmentId>12B992</ShipmentId>
    <Date>20200228</Date>
    <ShipTo>14 Wallaby Way</ShipTo>
  </SHIP>
  <PCKG>
    <ShipmentId>12B992</ShipmentId>
    <ItemName>Goggles</ItemName>
    <ItemWeight>3.98</ItemWeight>
  </PCKG>
  <PCKG>
    <ShipmentId>12B992</ShipmentId>
    <ItemName>Fins</ItemName>
    <ItemWeight>1.07</ItemWeight>
  </PCKG>
</Items>
```

轉換 XML 檔案為平面檔案，輸入的 XML 必須與上面的結構匹配（包括欄位名稱必須與端口配置中定義的欄位匹配的限制）。

當轉換 XML 為平面檔案時，端口將在最終的平面檔案中為每個 *row* 元素建立一個新行。對於 *row* 元素的每個子元素，端口將會將其與端口配置中**欄位名稱**匹配，並將該元素放到合適的**欄位索引**。

## 多行層級關係

有多種行型別的平面檔案通常在行型別中有隱含的層級結構。例如，一行包括訂單的資訊（例如客戶名稱，訂單日期等），下面幾行代表訂單中的每個訂單行（例如專案名稱，專案數量等）。行專案"屬於"訂單，構成層級關係。

這些關係有時稱為"主-明細"關係；意味著第一個行型別（訂單）是主，下面幾行（行專案）是關於主行的"明細"資訊。在 XML 中，這通常表現為"父子"關係。

Flat File 端口在轉換平面檔案為 XML 時可以保留這些層級關係。如果在[高階頁面](#高階頁面)啟用了**巢狀行型別**設定，端口將自動縮排"明細"行，使它們成為"主"行型別的子元素。

以下是將**巢狀行型別**設為 true，轉換一個有層級關係的平面檔案的範例。在範例之後的部分將解釋端口決定層級關係使用的邏輯。

### 多行層級關係範例

以輸入以下平面檔案為例：

```
M,CustomerA,05022020,true
D,itemA,4,2.09
D,itemB,9,15.23
M,CustomerB,05032020,false
D,itemC,1,5.99
D,itemE,1,3.99
```

平面檔案中有兩個行型別，`M` 和 `D`：

* `M`，或者說是主，包括一個訂單的資訊：客戶名稱，訂單日期，以及一個"重要客戶"的標識
* `D`，或者說明細，包括了之前訂單的訂單行資訊：專案名稱，專案數量，專案價格

因為 `D` 行型別"屬於" `M` 行型別，兩者為層級關係，那麼在轉換平面檔案為 XML 時，需要將層級關係保留下來。要檢視其格式，請在轉換上文平面檔案為 XML 時，啟用**巢狀行型別**，採取以下範例輸出：

```xml theme={null}
<Items>
  <M>
    <CustomerName>CustomerA</CustomerName>
    <OrderDate>05022020</OrderDate>
    <HighValueCustomer>true</HighValueCustomer>
    <D>
      <ItemName>itemA</ItemName>
      <ItemQuantity>4</ItemQuantity>
      <ItemPrice>2.09</ItemPrice>
    </D>
    <D>
      <ItemName>itemB</ItemName>
      <ItemQuantity>9</ItemQuantity>
      <ItemPrice>15.23</ItemPrice>
    </D>
  </M>
  <M>
    <CustomerName>CustomerB</CustomerName>
    <OrderDate>05032020</OrderDate>
    <HighValueCustomer>false</HighValueCustomer>
    <D>
      <ItemName>itemC</ItemName>
      <ItemQuantity>1</ItemQuantity>
      <ItemPrice>5.99</ItemPrice>
    </D>
    <D>
      <ItemName>itemE</ItemName>
      <ItemQuantity>1</ItemQuantity>
      <ItemPrice>3.99</ItemPrice>
    </D>
  </M>
</Items>
```

可以看到 `D` 記錄為 `M` 記錄的子元素，準確反映了源資料中存在的層級結構。

### 多行層級關係邏輯

Flat File 端口使用源平面檔案中行的順序決定行專案之間的層級關係。當**巢狀行型別**啟用，端口將遵循以下邏輯：

* 端口遇到的第一個行型別通常被當作層級結構的最上級（即不會在生成的 XML 中縮排）
* 在第一個行型別之後，當端口遇到一個新的行，它假設這個行型別是前一個行型別的下的層級（即它歸屬於前一個行且在 XML 中縮排）
* 當端口遇到一個之前遇到過的行型別，將傳回到該行型別的層級，並關閉所有等於或低於此等級的 XML 元素。

因此，源平面檔案必須根據所需的層級結構按行排列。

## 宏

<MacrosTable />

### 範例

<MacrosExamples />