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

# Database 端口設定

> 連線知行之橋與 Database，用於資料集成和同步

資料庫端口（Database connector）允許連線到多種不同的資料庫型別，並可以從這些資料庫中推送或拉取資料。

## 核心功能

* **通用資料庫連線**：支援主流資料庫平臺。
* **驅動程式支援**：同時支援 ADO.NET 和 JDBC 驅動程式。
* **全面的交易管理**：具備提交 (Commit) 和復原 (Rollback) 功能。
* **標準資料庫操作**：提供查詢 (Select)、查詢 (Lookup)、更新/插入 (Upsert) 和預存程序 (Stored Procedure) 用於資料操作。
* **高階查詢自定義**：支援查詢自定義和參數繫結。

按照以下步驟將知行之橋連線到 Database。

## 建立資料庫連線

在將 Database 端口新增到工作流程之前，必須在本地計算機上配置與資料庫的連線。

> [!NOTE]
>
> Database 端口中引用且需要許可的資料來源，應在知行之橋外部的計算機上完成許可授權。

### ADO.NET

知行之橋的 [.NET 版本](https://docs.kasoftware.com/26.3/self-hosted/zh/getting-started/installation/windows-edition.md)主要使用 ADO.NET 驅動程式。為了讓 ADO.NET 提供程式對知行之橋可見，它必須在 machine.config 檔案中定義，並在全域程式集快取 (GAC) 中註冊。熟悉相關操作的使用者可以手動完成此過程，但 知行軟體建議在託管知行之橋的計算機上安裝資料庫用戶端，因為資料庫特定的安裝嚮導會處理提供程式的定義和註冊。

### JDBC

為了讓 JDBC 驅動程式對知行之橋可見，它必須作為 Java 類路徑的一部分包含在內。知行之橋包含 H2、MySQL、PostgreSQL 和 SQL Server 的驅動程式；如需將其他驅動程式新增到類路徑，請參閱 Java Web servlet 的文件。

> [!NOTE]
>
> 除了預設選項之外，Database 端口還支援其他資料庫的 JDBC 驅動程式。但是，自定義驅動程式可能需要覆蓋端口發出的查詢，以符合資料庫預期的語法。可以使用 Input Mapping 或 Output Mapping 的 *Write custom query* 部分覆蓋查詢。

## 配置 Database 端口

配置資料庫連線後，可以將 Database 端口新增到知行之橋工作流程中。必須在 Database 端口的每個例項中輸入資料庫連線憑據。

按照以下步驟建立連線：

1. 將 Database 端口拖入知行之橋工作流程，併為其命名。

2. 在 **Settings** 索引標籤的 **Database Connection** 部分，從清單中選擇 **Driver Name**。**Driver Class** 會自動填充。

3. 選擇 **Settings Format**。

   1. 如果選擇 **Property List**，請填寫驅動程式特定的屬性。這些屬性因驅動程式而異。
   2. 如果選擇 **Connection String** 或 **DatabaseURL**，請向資料庫提供完整的連接字串。

4. 單擊 **Test Connection**，確保知行之橋可以連線到 Database。如果發生錯誤，請檢查所有欄位並重試。

5. 單擊 **Save Changes**。

### 其他資料庫連線

**Database Connection** 下拉功能表包含一個 **Other** 選項。選擇 **Other** 時，會出現 **Connection Type** 選項，要求選擇 **ADO.NET** 或 **ODBC**。

* 如果選擇 **ADO.NET**，請輸入 **Driver Class**、**Data Source**、**User** 和 **Password** 詳細資訊。
* 如果選擇 **ODBC**，請確保已按照以下說明建立系統 DSN，然後在 **Data Source Name** 中選擇它。填寫 **Driver**、**User** 和 **Password** 詳細資訊。

#### ODBC

透過 ODBC 驅動程式連線資料庫需要資料來源名稱 (DSN)。可以使用 Microsoft ODBC 管理器建立 DSN。CData 必須為 ODBC 驅動程式使用系統 DSN 連線。建立 DSN 後，在端口的 **Data Source Name** 下拉式清單中選擇它。

Database 端口支援預設選項之外的其他資料庫 ODBC 驅動程式。但是，自定義驅動程式可能需要覆蓋端口發出的查詢，以符合資料庫預期的語法。有關更多資訊，請參閱[預處理和後處理查詢](https://docs.kasoftware.com/26.3/self-hosted/zh-Hant/connectors/database/database-ac.md#pre-processing-and-post-processing-queries)。也可以在 [Select](https://docs.kasoftware.com/26.3/self-hosted/zh-Hant/connectors/database/database-select.md) 操作中使用 **Write custom queries** 選項。

## 選擇一個操作

與 Database 建立連線後，必須選擇 Database 端口將執行的操作。下表概觀了每個操作及其在知行之橋工作流程中的位置。

| 操作 | 描述 | 工作流程中位置 |
| - | - | - |
| [Upsert](https://docs.kasoftware.com/26.3/self-hosted/zh-Hant/connectors/database/database-upsert.md) | 插入或更新 Database 資料。預設情況下，如果 Database 中已存在記錄，則會使用輸入中提供的值更新 Database 中的現有資料。 | End |
| [Lookup](https://docs.kasoftware.com/26.3/self-hosted/zh-Hant/connectors/database/database-lookup.md) | 從 Database 檢索值，並將這些值插入到工作流程中已有的知行之橋訊息中。 **Lookup 查詢**決定端口將從 Database 檢索什麼值。該查詢應格式化為針對 Database 表的 SQL 查詢。 | Middle |
| [Lookup 預存程序](https://docs.kasoftware.com/26.3/self-hosted/zh-Hant/connectors/database/database-lsp.md) | 將進入端口的資料視為預存程序的輸入，然後將結果插入到工作流程中的現有知行之橋訊息中。 可以單擊 **Test Lookup** 模態框中的 **Show Sample Data** 按鈕，為所選預存程序提供範例輸入並預覽結果。 | Middle |
| [Select](https://docs.kasoftware.com/26.3/self-hosted/zh-Hant/connectors/database/database-select.md) | 從 Database 檢索資料並將其帶入知行之橋。 可以使用 **Filter** 面板向 Select 新增過濾器。這些過濾器的功能類似於 SQL 中的 *WHERE* 子句。 | Beginning |
| [執行預存程序](https://docs.kasoftware.com/26.3/self-hosted/zh-Hant/connectors/database/database-esp.md) | 將進入端口的資料視為預存程序的輸入，然後將結果沿工作流程向下傳遞。 可以單擊 **Test Execute Stored Procedure** 模態框中的 **Show Sample Data** 按鈕，為所選預存程序提供範例輸入並預覽結果。 | Middle |

## 進階選項卡

**高階**索引標籤上的許多設定都是從正在使用的資料來源動態載入的，因此本文件中未介紹這些設定。可以在我們網站的[線上幫助檔案](https://www.kasoftware.com/articles.html)頁面上找到資料來源的詳細資訊。

下面描述的選項適用於所有資料來源。

### 訊息

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

| 設定 | 描述 |
| - | - |
| **儲存至 Sent 資料夾**（已棄用） | 將端口處理的檔案複製到 Sent 資料夾。預設停用。儲存到 Sent 資料夾中的檔案不受靜態加密保護。 |
| **Sent 資料夾方案**（已棄用） | 按所選時間間隔對 Sent 資料夾中的檔案進行分組。僅在啟用**儲存至 Sent 資料夾**時適用。 |

### 進階設定

*進階設定* 是依賴任意資料庫驅動程式（例如 Database、CData 和 API 端口）以連線到各種資料來源的端口的通用設定。

| 設定 | 描述 |
| - | - |
| **自動截斷** | 啟用後，端口會自動截斷任何超過允許長度限制的字串或二進位列值。 |
| **命令逾時時間** | 命令執行逾時時長（以秒為單位）。 |
| **上次插入的 ID 查詢** | 提供一個要執行的查詢，用於檢索最後插入記錄的自增 ID。 |
| **日誌級別** | 端口生成日誌的詳細程度。請求支援時，請將其設定為 **Debug**。 |
| **本地檔案方案** | 用於為端口輸出的訊息分配檔名的方案。可以在檔名中動態使用宏，以包含識別碼、時間戳等資訊。有關更多資訊，請參閱[宏](#宏)。 |
| **保留訊息副本** | 選中後，端口會在 Logs 目錄中將訊息副本儲存在該訊息的日誌旁邊。如果停用此功能，可能無法從 **Input** 或 **Output** 索引標籤下載檔案副本。 |
| **最大失敗記錄數** | 插入期間允許失敗且仍繼續處理的最大記錄數。預設值 0 表示任何錯誤都會導致輸入訊息被標記為 Error，並復原任何未提交的交易。值 -1 表示忽略所有錯誤，端口會繼續嘗試插入後續記錄。正值表示端口會繼續嘗試插入記錄，直到達到該閾值。 |
| **輸出檔案格式** | 輸出資料的表示格式。預設值 (XML) 會讓端口為處理的每條記錄輸出一個 XML 檔案，同時可根據 **最大記錄數** 的值選擇將多條記錄組合到單個資料結構中。CSV 和 TSV 選項會以相應的檔案格式輸出資料。此選項不適用於包含子表的複雜表結構。 |
| **處理更改間隔單位** | 僅適用於 Select 操作。當在 **Settings** 索引標籤的 **Select Configuration** 部分的 **Advanced** 區域中選中 **Use column *columnname* for processing new or changed records** 時，此設定控制如何解釋 **Process Changes Interval** 設定（例如小時、天或周）。有關此設定以及以下兩個設定的詳細資訊，請參閱[只處理新的或更改的記錄](https://docs.kasoftware.com/26.3/self-hosted/zh-Hant/connectors/database/database-ac.md#only-process-new-or-changed-records)。 |
| **處理更改間隔** | 當在 **Settings** 索引標籤的 **Select Configuration** 部分中選中 **Use column *columnname* for processing new or changed records** 時，此設定控制知行之橋首次嘗試處理多少歷史資料。例如，保留預設值 180 (Days) 表示知行之橋只嘗試處理過去 180 天內建立或修改的資料。 |
| **處理更改開始日期** | 當在 **Settings** 索引標籤的 **Select Configuration** 部分中選中 **Use column *columnname* for processing new or changed records** 時，此設定控制要檢索資料的開始日期。 |
| **重置歷史記錄** | 重置選中 **Use column *columnname* for processing new or changed records** 時儲存的快取。 |
| **批次處理輸入大小** | 如果資料來源支援批次處理，則這是批次處理中查詢的最大數量。 |
| **批次處理大小** | 批次處理組中批次處理訊息的最大數量。 |
| **最大記錄數** | 單個輸出訊息中包含的最大記錄數。使用 -1 表示所有輸出記錄應放入單個檔案，使用 0 表示端口可以根據配置的 **輸出檔案格式** 決定。預設情況下，XML 每個檔案輸出一條記錄，而平面檔案格式會將所有記錄包含在一個檔案中。 |
| **交易大小** | 交易中的最大查詢數量。 |
| **處理延遲** | 放入 Input 資料夾的檔案延遲處理的時間（以秒為單位）。這是一箇舊版設定。最佳實踐是[使用 File 端口](https://docs.kasoftware.com/26.3/self-hosted/zh/flows/designing-a-flow.md#interacting-with-the-local-file-system)管理本地檔案系統，而不是使用此設定。 |
| **插入空值** | 如果未選中（預設），端口在構建 INSERT 和 UPDATE 語句時會跳過空的 XML 元素。這會使資料庫在 INSERT 語句中使用預設列值，並在 UPDATE 語句中保持列值不變。選中後，端口會在 INSERT 和 UPDATE 語句中包含空的 XML 元素，並將空字串用作該列的值。 |
| **插入 Null** | 如果未選中（預設），端口在構建 INSERT 和 UPDATE 語句時會跳過 null XML 元素（由 `xsi:nil="true"` 屬性指示）。這會使資料庫在 INSERT 語句中使用預設列值，並在 UPDATE 語句中保持列值不變。選中後，端口會在 INSERT 和 UPDATE 語句中包含 null XML 元素，並將 null 用作該列的值。被視為 null 的情況包括：`Not exist`、`<element/>`、`<element xsi:nil="true"/>`、`<element xsi:nil="true"></element>`、`<element null="true"/>` 和 `<element null="true"></element>`。 |
| **Lookup 快取** | 選中 **Enable lookup cache** 後，在直接對資料來源執行查詢之前（當快取未傳回任何記錄時），會先對本地快取執行查詢。如果未選中（預設），查詢會直接對資料來源執行。以下 Lookup 快取選項僅在選中 **Enable lookup cache** 時可用。 |
| **Lookup 快取提供程式** | 指定使用哪個驅動程式來輔助連線快取資料庫。 |
| **Lookup 快取連接字串** | 設定後，端口會使用此處指定的資料庫進行快取。 |
| **Lookup 快取容差** | 指定端口查詢資料來源以重新整理快取的頻率。與 **容差單位** 選項結合使用。 |
| **Lookup 快取容差單位** | 選擇 **Minute**、**Hour** 或 **Day**。 |
| **日誌子資料夾方案** | 指示端口根據所選時間間隔對 `Logs` 資料夾中的檔案進行分組。例如，**Weekly** 選項指示端口每週建立一個新的子資料夾，並將該周的所有日誌儲存在該資料夾中。空白設定會讓端口將所有日誌直接儲存到 `Logs` 資料夾。對於處理大量交易的端口，使用子資料夾有助於保持日誌有序並提高效能。 |

### 其它

*其它設定* 適用於特定用例。

| 設定 | 描述 |
| - | - |
| **其他設定** | 允許以分號分隔的清單配置隱藏的端口設定（例如 `setting1=value1;setting2=value2`）。正常的端口用例和功能不應需要使用這些設定。 |

## 自動化索引標籤

### 自動化設定

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

| 設定 | 描述 |
| - | - |
| **傳送** | 到達端口的檔案是否會自動傳送。 |
| **重試間隔** | 失敗傳送在重試前等待的分鐘數。 |
| **最大次數** | 端口處理檔案的最大次數。成功與否根據伺服器成功確認來衡量。如果將此設定為 0，端口會無限期重試該檔案。 |
| **接收** | 端口是否應自動查詢資料來源。 |
| **間隔** | 自動查詢嘗試之間的時間間隔。 |
| **整點後的分鐘數** | 小時計劃的分鐘偏移量。僅當上面的間隔設定為 *Hourly* 時適用。例如，如果此值設定為 5，自動化服務會在 1:05、2:05、3:05 等時間下載。 |
| **時間** | 嘗試發生的當天時間。僅當上面的間隔設定為 *Daily*、*Weekly* 或 *Monthly* 時適用。 |
| **天** | 嘗試發生的日期。僅當上面的間隔設定為 *Weekly* 或 *Monthly* 時適用。 |
| **分鐘** | 嘗試下載前等待的分鐘數。僅當上面的間隔設定為 *Minute* 時適用。 |
| **Cron 運算式** | 表示 cron 運算式的五段字串，用於確定嘗試發生的時間。僅當上面的間隔設定為 *Advanced* 時適用。 |

### 效能

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

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

## 通知索引標籤

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

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

預設情況下，錯誤通知已啟用，這意味著每當發生錯誤時都會傳送電子郵件。要關閉它們，請取消選中 **啟用** 核取方塊。

輸入 **主題**（必填），然後可選地輸入以逗號分隔的 **收件人** 電子郵件清單。

## SLA 索引標籤

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

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

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

![空 SLA 配置](https://mintcdn.com/qiao/ImYlxBRjlKh9pKya/26.3/images/sla_empty.png?fit=max\&auto=format\&n=ImYlxBRjlKh9pKya\&q=85\&s=a3e02838303e09f3ddfc5d7b06db2987)

* 如果端口具有單獨的傳送和接收操作，請使用選項按鈕指定 SLA 適用的方向。
* 在視窗的 **預計至少** 部分：
  * 設定期望處理的最小交易數（數量）
  * 使用 **每** 欄位指定時間範圍
  * 指定 SLA 應何時生效。如果選擇 **開始於**，請填寫日期和時間欄位。
  * 勾選希望 SLA 生效的星期幾。如有需要，使用下拉功能表選擇 **每天**。
* 在視窗的 **將狀態設定為“有風險”** 部分，指定何時應將 SLA 標記為有風險。
  * 預設情況下，只有違反 SLA 後才會傳送通知。若要更改此設定，請選中 **傳送“有風險”通知**。

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

![SLA 配置範例](https://mintcdn.com/qiao/ImYlxBRjlKh9pKya/26.3/images/sla_defined.png?fit=max\&auto=format\&n=ImYlxBRjlKh9pKya\&q=85\&s=d8c67592769e76409cb1fba2c86c4805)

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

## 宏

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

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

| 宏 | 描述 |
| - | - |
| ConnectionName | 替換為端口使用的連線名稱。 |
| ConnectorID | 替換為端口的 ConnectorID。 |
| Ext | 替換為端口當前正在處理的檔案的副檔名。 |
| Filename | 替換為端口當前正在處理的檔案的檔名（包括副檔名）。 |
| FilenameNoExt | 替換為端口當前正在處理的檔案的檔名（不帶副檔名）。 |
| MessageId | 替換為端口輸出訊息的 MessageId。 |
| RegexFilename:*pattern* | 將規則運算式模式應用於端口當前正在處理的檔名。 |
| Header:*headername* | 替換為當前正在處理訊息上的目標訊息頭（`headername`）的值。 |
| LongDate | 替換為系統當前日期時間的長格式（例如，2024 年 1 月 24 日星期三）。 |
| ShortDate | 替換為系統當前日期時間的 yyyy-MM-dd 格式（例如 2024-01-24）。 |
| DateFormat:*format* | 替換為指定格式（`format`）的系統當前日期時間。有關可用日期時間格式，請參閱[範例日期格式](https://docs.kasoftware.com/26.3/self-hosted/zh/scripting/value-formatters/date-formatters.md#date-formats-with-literal-characters)。 |
| Vault:*vaultitem* | 替換為指定保管庫專案的值。 |
| Table | 替換為端口選擇資料所在的表名。 |
| PK | 替換為從表中接收的記錄的主索引鍵值。 |
| Sequence | 根據端口接收的記錄總數替換為四位數字（例如，對於傳回的第五條記錄，%Sequence% 替換為 0005）。 |
| FileFormat | 替換為端口 **高階** 索引標籤上指定的輸出檔案格式（XML、CSV 或 TSV）。 |

### 範例

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

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

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

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

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


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