> ## 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. # REST 端口 > 構建動態 REST 請求以使用 RESTful API Web 服務，支援所有 HTTP 方法、OAuth 2.0 以及由 ArcScript 驅動的 URL 和標頭。 REST 端口支援構建動態 REST 請求以使用 RESTful API Web 服務。 ## 核心功能 * 完整的 RESTful API 用戶端，支援所有 HTTP 方法（GET、POST、PUT、PATCH 和 DELETE） * 支援 Swagger 匯入，可自動配置 API 並生成請求 * 支援進階身分驗證，包括 OAuth 2.0、Bearer Token、AWS Signature、API Key 以及 Basic/Digest 認證 * 支援在 URL、標頭和表單資料中使用 ArcScript 構建動態請求 * 靈活的正文型別，包括 raw、form-data、URL-encoded 和檔案上傳 ## 概觀 REST 端口提供簡單介面，用於構建 REST 請求的標頭、授權、正文和 HTTP 方法。請求正文可以在端口配置中靜態設定，也可以根據端口處理的檔案動態生成。 ### 操作 此端口可以執行三種端口操作型別中的任何一種： • *觸發* 按計劃執行一個 request ，並且可能會生成要沿著工作流程傳送的檔案。此操作充當工作流程的起點。 • *轉換* 接受來自工作流程的訊息作為 request 的輸入並生成輸出。此操作充當工作流程的中間部分。 • *終結* 接受來自工作流程的訊息作為 request 的輸入並充當工作流程的終點。 ## 端口配置 ### 設定索引標籤 *與端口核心配置相關的設定。* #### 配置
設定 描述
**端口 Id** 端口的靜態、唯一識別碼。
**端口型別** 顯示端口型別及其用途的描述。
**端口描述** 一個可選欄位，用於提供端口及其在流中的角色的自由格式描述。
#### 進階設定 | 設定 | 說明 | | - | - | | **本地檔案方案** | 為端口輸出的訊息分配檔名的方案。可以在檔名中使用宏，動態包含識別碼和時間戳等資訊。有關更多資訊，請參見[宏](#宏)。 | ### REST 詳情索引標籤 *與端口請求詳細資訊相關的設定。* ![](https://mintcdn.com/qiao/HyyOl9gYIsxaiGgh/26.4/images/rest_details_tab.png?fit=max\&auto=format\&n=HyyOl9gYIsxaiGgh\&q=85\&s=beb92cf15668eab5b6bba0d918d92ef4) | 設定 | 說明 | | - | - | | **REST 詳情** | 選擇端口應執行的操作。（有關三個選項的詳細資訊，請參見[操作](#操作)。） | | **從 Swagger 匯入** | 單擊 ![從 Swagger 匯入](https://mintcdn.com/qiao/HyyOl9gYIsxaiGgh/26.4/images/rest_import_from_swagger.png?fit=max\&auto=format\&n=HyyOl9gYIsxaiGgh\&q=85\&s=df1870dcdee5497d25634d9abf8b0227) 圖示可直接從 Swagger URL 匯入 API 詳細資訊。 | | **測試** | 測試當前配置，而不建立傳送到工作流程下游的訊息或交易。單擊**測試**會開啟一個包含其他索引標籤的視窗（更多資訊請參見[測試請求配置](#測試請求配置)）。 | | **請求 URL** | REST 請求的 HTTP 方法和目標 HTTP URL。可用方法選項包括：GET、POST、PUT、PATCH 和 DELETE。 | | **允許在 URL 中使用 ArcScript** | 勾選此項可在發出查詢前對 URL 中的 ArcScript 運算式求值。選擇此項後，會顯示 **ArcScript 編輯器**按鈕（![ArcScript 編輯器按鈕](https://mintcdn.com/qiao/HyyOl9gYIsxaiGgh/26.4/images/rest_arcscript_editor.png?fit=max\&auto=format\&n=HyyOl9gYIsxaiGgh\&q=85\&s=9113829cbe1ae9572316802c46a91bec)），使你能夠使用 ArcScript 構建動態請求 URL。詳情請參見[使用 ArcScript 編輯器構建請求 URL 和標頭](#使用-arcscript-編輯器構建請求-url-和標頭)。 | | **正文型別** | 隨 REST 請求提供的正文內容類型。當 HTTP 方法為 GET 時不可見。有關每個選項的說明，請參見[正文](#正文)。 | | **內容類型** | 原始資料傳輸使用的內容類型。僅當**正文型別**設定為 `raw` 時可見。 | #### 查詢參數 使用此索引標籤向請求 URL 新增查詢參數。以名稱-值對形式提供參數，並可選擇新增說明。單擊**儲存**以使用參數更新 URL。 ![](https://mintcdn.com/qiao/HyyOl9gYIsxaiGgh/26.4/images/rest_query_params.png?fit=max\&auto=format\&n=HyyOl9gYIsxaiGgh\&q=85\&s=797c48b022a57b75bc298f1f6fcdcadf) 上圖包含兩組查詢參數。儲存端口後，`api.example.com` 請求 URL 會變為：`https://api.example.com/orders?status=pending&limit=50` 單擊右側的省略號可設定另外兩個選項：**批次編輯檢視**和**隱藏說明列**。 #### 認證 使用此索引標籤配置 API 請求的身分驗證憑據。 | 設定 | 說明 | | - | - | | **憑據** | 是否從先前配置的連線提供身分驗證憑據、建立新連線，或不帶身分驗證傳送請求。 **來自連線**：選擇此項，然後從下拉式清單中選擇你的**連線**。**注意**：單擊**連線**旁邊的加號可建立新連線。 **無憑據**：選擇此項可傳送不帶身分驗證的請求。此選項適用於公共 API，或透過[查詢參數](#查詢參數)或[標頭](#標頭)處理身分驗證的情況。 | | **TLS 伺服器憑證** | 用於驗證 TLS 伺服器身份的公開金鑰憑證。你可以上傳憑證，留空以允許底層 OS/JVM 執行憑證驗證，或設定為 `Any Certificate` 以信任目標伺服器的身份。請謹慎使用 Any Certificate：憑證用於驗證你連線的是預期伺服器。 | #### 標頭 此索引標籤使你能夠新增要包含在傳出 REST 請求中的 HTTP 標頭清單。標頭也以名稱-值對指定。更多資訊請參見[靜態請求](#靜態請求)和[動態請求](#動態請求)。單擊右側的省略號可存取另外三個選項：**批次編輯檢視**、**允許在標頭中使用 ArcScript** 和**顯示自動生成的標頭**。有關使用 ArcScript 編輯器的詳細資訊，請參見[使用 ArcScript 編輯器構建請求 URL 和標頭](#使用-arcscript-編輯器構建請求-url-和標頭)。 #### 正文 如果**正文型別**設定為 `form-data` 或 `x-www-urlencoded`，請使用**正文**索引標籤提供構成請求正文的一組名稱-值對（欄位）。以下清單更詳細地說明了每個選項。 * **none**：REST 請求不提供正文。 * **form-data**：正文以一組名稱-值對（欄位）提供。使用 **Name** 旁邊的下拉式清單選擇欄位型別。 * **Static**：同時提供 **Name** 和 **Value**。 * **XML**：在 UI 中提供 **Name**。**Value** 會從端口處理的輸入檔案中動態讀取。更多資訊請參見[動態表單資料](#動態表單資料)。 * **File**：每個端口可以有一個正文欄位設定為 File。這會使輸入檔案作為請求正文傳送。由於端口使用輸入檔案本身作為表單資料，因此 **Value** 欄位會變灰。 * **Header**：使用 **Value** 欄位指定從輸入訊息的哪個標頭讀取正文。 * **ArcScript**：提供的 **Value** 會渲染為 ArcScript，結果值會用於請求正文。 * **x-www-urlencoded**：正文的配置方式與 form-data 相同；但名稱-值對會編碼為 URL 查詢字串，而不是多部分表單資料。 * **raw**：正文設定為端口處理的輸入檔案內容。使用下拉式清單選擇正文的**內容類型**，或在**標頭**部分將其指定為自定義標頭。 單擊右側的省略號可存取另外兩個設定：**批次編輯檢視**和**顯示內容類型列**。顯示內容類型列後，可以按欄位為 `form-data` 和 `x-www-form-urlencoded` 正文型別提供內容類型。 #### 選項 *與請求相關的其他設定。* | 設定 | 說明 | | - | - | | **為錯誤回應建立輸出訊息** | 預設情況下，當回應以不表示成功的狀態碼傳送時，端口不會向工作流程輸出訊息。啟用此設定後，端口會為這些錯誤回應向工作流程輸出訊息。稍後可以在工作流程中使用 HTTP-Status-Code 標頭過濾訊息。 | | **壓縮 HTTP 請求** | 啟用此項可在傳送請求之前將 PUT 或 POST 請求的正文壓縮為 `gzip` 格式。傳出請求中還會新增 **Content-Encoding** 標頭。 | | **GET 請求正文** | 允許 GET 請求使用輸入訊息資料作為請求正文。 | | **HTTP 版本** | 連線到 REST 服務時使用 HTTP 1.0、1.1 還是 2.0。 | ### 進階選項卡 #### 認證 *與需要雙向 TLS 身分驗證時的用戶端身分驗證相關的設定。*
設定描述
**私有憑證** TLS 用戶端身分驗證期間提供的私有憑證。
**憑證密碼** 存取 TLS 用戶端憑證所需的密碼。
#### 進階設定 \_不屬於前述類別的設定。 | 設定 | 說明 | | - | - | | **分塊編碼** | 傳送請求時是否使用 HTTP 分塊傳輸編碼。這允許應用程式按順序傳送訊息的各部分（塊），以避免連線過載。 | | **塊大小** | 啟用**分塊編碼**時每個塊的大小（位元組）。 | | **跟隨 Authorization 標頭** | 啟用時，當重新導向到不同協議或主機名時保留 Authorization 標頭。 | | **輸出行為** | 預設情況下，端口輸出包含 `Response` 資料的訊息。其他選項允許你輸出 `Input Message` 以便進一步處理，或完全不輸出訊息。更多資訊請參見[回應事件](#回應事件)。 | | **逾時（秒）** | 擲回逾時錯誤之前等待 REST 伺服器回應的時長（秒）。 | | **回應標頭** | 設定後，端口會將 REST 訊息中的指定標頭提升為已下載訊息的中繼資料。可以用逗號分隔清單指定多個標頭。 | | **保留 Cookie** | 若要在輸出訊息上保留 Cookie，請提供要持久化的 Cookie 名稱逗號分隔清單。使用 `*` 可保留所有 Cookie。**注意**：僅保留名稱-值對，不執行屬性檢查。使用者負責確保 Cookie 不會洩露到非預期目標。 | | **啟用的 TLS 協議** | 建立出站連線時支援的 TLS/SSL 協議清單。最佳實踐是僅使用 TLS 協議。SSL v2 和 SSL v3 被認為存在漏洞，只有當夥伴不支援更高版本時才應使用。請注意，TLS v1.3 尚未普遍採用，如果目標伺服器不支援，可能會被拒絕。 | | **處理延遲** | 放入**交易**索引標籤的檔案延遲處理的時長（秒）。這是一箇舊版設定。最佳實踐是[使用 File 端口](https://docs.kasoftware.com/26.4/self-hosted/zh-Hant/flows/designing-a-flow.md#與本地檔案系統互動)管理本地檔案系統，而不是使用此設定。 | #### 代理設定 這是一組用於識別連線所經代理並對其進行身分驗證的設定。預設情況下，本節使用 [安全設定](https://docs.kasoftware.com/26.4/self-hosted/zh/getting-started/administration/settings/security.md) 頁面的 [代理設定](https://docs.kasoftware.com/26.4/self-hosted/zh/getting-started/administration/settings/proxy-settings.md) 部分中的全域設定。清除此核取方塊可為您的端口提供特定的設定。
設定描述
**代理型別** 基於代理的防火牆使用的協議。
**代理主機** 基於代理的防火牆的名稱或 IP 地址。
**代理端口** 基於代理的防火牆的 TCP 端口。
**代理使用者** 用於透過基於代理的防火牆進行身分驗證的使用者名稱。
**代理密碼** 用於對基於代理的防火牆進行身分驗證的密碼。
**身分驗證方案** 保留預設值 **None** 或選擇以下身分驗證方案之一：**Basic**、**Digest**、**Proprietary** 或 **NTLM**。
#### 日誌 *用於管理日誌建立和儲存的設定。*
設定 描述
**日誌級別** 指定要記錄在端口日誌目錄中的資訊型別：
  • **None** - 不建立任何日誌。
  • **Error** - 僅當端口遇到錯誤時才建立日誌。
  • **Warning** - 僅當端口發出警告時才建立日誌。
  • **Info** - 記錄工作流程的一般資訊，包括任何錯誤和警告（如果適用）。
  • **Debug** - 記錄成功和失敗工作流程的詳細偵錯資訊。
  • **Trace** - 記錄成功和失敗工作流程的詳細跟蹤資訊。
