核心功能
- 完整的 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 方法。請求正文可以在端口配置中靜態設定，也可以根據端口處理的檔案動態生成。操作
端口配置
設定索引標籤
與端口核心配置相關的設定。配置
進階設定
REST 詳情索引標籤
與端口請求詳細資訊相關的設定。
| 設定 | 說明 |
|---|---|
| REST 詳情 | 選擇端口應執行的操作。（有關三個選項的詳細資訊，請參見操作。） |
| 從 Swagger 匯入 | 單擊  圖示可直接從 Swagger URL 匯入 API 詳細資訊。 |
| 測試 | 測試當前配置，而不建立傳送到工作流程下游的訊息或交易。單擊測試會開啟一個包含其他索引標籤的視窗（更多資訊請參見測試請求配置）。 |
| 請求 URL | REST 請求的 HTTP 方法和目標 HTTP URL。可用方法選項包括：GET、POST、PUT、PATCH 和 DELETE。 |
| 允許在 URL 中使用 ArcScript | 勾選此項可在發出查詢前對 URL 中的 ArcScript 運算式求值。選擇此項後，會顯示 ArcScript 編輯器按鈕（ ），使你能夠使用 ArcScript 構建動態請求 URL。詳情請參見使用 ArcScript 編輯器構建請求 URL 和標頭。 |
| 正文型別 | 隨 REST 請求提供的正文內容類型。當 HTTP 方法為 GET 時不可見。有關每個選項的說明，請參見正文。 |
| 內容類型 | 原始資料傳輸使用的內容類型。僅當正文型別設定為 raw 時可見。 |
查詢參數
使用此索引標籤向請求 URL 新增查詢參數。以名稱-值對形式提供參數，並可選擇新增說明。單擊儲存以使用參數更新 URL。
api.example.com 請求 URL 會變為：https://api.example.com/orders?status=pending&limit=50
單擊右側的省略號可設定另外兩個選項：批次編輯檢視和隱藏說明列。
認證
使用此索引標籤配置 API 請求的身分驗證憑據。標頭
此索引標籤使你能夠新增要包含在傳出 REST 請求中的 HTTP 標頭清單。標頭也以名稱-值對指定。更多資訊請參見靜態請求和動態請求。單擊右側的省略號可存取另外三個選項：批次編輯檢視、允許在標頭中使用 ArcScript 和顯示自動生成的標頭。有關使用 ArcScript 編輯器的詳細資訊，請參見使用 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 正文型別提供內容類型。
選項
與請求相關的其他設定。進階選項卡
認證
進階設定
_不屬於前述類別的設定。代理設定
日誌
其他設定
自動化索引標籤
自動化設定
與端口自動處理檔案相關的設定。效能
告警索引標籤
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 端口後的回應正文結果。
- 回應正文：以伺服器傳回的格式顯示 REST 請求的輸出。
- 回應標頭：顯示伺服器傳回回應中包含的回應標頭。
- 訊息標頭：顯示測試輸出中包含的訊息標頭。
- 日誌：顯示測試日誌。
- 只有在請求正文中定義了 XML 欄位時，XML 索引標籤才會填充，如下圖所示。
- 如果勾選了允許在 URL 中使用 ArcScript 或允許在標頭中使用 ArcScript，請使用標頭索引標籤提供可能在指令碼上下文中使用的訊息標頭（有關這些選項的詳情，請參見使用 ArcScript 編輯器構建請求 URL 和標頭）。如果你的請求配置了作為
form-data或x-www-form-urlencoded正文元素的標頭，標頭名稱會顯示在此處，你可以提供用於測試的值。 - 日誌索引標籤包含上次測試的結果。
靜態請求
內容完全靜態的 REST 請求（例如使用 HTTP GET 方法的請求）不需要輸入檔案，因為請求內容完全在端口 UI 中配置。只需在標頭部分新增任何必要的名稱-值對作為自定義標頭，或在正文部分新增表單資料。 如果啟用接收自動化，可以按計劃自動傳送靜態請求。每個請求的回應會儲存在輸出資料夾中，或傳遞給工作流程中的下一個端口。 如果啟用傳送自動化，到達端口交易資料夾的檔案也會觸發靜態請求。輸入檔案的內容會被忽略，請求會根據 UI 中的配置傳送。動態請求
REST 請求可以使用到達端口交易資料夾的檔案中的資料動態填充。原始輸入資料
如果將請求的正文型別設定為raw，輸入檔案的內容會作為 REST 請求正文傳送。
使用內容類型下拉式清單設定資料的特定內容類型。如果所需內容類型未列出，可以在標頭部分新增 Content-Type 標頭。
動態表單資料
如果將請求的正文型別設定為form-data 或 x-www-urlencoded，端口會從輸入檔案中查詢特定值來填充請求。對於設定為 XML 的每個名稱-值對，端口會掃描輸入檔案，查詢與欄位名稱相同且使用特定 XML 結構的 XML 元素，如下所示：
CustomerID 的動態欄位，並且輸入檔案包含如下所示的 XML，則 REST 端口會將 CustomerID 欄位的值設定為 12354。
使用 XML Map 構建動態範本
將 XML Map 端口與 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 端口文件。動態標頭
還可以對 ArcScript 中的運算式求值，以生成動態字串作為標頭值。有關詳情和範例，請參見標頭。使用 ArcScript 編輯器構建請求 URL 和標頭
可以使用如下所示的 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 索引標籤可將全域設定保管庫中的專案新增到運算式。如果你在整個工作流程的不同位置重複使用某些值，這會很有用。你可以在保管庫中定義這些值，然後在運算式開頭引用它們。請注意，如果希望對映使用保管庫中專案的_值_，需要在方括號內引用它；否則編輯器會將專案_名稱_解釋為字面量。格式化器
格式化器支援操作不同 xpath 傳回的值。在運算式中，格式化器用管道字元 (|) 分隔，並從左到右求值。例如：[xpath('City') | toupper | substring(0,3)]
在此範例中，傳回 City xpath 的值之前，所有字串字元都會轉換為大寫字元，並在結果中傳回前三個字元的子字串。例如，如果源文件有以下值：
<City>Durham</City>
結果運算式傳回以下內容：
DUR
格式化器列在格式化器索引標籤上。單擊清單中的格式化器可將其新增到運算式。
回應事件
可以在 REST 端口中使用回應事件與從伺服器接收的回應（包括正文、標頭、Cookie 等）互動，並豐富端口生成的輸出訊息。可以在Response 事件中使用以下特殊專案。
回應事件 Example
此指令碼讀取從 REST 呼叫接收的 JSON 回應，解析出 JSON 中包含的存取權杖，並將其作為標頭新增到 REST 端口建立的輸出訊息上：_response.body 存取伺服器傳送回知行之橋中 REST 端口的回應正文，並將其設定為 jsonDOMGet 操作的 text 屬性。jsonDOMGet 的其他屬性也會被填充，例如 map 屬性，其中包含回應正文中所需權杖的 jsonpath。
2 呼叫 jsonDOMGet 操作。如果在回應 JSON 正文中找到權杖，則會透過 _message.header:access_token 語法將其作為訊息標頭新增到 REST 端口的輸出訊息。如果未找到權杖，則 access_token 標頭的值會設定為靜態字串：Token not found!。
在 中檢視來自 REST 端口的訊息的輸出訊息詳細資訊時，結果如下所示：
