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

# 工作流程 API

> 使用工作流程 API 建立知行之橋工作流程並將其公開為可查詢的 REST 介面。

工作流程 API 使你能夠建立模組化的單路徑 知行之橋 工作流程，並將它們公開為可以查詢的介面。知行之橋 會處理你傳遞給工作流程 API 介面的資料，並將結果傳回給查詢服務。

你可以使用工作流程 API 從外部應用程式和服務執行 知行之橋 工作流程。這種靈活性使你能夠使用自己選擇的工具來管理工作流程和自動化。

## 影片資源

觀看此短影片，瞭解如何設定和使用工作流程 API。

[//player.bilibili.com/player.html?aid=700508398\&bvid=BV1Hm4y1J7VW\&cid=1185497528\&page=1](//player.bilibili.com/player.html?aid=700508398\&bvid=BV1Hm4y1J7VW\&cid=1185497528\&page=1)

## 建立工作流程 API

透過以下步驟建立工作流程 API：

1. 在工作流程畫布上，右鍵單擊端口並選擇 **建立 API 設定**。

   ![Create API Settings option in connector context menu](https://mintcdn.com/qiao/kYLwR1iZrGqYINH1/26.4/images/flow_api_create.png?fit=max\&auto=format\&n=kYLwR1iZrGqYINH1\&q=85\&s=7dd0e83e5edf1ed1ee741b5e25ba0eae)

   > [!NOTE]
   >
   > 工作流程 API 目前不支援某些端口。如果端口不受支援，當你嘗試將該端口新增到工作流程 API 時，知行之橋 會顯示一條錯誤訊息。有關不能在工作流程 API 中使用的端口清單，請參閱[不支援的端口](#不支援的端口)。

2. **建立 API 設定** 頁面會開啟。在 **方法** 欄位中，選擇你希望工作流程 API 接受請求的 HTTP 方法。選項包括 **GET**、**POST**、**PUT**、**PATCH** 和 **DELETE**。建立工作流程 API 後，可以根據需要更改此設定。

   ![建立 API 設定頁面](https://mintcdn.com/qiao/kYLwR1iZrGqYINH1/26.4/images/flow_api_createsettings_263.png?fit=max\&auto=format\&n=kYLwR1iZrGqYINH1\&q=85\&s=c7a9c9895345320877f6943953e46173)

3. 在 **路徑** 欄位中，輸入工作流程 API 的名稱。發出 API 查詢時會使用此名稱。

   > [!NOTE]
   >
   > 只有當 API 名稱執行不同功能時，才可以重複使用。例如，可以有一個名為 API\_X12、執行 POST 功能的工作流程 API，也可以有一個名為 API\_X12、執行 PATCH 功能的工作流程 API，但不能有兩個都名為 API\_x12 且都執行 POST 功能的工作流程 API。

4. 單擊 **建立 API**。系統會在**設定**索引標籤中開啟**工作流程 API 設定**，工作流程 API 也會顯示在工作區中。

   ![工作區中的工作流程 API](https://mintcdn.com/qiao/kYLwR1iZrGqYINH1/26.4/images/flow_api_workspace_263.png?fit=max\&auto=format\&n=kYLwR1iZrGqYINH1\&q=85\&s=2cd53aec27c44978780ea6f4dfe3fcfe)

5. 將其他端口拖到工作流程 API 框中，並將它們連線在一起。也可以向工作流程 API 框新增註解。

> [!NOTE]
>
> 工作流程 API 中的第一個端口從發出查詢的實體接收輸入資料，最後一個端口將輸出資料傳送回發出查詢的實體。

完成新增和連結端口後，可以[配置和測試工作流程 API](#配置和測試工作流程-api)。

### 不支援的端口

工作流程 API 中的端口必須以一種方式連線，從而為每個輸入訊息產生一個輸出訊息。不支援基於計劃或外部處理程序處理檔案的端口。因此，工作流程 API 中不允許使用以下端口：

* [API](https://docs.kasoftware.com/26.4/self-hosted/zh-Hant/connectors/api/api.md)
* [Copy](https://docs.kasoftware.com/26.4/self-hosted/zh-Hant/connectors/copy.md)
* [Email Receive](https://docs.kasoftware.com/26.4/self-hosted/zh-Hant/connectors/email-receive.md)
* [Form](https://docs.kasoftware.com/26.4/self-hosted/zh-Hant/connectors/form.md)
* [FTP Server](https://docs.kasoftware.com/26.4/self-hosted/zh-Hant/connectors/ftp-server.md)
* [RSS](https://docs.kasoftware.com/26.4/self-hosted/zh-Hant/connectors/rss.md)
* [Schedule](https://docs.kasoftware.com/26.4/self-hosted/zh-Hant/connectors/schedule.md)
* [SFTP Server](https://docs.kasoftware.com/26.4/self-hosted/zh-Hant/connectors/sftp-server.md)
* [Webhook](https://docs.kasoftware.com/26.4/self-hosted/zh-Hant/connectors/webhook.md)
* [Workspace Receive](https://docs.kasoftware.com/26.4/self-hosted/zh-Hant/connectors/workspace-receive.md)

### 工作流程 API 範例

以下範例顯示了一個配置為 POST 的工作流程 API 的真實用例：

![工作區中的工作流程 API 範例](https://mintcdn.com/qiao/kYLwR1iZrGqYINH1/26.4/images/flow_api_example_263.png?fit=max\&auto=format\&n=kYLwR1iZrGqYINH1\&q=85\&s=9ee02d55ca849f5e1d329309d9a03d2f)

此工作流程 API 執行以下工作流程：

1. 資料在開始節點以加密的 X12 檔案形式接收。

2. OpenPGP\_Decrypt 端口解密 X12 檔案，並將其傳遞給 X12 端口。

3. X12 端口將 X12 檔案轉換為 XML，並將轉換後的 XML 檔案傳遞給 JSON 端口。

4. JSON 端口將 XML 檔案轉換為 JSON 格式，並將轉換後的檔案傳遞給 OpenPGP\_Encrypt 端口，後者對 JSON 檔案進行加密。

5. 加密的 JSON 檔案透過結束節點傳回。

在本例中，每個端口都連結到另外兩個端口，一個在前面，一個在後面。開始和結束節點會自動新增到工作流程的介面。

## 配置和測試工作流程 API

建立工作流程 API 後，可以配置其設定並執行範例請求來測試配置。

### 配置設定

單擊工作流程 API 標題中的齒輪狀設定圖示，以開啟 **設定** 面板。

![Opening the Flow API settings pane](https://mintcdn.com/qiao/kYLwR1iZrGqYINH1/26.4/images/flow_api_opensettings.png?fit=max\&auto=format\&n=kYLwR1iZrGqYINH1\&q=85\&s=f331799d870a27f2c68863790d981f99)

在此面板中，可以配置工作流程 API 的行為。

![工作流程 API 設定面板](https://mintcdn.com/qiao/kYLwR1iZrGqYINH1/26.4/images/flow_api_settings_263.png?fit=max\&auto=format\&n=kYLwR1iZrGqYINH1\&q=85\&s=b4304c0ef43176218bcbe9fb9bcfa4aa)

這些設定在以下章節中概觀。

#### 請求

在 **路徑** 欄位中，選擇工作流程 API 的請求型別。如果更改請求型別，請確保端口的結構和配置對於新的請求型別是正確的。

使用 **說明** 欄位輸入工作流程 API 的可選描述。當你有多個工作流程 API 並希望跟蹤每個工作流程 API 的用途時，這會很有用。

#### 中繼資料頭

請求中包含的所有頭資訊都會隨訊息在工作流程中傳遞時保留下來。這些頭以 `API-Header-` 為字首，因此名為 `MyHeader` 的頭將顯示為 `API-Header-MyHeader`。在[日誌頁面](https://docs.kasoftware.com/26.4/self-hosted/zh-Hant/getting-started/administration/activity.md)中展開訊息時，可以看到這些頭。也可以在端口的 **交易記錄** 索引標籤上展開交易時檢視頭資訊。

#### 查詢參數

此部分使你能夠為工作流程指定查詢字串參數。如果在此處新增參數，當訊息沿工作流程向下傳遞時，它們將作為中繼資料頭保留下來。這些頭以 `API-QueryParameter-` 為字首，因此 `test` 的查詢字串將使用 `API-QueryParameter-test`。這些頭與[中繼資料頭](#中繼資料頭)顯示在相同的位置。

如果你希望將某些資訊作為請求的一部分傳遞，但該資訊不是請求體的一部分，那麼此功能會很有用。例如，如果想要查詢資料庫中特定公司的最近銷售訂單 ID，可以將 CompanyName 查詢參數新增到 API 中，並在工作流程中使用 `API-QueryParameter-CompanyName` 頭引用它。

#### 主體和回應

在 **主體** 部分中，選擇與查詢用戶端和工作流程 API 通訊方式相對應的 **型別**：

* **None**—請求中不預期包含主體
* **Raw**—任意格式的自由格式資料
* **Form data**—名稱-值對
* **x-www-form-urlencoded**

在 **主體** 和 **回應** 的文字欄位中，使用下拉功能表選擇主體和回應的預期資料格式（**XML**、**JSON** 或 **Custom**）。

#### 處理二進位檔案

工作流程 API 支援將二進位檔案（PDF、JPEG 或其他二進位檔案型別）作為請求體或回應體進行上傳和下載。開啟測試面板（參見[測試工作流程 API](#測試工作流程-api)）時，工作流程 API 包含：

* 當請求體內容類型為二進位檔案時，提供檔案上傳按鈕，如下圖所示

  ![File upload button in the testing pane](https://mintcdn.com/qiao/kYLwR1iZrGqYINH1/26.4/images/flow_api_upload_file.png?fit=max\&auto=format\&n=kYLwR1iZrGqYINH1\&q=85\&s=09841dde2db97bcf2f9f06b6ebcca7b6)

* 當回應內容類型為二進位檔案時，提供檔案下載按鈕

> [!NOTE]
>
> 如果需要 API 傳回 Base64 編碼的文字而不是二進位檔案，需要使用 [Script](https://docs.kasoftware.com/26.4/self-hosted/zh-Hant/connectors/script.md) 端口將輸出編碼為 Base64，並將回應內容類型設定為類似 `text/plain` 的型別。

### 呼叫存取使用者

要檢視能夠呼叫工作流程 API 的使用者，請開啟**設定**面板並點選**呼叫存取使用者**。此索引標籤根據分配給使用者的[策略](https://docs.kasoftware.com/26.4/self-hosted/zh-Hant/getting-started/administration/settings/user-roles.md#建立角色和策略)，列出能夠呼叫該 API 的所有標準使用者和服務使用者。點選**新增使用者**可授予其他使用者呼叫權限。

![能夠呼叫工作流程 API 的使用者清單](https://mintcdn.com/qiao/kYLwR1iZrGqYINH1/26.4/images/flow_api_invoke_access_users.png?fit=max\&auto=format\&n=kYLwR1iZrGqYINH1\&q=85\&s=de05ff80377f1cdedadef05c0f0d0431)

### 測試工作流程 API

要開啟工作流程 API 的測試面板，請單擊工作流程 API 標題中的三角形圖示。

![Opening the Flow API testing pane](https://mintcdn.com/qiao/kYLwR1iZrGqYINH1/26.4/images/flow_api_opentest.png?fit=max\&auto=format\&n=kYLwR1iZrGqYINH1\&q=85\&s=120d91e154a3ce823f4a9f2ab097749c)

在測試面板中，左側的框充當請求，右側的框顯示回應。每個框都會顯示在設定面板中選擇的預期資料格式。

![工作流程 API 測試面板](https://mintcdn.com/qiao/kYLwR1iZrGqYINH1/26.4/images/flow_api_test_263.png?fit=max\&auto=format\&n=kYLwR1iZrGqYINH1\&q=85\&s=9581a5c2339d45d4ebc295173a050941)

要測試工作流程 API，請在左側框中輸入測試查詢，然後單擊 **執行**。如果回應與預期結果匹配，則工作流程 API 已可使用。如果回應不正確，請檢查工作流程 API 的配置以及工作流程 API 中每個端口的配置。

## 將工作流程 API 與外部應用程式一起使用

以下步驟說明如何從外部用戶端呼叫工作流程 API。此範例展示瞭如何從 Postman 執行工作流程 API，但也可以使用任何能夠傳送 REST 請求的用戶端。

1. 使用工作流程設計器右下角的 **選擇多個端口** 選項，選擇要公開為 API 的工作流程。然後單擊 **建立 API 設定**。此操作會開啟 **建立 API 設定** 對話方塊。

2. 選擇一個方法（例如 **POST**），如下所示，併為 API 指定一個有意義的名稱。

   ![Select a method in Create API Settings](https://mintcdn.com/qiao/4hcVjuRd69QHuQ3V/26.4/images/arc_flow_method.png?fit=max\&auto=format\&n=4hcVjuRd69QHuQ3V\&q=85\&s=153897a34c9f3de9d35e73b5eecc48ae)

3. 單擊 **建立 API** 建立工作流程 API。

4. 在 **設定** 面板中，配置工作流程 API，以在 **主體** 部分定義預期的 <var>Content-Type</var> 值，並在 **回應** 部分定義所需回應的 <var>Content-Type</var> 值。也可以選擇為請求和回應提供範例資料。

5. 複製**請求**面板中顯示的路徑。

6. 開啟 Postman 應用程式。確保 <var>Content-Type</var> 下拉式清單中顯示相同的內容類型（在本例中為 **POST**）。然後，將在 知行之橋 中複製的路徑（第 5 步）貼上到請求 URL 欄位中。將請求正文指定為應啟動工作流程的內容。

   ![Copy and paste the Content-Type path in Postman](https://mintcdn.com/qiao/4hcVjuRd69QHuQ3V/26.4/images/arc_body_content.png?fit=max\&auto=format\&n=4hcVjuRd69QHuQ3V\&q=85\&s=f48f08d2276cbab646bf2c6c48215242)

7. 對工作流程 API 進行身分驗證。工作流程 API 使用與 Admin API 相同的身分驗證規則。此範例使用身分驗證權杖頭（**x-cdata-authtoken**）作為身分驗證方法。

   要使用該方法：

   1. 單擊導覽列上的 **設定** 齒輪圖示。然後，單擊 **新增** 以開啟 **新增使用者** 對話方塊，或編輯現有使用者。

   2. 在出現的對話方塊中，選中 **API Access** 核取方塊以顯示身分驗證權杖。（請將此權杖複製到安全位置，因為該對話方塊不會再次顯示。如果丟失或刪除身分驗證權杖，則必須建立新權杖。）然後單擊 **儲存更改**。

   3. 傳回 Postman 應用程式並按如下方式新增工作流程 API 的身分驗證憑據：

      1. 單擊 **Headers** 索引標籤。

      2. 將 **x-cdata-authtoken** 貼上到 **Key** 欄位中。

      3. 將在 知行之橋 中複製的身分驗證權杖貼上到 **Value** 欄位中。

8. 請求準備就緒後，單擊 **Send** 按鈕。應該會看到對所傳送請求的回應，如下例所示：

   ![Response to the request in Postman](https://mintcdn.com/qiao/4hcVjuRd69QHuQ3V/26.4/images/arc_response_to_request.png?fit=max\&auto=format\&n=4hcVjuRd69QHuQ3V\&q=85\&s=3099f86e5e03c92819d00126e9f31b51)

### 跨源資源共享（CORS）

可以透過導航到[安全索引標籤](https://docs.kasoftware.com/26.4/self-hosted/zh-Hant/getting-started/administration/settings/security.md)中的 [Admin API](../admin-api) 部分，為工作流程 API 配置跨源資源共享（CORS）。CORS 允許基於瀏覽器的用戶端連線到 知行之橋。如果沒有 CORS，由於瀏覽器強制執行同源策略，基於瀏覽器的指令碼將無法連線到 知行之橋。此策略限制用戶端指令碼和文件載入其來源之外的資源。指令碼的來源由協議、主機和端口組成。

<table><thead><tr><th>設定</th><th>描述</th></tr></thead>
<tbody><tr><td>**啟用跨源資源共享 (CORS)**</td>
<td>是否啟用 CORS。僅當選中此框時，其餘選項才可用。</td></tr>
<tr><td>**允許所有不帶 '\*' 的域**</td>
<td>如果啟用，域來源不限於特定清單。</td></tr>
<tr><td>**Access-Control-Allow-Origin**</td>
<td>要允許的以逗號分隔的域來源清單。作為 HTTP 回應訊息頭包含在內。</td></tr>
<tr><td>**Access-Control-Allow-Credentials**</td>
<td>跨域請求中是否允許使用者憑據（例如 cookie）。作為 HTTP 回應訊息頭包含在內。</td></tr>
<tr><td>**Access-Control-Allow-Methods**</td>
<td>允許的以逗號分隔的方法清單。作為 HTTP 回應訊息頭包含在內。</td></tr>
<tr><td>**Access-Control-Allow-Headers**</td>
<td>允許的訊息頭的逗號分隔清單。作為 HTTP 回應訊息頭包含在內。</td></tr>
<tr><td>**Access-Control-Max-Age**</td>
<td>可以快取 Access-Control 回應訊息頭值的最大持續時間（以秒為單位）。</td></tr></tbody></table>


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