> ## 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 介面。

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

export const siteNameShort = "知行之橋";

export const siteName = "知行之橋";

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

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

## 影片資源

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

<iframe width="560" height="315" src="//player.bilibili.com/player.html?aid=700508398&bvid=BV1Hm4y1J7VW&cid=1185497528&page=1" scrolling="no" border="0" frameBorder="no" framespacing="0" allowFullScreen />

## 建立工作流程 API

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

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

   <img src="https://mintcdn.com/qiao/bVtjD3fvHFZBo1vE/public/images/flow_api_create.png?fit=max&auto=format&n=bVtjD3fvHFZBo1vE&q=85&s=a8b0cabbb5eac95486cb9e9f9596f459" alt="Create API Settings option in connector context menu" width="350" data-path="public/images/flow_api_create.png" />

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

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

   <img src="https://mintcdn.com/qiao/Ucivuk3ay0Gk5vqt/public/images/flow_api_createsettings_263.png?fit=max&auto=format&n=Ucivuk3ay0Gk5vqt&q=85&s=1ab99445926e7ede518d2df2f0fcd71b" alt="建立 API 設定頁面" width="500" data-path="public/images/flow_api_createsettings_263.png" />

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

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

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

   <img src="https://mintcdn.com/qiao/Ucivuk3ay0Gk5vqt/public/images/flow_api_workspace_263.png?fit=max&auto=format&n=Ucivuk3ay0Gk5vqt&q=85&s=d59a5f151a2a3d37691a05122ad36433" alt="工作區中的工作流程 API" width="800" data-path="public/images/flow_api_workspace_263.png" />

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

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

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

### 不支援的端口

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

* [API](../connectors/api/api)
* [Copy](../connectors/copy)
* [Email Receive](../connectors/email-receive)
* [Form](../connectors/form)
* [FTP Server](../connectors/ftp-server)
* [RSS](../connectors/rss)
* [Schedule](../connectors/schedule)
* [SFTP Server](../connectors/sftp-server)
* [Webhook](../connectors/webhook)
* [Workspace Receive](../connectors/workspace-receive)

### 工作流程 API 範例

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

<img src="https://mintcdn.com/qiao/Ucivuk3ay0Gk5vqt/public/images/flow_api_example_263.png?fit=max&auto=format&n=Ucivuk3ay0Gk5vqt&q=85&s=cb5bc592c44af59967555cf67f317a0d" alt="工作區中的工作流程 API 範例" width="800" data-path="public/images/flow_api_example_263.png" />

此工作流程 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 標題中的齒輪狀設定圖示，以開啟 **設定** 面板。

<img src="https://mintcdn.com/qiao/bVtjD3fvHFZBo1vE/public/images/flow_api_opensettings.png?fit=max&auto=format&n=bVtjD3fvHFZBo1vE&q=85&s=dc41da5627810cb6ee04ef82aa31c803" alt="Opening the Flow API settings pane" width="400" data-path="public/images/flow_api_opensettings.png" />

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

<img src="https://mintcdn.com/qiao/Ucivuk3ay0Gk5vqt/public/images/flow_api_settings_263.png?fit=max&auto=format&n=Ucivuk3ay0Gk5vqt&q=85&s=b76191b8c0e86d89e50c7489a03a5e19" alt="工作流程 API 設定面板" width="700" data-path="public/images/flow_api_settings_263.png" />

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

#### 請求

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

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

#### 中繼資料頭

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

#### 查詢參數

此部分使你能夠為工作流程指定查詢字串參數。如果在此處新增參數，當訊息沿工作流程向下傳遞時，它們將作為中繼資料頭保留下來。這些頭以 `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 包含：

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

  <img src="https://mintcdn.com/qiao/bVtjD3fvHFZBo1vE/public/images/flow_api_upload_file.png?fit=max&auto=format&n=bVtjD3fvHFZBo1vE&q=85&s=ce3c0566f2ec2b2566605f2f7808a29f" alt="File upload button in the testing pane" width="500" data-path="public/images/flow_api_upload_file.png" />

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

<Note>如果需要 API 傳回 Base64 編碼的文字而不是二進位檔案，需要使用 [Script](../connectors/script) 端口將輸出編碼為 Base64，並將回應內容類型設定為類似 `text/plain` 的型別。</Note>

### 呼叫存取使用者

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

<img src="https://mintcdn.com/qiao/Ucivuk3ay0Gk5vqt/public/images/flow_api_invoke_access_users.png?fit=max&auto=format&n=Ucivuk3ay0Gk5vqt&q=85&s=42f6608dbd24104d2f9284b16b35421a" alt="能夠呼叫工作流程 API 的使用者清單" width="700" data-path="public/images/flow_api_invoke_access_users.png" />

### 測試工作流程 API

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

<img src="https://mintcdn.com/qiao/bVtjD3fvHFZBo1vE/public/images/flow_api_opentest.png?fit=max&auto=format&n=bVtjD3fvHFZBo1vE&q=85&s=70a8f36d132564c70f0ebb0215bde129" alt="Opening the Flow API testing pane" width="400" data-path="public/images/flow_api_opentest.png" />

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

<img src="https://mintcdn.com/qiao/Ucivuk3ay0Gk5vqt/public/images/flow_api_test_263.png?fit=max&auto=format&n=Ucivuk3ay0Gk5vqt&q=85&s=8e2416e4a070097c53922c7342ca1243" alt="工作流程 API 測試面板" width="800" data-path="public/images/flow_api_test_263.png" />

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

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

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

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

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

   <img src="https://mintcdn.com/qiao/U-KEZ9JbQY4Wqs1D/public/images/arc_flow_method.png?fit=max&auto=format&n=U-KEZ9JbQY4Wqs1D&q=85&s=ed76871b9ef0e44cfc69a1218fd7224d" alt="Select a method in Create API Settings" width="500" data-path="public/images/arc_flow_method.png" />

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

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

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

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

   <img src="https://mintcdn.com/qiao/U-KEZ9JbQY4Wqs1D/public/images/arc_body_content.png?fit=max&auto=format&n=U-KEZ9JbQY4Wqs1D&q=85&s=680ee31500857b96cd48a265f9687ce9" alt="Copy and paste the Content-Type path in Postman" width="800" data-path="public/images/arc_body_content.png" />

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

   要使用該方法：

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

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

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

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

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

      3. 將在 {siteNameShort} 中複製的身分驗證權杖貼上到 **Value** 欄位中。

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

   <img src="https://mintcdn.com/qiao/U-KEZ9JbQY4Wqs1D/public/images/arc_response_to_request.png?fit=max&auto=format&n=U-KEZ9JbQY4Wqs1D&q=85&s=a48383367e41a270578e863ce95954e4" alt="Response to the request in Postman" width="800" data-path="public/images/arc_response_to_request.png" />

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

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

<CommonCors />