\*\*請注意：\*\***Debug** 和 **Trace** 級別的日誌可能會記錄敏感資訊，包括訊息內容和 SSL 憑證。儘管連線屬性（例如密碼）被遮蔽了，但在與您的組織外部共享它們之前，請檢視此級別的日誌以避免洩漏敏感資訊。
**日誌資料夾結構** 指示端口根據選定的時間間隔將日誌資料夾中的檔案分組。例如，**Weekly** 選項指示端口每週建立一個新的子資料夾，並將該周的所有日誌儲存在該資料夾中。空白設定告訴端口將所有日誌直接儲存在日誌資料夾中。對於處理許多交易的端口，使用子資料夾有助於保持日誌的有序性並提高效能。
**保留訊息副本** 指示端口在日誌目錄中儲存最新訊息副本的切換。請注意，端口每個子資料夾只保留一個訊息，並且端口在再次執行時會覆蓋以前儲存的訊息。
#### 其他設定 *特殊設定適用於特定用例。*
設定 描述
**其他設定** 允許在以分號分隔的清單中配置隱藏的端口設定，例如 `setting1=value1;setting2=value2`。正常的端口用例和功能不需要使用這些設定。
### 自動化索引標籤 #### 自動化設定 *與端口自動處理檔案相關的設定。* | 設定 | 說明 | | - | - | | **傳送** | 指示端口在檔案準備就緒時自動傳送檔案的開關。 | | **重試間隔** | 端口在重試失敗傳送之前等待的間隔。 | | **最大次數** | 端口嘗試傳送訊息的次數。將此值設定為 *1* 會指示端口僅進行初始傳送嘗試而不重試。端口會在每次嘗試之間等待**重試間隔**指定的時長。 | | **接收** | 指示端口按配置間隔自動發起 REST 請求的開關。 | | **間隔** | 端口發起配置的 REST 請求的間隔。 | | **整點後的分鐘數** | 小時計劃的分鐘偏移量。僅當上述間隔設定為\_每小時\_時適用。例如，如果此值設定為 5，自動化服務會在 1:05、2:05、3:05 等時間傳送請求。 | | **時間** | 嘗試發生的具體時間。僅當上述間隔設定為\_每天\_、\_每週\_或\_每月\_時適用。 | | **天** | 嘗試發生的日期。僅當上述間隔設定為\_每週\_或\_每月\_時適用。 | | **分鐘** | 發起請求前等待的分鐘數。僅當上述間隔設定為\_分鐘\_時適用。 | | **Cron 運算式** | 表示 Cron 運算式的五段字串，用於確定嘗試發生的時間。僅當上述間隔設定為\_進階\_時適用。 | | **開始日期和時間** | 自動化首次執行的日期和時間。之後的每次執行都遵循上方的間隔設定。上次和下次執行時間顯示在 [自動化狀態](#自動化狀態) 區段中。 | #### 自動化狀態 *唯讀摘要，顯示自動化是否正在執行、上次執行的結果以及下次執行的時間。* **自動化狀態**卡片顯示在 **自動化** 索引標籤的 **啟用** 核取方塊下方，適用於 **接收**、**下載** 和 **定時傳送** 自動化。該卡片回答三個問題：自動化是否已執行、執行是否成功，以及下次執行的時間。 在儲存端口之前，當您變更 **啟用** 核取方塊，或者變更 **間隔** 或 **開始日期和時間** 設定時，卡片會隨之更新。 ![自動化索引標籤上的自動化狀態卡片，顯示已暫停狀態、失敗的上次處理結果以及下次執行時間](https://docs.kasoftware.com/26.4/images/automation-status-card.png) 狀態 端口自動化的目前狀態。
狀態 描述
**進行中** 目前有一次執行正在進行，或者其他執行個體已鎖定該排程時段。
**閒置** 自動化正在等待下一次排程執行。
**已暫停** 端口在多次執行失敗後處於[退避](https://docs.kasoftware.com/26.4/self-hosted/zh/connectors/connector-backoff.md)狀態，自動化服務會略過該端口。
**已停用** 該端口的自動化已關閉。
上次執行時間 最近一次執行的結果。
欄位 描述
**日期** 上次執行的排程時間。
**上次處理開始時間** 端口實際開始處理上次執行的時間。該時間可能略晚於排程時間。
**上次處理結果** 上次執行的結果：
  • **成功**：執行已完成並處理了資料。
  • **無資料**：執行已完成，但沒有需要處理的內容，例如查詢未傳回任何資料列。
  • **失敗**：執行未完成。
**上次成功時間** 最近一次成功執行的日期和時間。當上次執行失敗或未傳回資料時，會顯示此欄位，讓您瞭解端口已有多長時間未成功執行。
下次執行時間 **日期** 欄位顯示自動化下一次排程執行的時間。自動化停用時，該欄位為空白。 檢視詳細資料 **已暫停** 狀態、**失敗** 結果和 **無資料** 結果都包含一個 **檢視詳細資料** 連結，點選後會開啟一個顯示完整訊息的對話方塊： 未執行與無資料 該卡片會區分尚未執行的端口與已執行但未找到任何內容的端口。如果 **上次處理結果** 為空白，表示自動化尚未執行，請檢查 **下次執行時間** 和排程設定。如果結果為 **無資料**，表示自動化已按排程執行，但資料來源未傳回任何內容，請檢查資料來源中是否有新資料。 已停用的端口 已停用的端口會保留其上次執行資訊，因此您仍可以檢視其上次執行的時間及結果。只有 **下次執行時間** 會被清除。 #### 效能 *與端口資源分配相關的設定。*
設定 描述
**最大工作執行緒數** 此端口上處理檔案時從執行緒池中消耗的最大工作執行緒數。如果設定，則會覆蓋 [進階設定](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) 部分的預設設定。
**最大檔案數** 分配給端口的每個執行緒傳送的最大檔案數。如果設定，則會覆蓋 [進階設定](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) 部分的預設設定。
### 告警索引標籤 *與配置通知相關的設定。* 在執行服務級別協議 (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) 以下範例顯示了為端口配置的 SLA，該端口預計在週一至週五每天接收 1000 個檔案。如果尚未收到 1000 個檔案，則會在時間段結束前 1 小時傳送風險通知。 ![SLA Configuration Example](https://docs.kasoftware.com/26.4/images/sla_defined.png) > [!NOTE] > > 如果有必要，可以關閉 SLA 通知。這在維護視窗期間非常有用。點選導覽列上的 **設定**，然後跳轉到 **通知 > 通用通知**。點選平板和鉛筆圖示進行編輯，並取消勾選 **SLA 通知** 設定。 ### 交易索引標籤 此索引標籤列出與端口關聯的所有訊息。使用搜尋欄查詢特定訊息，或單擊漏斗圖示應用篩選器。可以按時間、訊息方向和/或狀態進行篩選。 此索引標籤上的選項因端口的[操作型別](#操作)而異： * 如果端口是 **Trigger**，請使用**接收檔案**按鈕啟動工作流程。 * 如果端口是 **Transform** 或 **Terminal**，請使用**上傳檔案**按鈕將檔案上傳到工作流程。 ## 建立連線 與任何 REST 服務建立連線都需要有效的目標 URL。服務 URL 可以支援各種 HTTP 方法，你應根據特定 Web 服務操作或要檢索的資料集配置該方法。某些服務可能還需要身分驗證或一組自定義標頭才能使用該服務。 [認證](#認證)索引標籤的**憑據**部分使你能夠指定連線憑據。可從以下選項中選擇： * **來自連線**：選擇先前配置的 知行之橋 共享連線，或單擊**連線**欄位旁邊的加號以[建立連線](#建立連線)。 * **無憑據**適用於公共 API，或透過[查詢參數](#查詢參數)或[標頭](#標頭)處理身分驗證的情況。如果目標 URL 是 HTTPS URL，請將 **TLS 伺服器憑證**設定為標識伺服器的公開金鑰憑證。若要隱式信任目標端點，請將該欄位設定為 `Any Certificate`。 ### 建立連線 若要建立新連線，請選擇**來自連線**，然後單擊**連線**欄位旁邊的加號。 * 輸入唯一的**連線名稱**。 * **型別**始終設定為 REST。 * 選擇你的**身分驗證方案**。詳情請參見[認證方式](#認證方式)。 ### 認證方式 REST 端口支援多種身分驗證型別，每種型別都有自己的要求： * Basic（純文字）、Digest（加密）和 NTLM 需要使用者名稱-密碼身分驗證。這些憑據會作為請求中的標頭提供給 REST 服務。 * OAuth 身分驗證需要在 REST 服務的 Web 門戶或開發控制檯中註冊應用。應用註冊中要包含的 **Callback URL** 會顯示在 知行之橋 UI 中。選擇適用於 REST 服務的 **Grant Type**，並根據 REST 服務 Web 門戶或開發控制檯中顯示的詳細資訊指定其餘設定。然後單擊**取得新的存取權杖**以取得與服務互動所需的權杖。檢索到初始權杖後，應用程式會在權杖即將過期時重新整理它們。 * Bearer Token 身分驗證需要來自服務 Web 門戶或開發控制檯的權杖。 * AWS Signature 身分驗證用於對 Amazon 進行身分驗證，需要配置 Amazon 提供的憑據：**Access Key**、**Secret Key** 等。 * API Key 身分驗證需要一個鍵值對，然後必須指定該鍵應作為[標頭](#標頭)還是作為[查詢參數](#查詢參數)新增。 ## 測試請求配置 你可以隨時測試當前配置，而不建立傳送到工作流程下游的訊息或交易。單擊 **REST 詳情**索引標籤上的**測試**。下圖顯示了成功測試 Trigger 端口後的**回應正文**結果。 ![](https://mintcdn.com/qiao/HyyOl9gYIsxaiGgh/26.4/images/rest_test_tab.png?fit=max\&auto=format\&n=HyyOl9gYIsxaiGgh\&q=85\&s=44d9ae166da38b3ebaf8b61446bf2f45) * **回應正文**：以伺服器傳回的格式顯示 REST 請求的輸出。 * **回應標頭**：顯示伺服器傳回回應中包含的回應標頭。 * **訊息標頭**：顯示測試輸出中包含的訊息標頭。 * **日誌**：顯示測試日誌。 Transform 和 Terminal 端口有一個**輸入**窗格，其中包含 **XML**、**標頭**和**日誌**索引標籤。 * 只有在請求正文中定義了 XML 欄位時，**XML** 索引標籤才會填充，如下圖所示。 * 如果勾選了**允許在 URL 中使用 ArcScript** 或**允許在標頭中使用 ArcScript**，請使用**標頭**索引標籤提供可能在指令碼上下文中使用的訊息標頭（有關這些選項的詳情，請參見[使用 ArcScript 編輯器構建請求 URL 和標頭](#使用-arcscript-編輯器構建請求-url-和標頭)）。如果你的請求配置了作為 `form-data` 或 `x-www-form-urlencoded` 正文元素的[標頭](#標頭)，標頭名稱會顯示在此處，你可以提供用於測試的值。 * **日誌**索引標籤包含上次測試的結果。 ![](https://mintcdn.com/qiao/HyyOl9gYIsxaiGgh/26.4/images/rest_test_tab_transform.png?fit=max\&auto=format\&n=HyyOl9gYIsxaiGgh\&q=85\&s=a3d35d4ec2514b9f4c7c3ced895b6d41) ## 靜態請求 內容完全靜態的 REST 請求（例如使用 HTTP GET 方法的請求）不需要輸入檔案，因為請求內容完全在端口 UI 中配置。只需在**標頭**部分新增任何必要的名稱-值對作為自定義標頭，或在**正文**部分新增表單資料。 如果啟用**接收自動化**，可以按計劃自動傳送靜態請求。每個請求的回應會儲存在輸出資料夾中，或傳遞給工作流程中的下一個端口。 如果啟用**傳送自動化**，到達端口**交易**資料夾的檔案也會觸發靜態請求。輸入檔案的內容會被忽略，請求會根據 UI 中的配置傳送。 ## 動態請求 REST 請求可以使用到達端口**交易**資料夾的檔案中的資料動態填充。 ### 原始輸入資料 如果將請求的**正文型別**設定為 `raw`，輸入檔案的內容會作為 REST 請求正文傳送。 使用**內容類型**下拉式清單設定資料的特定內容類型。如果所需內容類型未列出，可以在**標頭**部分新增 *Content-Type* 標頭。 ### 動態表單資料 如果將請求的**正文型別**設定為 `form-data` 或 `x-www-urlencoded`，端口會從輸入檔案中查詢特定值來填充請求。對於設定為 `XML` 的每個名稱-值對，端口會掃描輸入檔案，查詢與欄位名稱相同且使用特定 XML 結構的 XML 元素，如下所示： ```xml theme={null} ``` 為適配此結構，知行軟體強烈建議在工作流程中的 REST 端口前使用 XML Map 端口，如[下文](#使用-xml-map-構建動態範本)所述。 當端口找到與欄位名稱和所需 XML 結構匹配的元素時，該元素中的值會用作名稱-值對中的值。例如，如果正文中有名為 `CustomerID` 的動態欄位，並且輸入檔案包含如下所示的 XML，則 REST 端口會將 `CustomerID` 欄位的值設定為 12354。 ```xml theme={null} 12354 ``` #### 使用 XML Map 構建動態範本 將 [XML Map](https://docs.kasoftware.com/26.4/self-hosted/zh-Hant/connectors/xml-map/xml-map.md) 端口與 REST 端口結合使用，可以輕鬆從其他 XML 資料結構構建動態請求。XML Map 端口會將自定義 XML 結構轉換為 REST 端口期望的 XML 結構。 首先，為 REST 端口配置請求中應存在的一組動態（和靜態）**正文**欄位。接下來，在 知行之橋 工作流程中將 XML Map 端口連線到 REST 端口，並儲存工作流程更改。這使 XML Map 端口能夠檢測 REST 端口期望在傳入輸入檔案中出現哪些欄位。 然後，在 XML Map 端口中，**目的檔案**下拉式清單會包含 REST 請求架構。選擇它作為目標，並將**來源檔案**設定為自定義 XML 結構。這會填充 XML Map 對映編輯器，你可以將需要包含在 REST 請求中的資料從源結構拖放到目標結構。對映完成後，XML Map 端口會自動將與來源檔案匹配的檔案轉換為有效的 REST 請求結構。 有關使用 XML Map 端口的更多資訊，請參見 [XML Map 端口文件](https://docs.kasoftware.com/26.4/self-hosted/zh-Hant/connectors/xml-map/xml-map.md)。 #### 動態標頭 還可以對 ArcScript 中的運算式求值，以生成動態字串作為標頭值。有關詳情和範例，請參見[標頭](#標頭)。 ## 使用 ArcScript 編輯器構建請求 URL 和標頭 可以使用如下所示的 ArcScript 編輯器構建請求 URL 和標頭。下圖顯示的是請求 URL 編輯器，但標頭值編輯器的工作方式相同。 ![](https://mintcdn.com/qiao/HyyOl9gYIsxaiGgh/26.4/images/rest_arcscript_editor_pane.png?fit=max\&auto=format\&n=HyyOl9gYIsxaiGgh\&q=85\&s=6d5ccb3d147d797a728f6fcac6535c04) 在端口配置窗格的 [REST 詳情索引標籤](#rest-詳情索引標籤)上選擇**允許在 URL 中使用 ArcScript**，以允許對 ArcScript 中的運算式求值並生成動態字串作為 URL。例如，以下 URL 包含日期和時間： `http://myendpoint.com/api?day=[_ | now('yyyyMMdd HH:mm:ss')]` 此 URL 包含用於透過傳送自動化觸發的查詢的傳入訊息標頭： `http://myendpoint.com/api?customer=[_message.header:customerid]` 最後，此 URL 使用從上次查詢時間到當前時間戳的動態日期範圍，併為第一次查詢使用預設時間戳： `http://myendpoint.com/api?DateFrom=[_connector.lastruntimestamp | def('2025-01-01T00:00:00-04:00')]&DateTo=[_connector.currenttimestamp]` 可以將運算式直接新增到 URL，也可以使用編輯器編寫它們。 選擇**允許在標頭中使用 ArcScript**，以便在發出查詢前對[標頭](#標頭)中的 ArcScript 運算式求值。例如，以下標頭包含日期和時間： `Timestamp [_ | now('yyyyMMdd')]` 此標頭包含用於透過傳送自動化觸發的查詢的客戶 ID： `Customer [_message.header:customerid]` ### 訊息標頭 訊息標頭幫助 知行之橋 跟蹤資料在工作流程中的進度。所有已跟蹤標頭都會顯示在編輯器的**訊息標頭**索引標籤上，你可以在運算式中引用它們。 還可以使用編輯器中的**新增訊息標頭**欄位並提供現有標頭的名稱，在運算式中包含其他訊息標頭。這些標頭不必是已跟蹤標頭。 ### 保管庫 使用 **Vault** 索引標籤可將[全域設定保管庫](https://docs.kasoftware.com/26.4/self-hosted/zh-Hant/getting-started/administration/settings/global-settings-vault.md)中的專案新增到運算式。如果你在整個工作流程的不同位置重複使用某些值，這會很有用。你可以在保管庫中定義這些值，然後在運算式開頭引用它們。請注意，如果希望對映使用保管庫中專案的\_值\_，需要在方括號內引用它；否則編輯器會將專案\_名稱\_解釋為字面量。 ### 格式化器 格式化器支援操作不同 xpath 傳回的值。在運算式中，格式化器用管道字元 (|) 分隔，並從左到右求值。例如： `[xpath('City') | toupper | substring(0,3)]` 在此範例中，傳回 `City` xpath 的值之前，所有字串字元都會轉換為大寫字元，並在結果中傳回前三個字元的子字串。例如，如果源文件有以下值： `Durham` 結果運算式傳回以下內容： `DUR` 格式化器列在**格式化器**索引標籤上。單擊清單中的格式化器可將其新增到運算式。 ## 回應事件 可以使用回應事件與從伺服器接收的回應（包括主體、標頭、Cookie 等）互動，並豐富端口產生的輸出訊息。可以在 `Response` 事件中使用以下特殊項目。 * [\_cookies](https://docs.kasoftware.com/26.4/self-hosted/zh-Hant/scripting/introduction-to-arcscript.md#http-cookie（_cookies）) * [\_message](https://docs.kasoftware.com/26.4/self-hosted/zh-Hant/scripting/introduction-to-arcscript.md#知行之橋訊息（_message）) * [\_request](https://docs.kasoftware.com/26.4/self-hosted/zh-Hant/scripting/introduction-to-arcscript.md#http-請求（_request）) * [\_response](https://docs.kasoftware.com/26.4/self-hosted/zh-Hant/scripting/introduction-to-arcscript.md#http-回應（_response）) ### 回應事件 Example 此指令碼讀取從伺服器接收的 JSON 回應，解析出 JSON 中包含的存取權杖，並將其作為標頭新增到端口建立的輸出訊息上： ```xml theme={null} ``` 以下步驟詳細說明了發生的情況： 1. 透過 `_response.body` 存取伺服器傳送回端口的回應正文，並將其設定為 jsonDOMGet 操作的 text 屬性。jsonDOMGet 的其他屬性也會被填充，例如 `map` 屬性，其中包含回應正文中所需權杖的 jsonpath。 2. 呼叫 jsonDOMGet 操作。如果在回應 JSON 正文中找到權杖，則會透過 `_message.header:access_token` 語法將其作為訊息標頭新增到端口的輸出訊息。如果未找到權杖，則 `access_token` 標頭的值會設定為靜態字串：*Token not found!*。 在 知行之橋 中檢視來自端口的訊息的輸出訊息詳細資訊時，結果如下所示： ![](https://mintcdn.com/qiao/HyyOl9gYIsxaiGgh/26.4/images/rest_response_event.png?fit=max\&auto=format\&n=HyyOl9gYIsxaiGgh\&q=85\&s=1845a3cd0d81d58982016f40d5add92f) 當你需要從傳送請求後伺服器傳回的原始 JSON 回應正文中解析資料時，這類指令碼很有用。隨後可以在工作流程的後續端口中讀取和使用該標頭。 > [!TIP] > > 如果伺服器使用 XML 回應，可以使用 xmlDOMGet 實現相同結果。 ## 宏 在檔案命名策略中使用宏可以提高組織效率和對資料的上下文理解。透過將宏合併到檔名中，可以動態地包含相關資訊，例如識別碼、時間戳和訊息頭資訊，從而為每個檔案提供有價值的上下文。這有助於確保檔名反映對組織重要的詳細資訊。 知行之橋 支援這些宏，它們都使用以下語法：`%Macro%`。
宏描述
ConnectorID替換為端口的 ConnectorID。
ConnectorName替換為端口名稱。可用於在檔名或路徑中包含連線名稱，例如按生成備份檔案的資料庫連線標記檔案。
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.4/self-hosted/zh/scripting/value-formatters/date-formatters.md#date-formats-with-literal-characters)。
Vault:*vaultitem*計算指定保管庫專案的值。
### 範例 某些宏（例如 %Ext% 和 %ShortDate%）不需要參數，但其他宏則需要。所有帶有參數的宏都使用以下語法：`%Macro:argument%` 以下是帶有參數的宏的一些範例： 還可以建立更復雜的宏，如以下範例所示： This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.