> ## 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 和標頭。

export const TlsClientAuthentication = () => <>
    <p><em>與需要雙向 TLS 身分驗證時的用戶端身分驗證相關的設定。</em></p>

    <table>
      <thead>
        <tr><th>設定</th><th>描述</th></tr>
      </thead>
      <tbody>
        <tr>
          <td><strong>私有憑證</strong></td>
          <td>TLS 用戶端身分驗證期間提供的私有憑證。</td>
        </tr>
        <tr>
          <td><strong>憑證密碼</strong></td>
          <td>存取 TLS 用戶端憑證所需的密碼。</td>
        </tr>
      </tbody>
    </table>
  </>;

export const CommonProxySettings = () => <>
    <p>這是一組用於識別連線所經代理並對其進行身分驗證的設定。預設情況下，本節使用 <a href="/26.3/self-hosted/zh/getting-started/administration/settings/security">安全設定</a> 頁面的 <a href="/26.3/self-hosted/zh/getting-started/administration/settings/proxy-settings">代理設定</a> 部分中的全域設定。清除此核取方塊可為您的端口提供特定的設定。</p>
    <table>
      <thead>
        <tr><th>設定</th><th>描述</th></tr>
      </thead>
      <tbody>
        <tr>
          <td><strong>代理型別</strong></td>
          <td>基於代理的防火牆使用的協議。</td>
        </tr>
        <tr>
          <td><strong>代理主機</strong></td>
          <td>基於代理的防火牆的名稱或 IP 地址。</td>
        </tr>
        <tr>
          <td><strong>代理端口</strong></td>
          <td>基於代理的防火牆的 TCP 端口。</td>
        </tr>
        <tr>
          <td><strong>代理使用者</strong></td>
          <td>用於透過基於代理的防火牆進行身分驗證的使用者名稱。</td>
        </tr>
        <tr>
          <td><strong>代理密碼</strong></td>
          <td>用於對基於代理的防火牆進行身分驗證的密碼。</td>
        </tr>
        <tr>
          <td><strong>身分驗證方案</strong></td>
          <td>保留預設值 <strong>None</strong> 或選擇以下身分驗證方案之一：<strong>Basic</strong>、<strong>Digest</strong>、<strong>Proprietary</strong> 或 <strong>NTLM</strong>。</td>
        </tr>
      </tbody>
    </table>
  </>;

export const CommonActionType = ({resource = "script"}) => <>
    <p>此端口可以執行三種端口操作型別中的任何一種：</p>
    <p style={{
  paddingLeft: '1.5rem',
  marginTop: '0.25rem',
  marginBottom: '0.25rem'
}}>• <em>觸發</em> 按計劃執行一個 {resource} ，並且可能會生成要沿著工作流程傳送的檔案。此操作充當工作流程的起點。</p>
    <p style={{
  paddingLeft: '1.5rem',
  marginTop: '0.25rem',
  marginBottom: '0.25rem'
}}>• <em>轉換</em> 接受來自工作流程的訊息作為 {resource} 的輸入並生成輸出。此操作充當工作流程的中間部分。</p>
    <p style={{
  paddingLeft: '1.5rem',
  marginTop: '0.25rem',
  marginBottom: '0.25rem'
}}>• <em>終結</em> 接受來自工作流程的訊息作為 {resource} 的輸入並充當工作流程的終點。</p>
  </>;

export const NameDescription = ({extraRows}) => <table>
    <thead>
      <tr>
        <th>設定</th>
        <th>描述</th>
      </tr>
    </thead>
    <tbody>
      <tr>
        <td><strong>端口 Id</strong></td>
        <td>端口的靜態、唯一識別碼。</td>
      </tr>
      <tr>
        <td><strong>端口型別</strong></td>
        <td>顯示端口型別及其用途的描述。</td>
      </tr>
      <tr>
        <td><strong>端口描述</strong></td>
        <td>一個可選欄位，用於提供端口及其在流中的角色的自由格式描述。</td>
      </tr>
      {extraRows}
    </tbody>
  </table>;

export const SlasTab = ({siteName = "知行之桥"}) => <>
    <p><em>與配置服務級別協議 (SLA) 相關的設定。</em></p>
    <p>
      SLA 允許配置預期流程中端口傳送或接收的資料量，並設定預期達到該資料量的時間範圍。當 SLA 未達到時，{siteName} 會傳送電子郵件警告使用者，並將 SLA 標記為 <em>存在風險</em>，這意味著如果 SLA 未能儘快達到，則會被標記為 <em>已違反</em>。這讓使用者有機會介入並確定 SLA 未達到的原因，並採取適當的措施。如果在風險時間段結束時仍未達到 SLA，則會將 SLA 標記為已違反，並再次通知使用者。
    </p>
    <p>
      要定義 SLA，請啟用 <strong>預期資料量</strong>，然後點選 <strong>設定</strong> 索引標籤。
    </p>
    <img src="/public/images/sla_empty.png" alt="SLA Empty" />
    <ul>
      <li>如果端口具有單獨的傳送和接收操作，請使用選項按鈕指定 SLA 適用的方向。</li>
      <li>在視窗的 <strong>預計至少</strong> 部分中：
        <ul>
          <li>設定預計處理的最小交易數量（交易量）</li>
          <li>使用 <strong>每個</strong> 欄位指定時間範圍</li>
          <li>指示 SLA 生效的時間。如果選擇 <strong>開始於</strong>，請填寫日期和時間欄位。</li>
          <li>勾選希望 SLA 生效的星期幾對應的核取方塊。如有必要，請使用下拉功能表選擇 <strong>每天</strong>。</li>
        </ul>
      </li>
      <li>在視窗的 <strong>將狀態設定為“有風險”</strong> 部分中，指定應將 SLA 標記為有風險的時間。
        <ul>
          <li>預設情況下，只有在違反 SLA 的情況下才會傳送通知。要更改此設定，請勾選 <strong>傳送“有風險”通知</strong>。</li>
        </ul>
      </li>
    </ul>
    <p>
      以下範例顯示了為端口配置的 SLA，該端口預計在週一至週五每天接收 1000 個檔案。如果尚未收到 1000 個檔案，則會在時間段結束前 1 小時傳送風險通知。
    </p>
    <img src="/public/images/sla_defined.png" alt="SLA Configuration Example" />
    <Note>
      如果有必要，可以關閉 SLA 通知。這在維護視窗期間非常有用。點選導覽列上的 <strong>設定</strong>，然後跳轉到 <strong>通知 &gt; 通用通知</strong>。點選平板和鉛筆圖示進行編輯，並取消勾選 <strong>SLA 通知</strong> 設定。
    </Note>
  </>;

export const AlertsTab = ({siteNameShort = "知行之桥"}) => <>
    <p><em>與配置通知相關的設定。</em></p>
    <p>
      在執行服務級別協議 (SLA) 之前，需要設定電子郵件通知以接收通知。預設情況下，{siteNameShort} 使用 <a href="/26.3/self-hosted/zh/getting-started/administration/settings/alerts">通知</a> 索引標籤上的全域設定。要為此端口使用其他設定，請啟用 <strong>覆蓋全域設定</strong>。
    </p>
    <p>
      預設情況下，錯誤通知處於啟用狀態，這意味著每當出現錯誤時都會傳送電子郵件。要關閉錯誤通知，請取消選中 <strong>啟用</strong> 核取方塊。
    </p>
    <p>
      輸入 <strong>主題</strong>（必填）。勾選<strong>允許在主題中使用 ArcScript</strong>，即可在<strong>主題</strong>欄位中使用 ArcScript。選中後會顯示 <strong>ArcScript 編輯器</strong>按鈕（<img src="/public/images/rest_arcscript_editor.png" alt="ArcScript 編輯器按鈕" style={{
  display: 'inline',
  verticalAlign: 'middle',
  margin: 0
}} />）。
    </p>
    <p>
      （可選）輸入以逗號分隔的<strong>收件人</strong>電子郵件地址清單。
    </p>
  </>;

export const MiscConnector = () => <>
    <p><em>特殊設定適用於特定用例。</em></p>
    <table>
      <thead>
        <tr>
          <th>設定</th>
          <th>描述</th>
        </tr>
      </thead>
      <tbody>
        <tr>
          <td><strong>其他設定</strong></td>
          <td>允許在以分號分隔的清單中配置隱藏的端口設定，例如 <code>setting1=value1;setting2=value2</code>。正常的端口用例和功能不需要使用這些設定。</td>
        </tr>
      </tbody>
    </table>
  </>;

export const Logging = () => <>
    <p><em>用於管理日誌建立和儲存的設定。</em></p>
    <table>
      <thead>
        <tr>
          <th>設定</th>
          <th>描述</th>
        </tr>
      </thead>
      <tbody>
        <tr>
          <td><strong>日誌級別</strong></td>
          <td>指定要記錄在端口日誌目錄中的資訊型別：
            <ul>
              <li><b>None</b> - 不建立任何日誌。</li>
              <li><b>Error</b> - 僅當端口遇到錯誤時才建立日誌。</li>
              <li><b>Warning</b> - 僅當端口發出警告時才建立日誌。</li>
              <li><b>Info</b> - 記錄工作流程的一般資訊，包括任何錯誤和警告（如果適用）。</li>
              <li><b>Debug</b> - 記錄成功和失敗工作流程的詳細偵錯資訊。</li>
              <li><b>Trace</b> - 記錄成功和失敗工作流程的詳細跟蹤資訊。</li>
            </ul>
            <strong>請注意：</strong><strong>Debug</strong> 和 <strong>Trace</strong> 級別的日誌可能會記錄敏感資訊，包括訊息內容和 SSL 憑證。儘管連線屬性（例如密碼）被遮蔽了，但在與您的組織外部共享它們之前，請檢視此級別的日誌以避免洩漏敏感資訊。</td>
        </tr>
        <tr>
          <td><strong>日誌資料夾結構</strong></td>
          <td>指示端口根據選定的時間間隔將日誌資料夾中的檔案分組。例如，<strong>Weekly</strong> 選項指示端口每週建立一個新的子資料夾，並將該周的所有日誌儲存在該資料夾中。空白設定告訴端口將所有日誌直接儲存在日誌資料夾中。對於處理許多交易的端口，使用子資料夾有助於保持日誌的有序性並提高效能。</td>
        </tr>
        <tr>
          <td><strong>保留訊息副本</strong></td>
          <td>指示端口在日誌目錄中儲存最新訊息副本的切換。請注意，端口每個子資料夾只保留一個訊息，並且端口在再次執行時會覆蓋以前儲存的訊息。</td>
        </tr>
      </tbody>
    </table>
  </>;

export const MacrosExamples = ({extraMacros = []}) => <>
    <p>
      某些宏（例如 %Ext% 和 %ShortDate%）不需要參數，但其他宏則需要。所有帶有參數的宏都使用以下語法：<code>%Macro:argument%</code>
    </p>

    <p>以下是帶有參數的宏的一些範例：</p>

    <ul>
      <li>%Header:headername%：其中 <code>headername</code> 是訊息上訊息頭的名稱。</li>
      <li>%Header:mycustomheader% 解析為輸入訊息上設定的 <code>mycustomheader</code> 訊息頭的值。</li>
      <li>%Header:ponum% 解析為輸入訊息上設定的 <code>ponum</code> 訊息頭的值。</li>
      <li>%RegexFilename:pattern%：其中 <code>pattern</code> 是規則運算式模式。例如，<code>%RegexFilename:^([\w][A-Za-z]+)%</code> 匹配並解析為檔名中的第一個單詞，並且不區分大小寫（<code>test_file.xml</code> 解析為 <code>test</code>）。</li>
      <li>%Vault:vaultitem%：其中 <code>vaultitem</code> 是 <a href="/26.3/self-hosted/zh/getting-started/administration/settings/global-settings-vault">vault</a> 中專案的名稱。例如，<code>%Vault:companyname%</code> 解析為儲存在保管庫中的 <code>companyname</code> 項的值。</li>
      <li>%DateFormat:format%：其中 <code>format</code> 是可接受的日期格式（有關詳細資訊，請參閱 <a href="/26.3/self-hosted/zh/scripting/value-formatters/date-formatters#sample-date-formats">範例日期格式</a>）。例如，<code>%DateFormat:yyyy-MM-dd-HH-mm-ss-fff%</code> 解析為檔案上的日期和時間戳。</li>
      {extraMacros.filter(item => item.example).map(item => <li key={`ex-${item.name}`}>{item.example}</li>)}
    </ul>

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

    <ul>
      <li>將多個宏組合在一個檔名中：<code>%DateFormat:yyyy-MM-dd-HH-mm-ss-fff%%EXT%</code></li>
      <li>包括宏之外的文字：<code>MyFile_%DateFormat:yyyy-MM-dd-HH-mm-ss-fff%</code></li>
      <li>在宏中包含文字：<code>%DateFormat:'DateProcessed-'yyyy-MM-dd_'TimeProcessed-'HH-mm-ss%</code></li>
    </ul>
  </>;

export const MacrosTable = ({siteName = "知行之桥", extraMacros = []}) => <>
    <p>
      在檔案命名策略中使用宏可以提高組織效率和對資料的上下文理解。透過將宏合併到檔名中，可以動態地包含相關資訊，例如識別碼、時間戳和訊息頭資訊，從而為每個檔案提供有價值的上下文。這有助於確保檔名反映對組織重要的詳細資訊。
    </p>

    <p>{siteName} 支援這些宏，它們都使用以下語法：<code>%Macro%</code>。</p>

    <table>
      <thead>
        <tr><th>宏</th><th>描述</th></tr>
      </thead>
      <tbody>
        <tr><td>ConnectorID</td><td>替換為端口的 ConnectorID。</td></tr>
        <tr><td>ConnectorName</td><td>替換為端口名稱。可用於在檔名或路徑中包含連線名稱，例如按生成備份檔案的資料庫連線標記檔案。</td></tr>
        <tr><td>Ext</td><td>替換為端口當前正在處理的檔案的副檔名。</td></tr>
        <tr><td>Filename</td><td>替換為端口當前正在處理的檔案的檔名（包括副檔名）。</td></tr>
        <tr><td>FilenameNoExt</td><td>替換為端口當前正在處理的檔案的檔名（不帶副檔名）。</td></tr>
        <tr><td>MessageId</td><td>計算端口輸出的訊息的 MessageId。</td></tr>
        <tr><td>RegexFilename:<em>pattern</em></td><td>將規則運算式模式應用於端口當前正在處理的檔案的檔名。</td></tr>
        <tr><td>Header:<em>headername</em></td><td>替換為端口正在處理的當前訊息的目標訊息頭（<code>headername</code>）的值。</td></tr>
        <tr><td>LongDate</td><td>以常規格式計算系統的當前日期時間（例如，2024 年 1 月 24 日星期三）。</td></tr>
        <tr><td>ShortDate</td><td>以 yyyy-MM-dd 格式計算系統的當前日期時間（例如 2024-01-24）。</td></tr>
        <tr><td>DateFormat:<em>format</em></td><td>以指定格式（<code>format</code>）計算系統的當前日期時間。有關可用的日期時間格式，請參閱 <a href="/26.3/self-hosted/zh/scripting/value-formatters/date-formatters#date-formats-with-literal-characters">範例日期格式</a>。</td></tr>
        <tr><td>Vault:<em>vaultitem</em></td><td>計算指定保管庫專案的值。</td></tr>
        {extraMacros.map(item => <tr key={item.name}>
            <td>{item.name}</td>
            <td>{item.description}</td>
          </tr>)}
      </tbody>
    </table>
  </>;

export const Performance = () => <>
    <p><em>與端口資源分配相關的設定。</em></p>
    <table>
      <thead>
        <tr>
          <th>設定</th>
          <th>描述</th>
        </tr>
      </thead>
      <tbody>
        <tr>
          <td><strong>最大工作執行緒數</strong></td>
          <td>此端口上處理檔案時從執行緒池中消耗的最大工作執行緒數。如果設定，則會覆蓋 <a href="/26.3/self-hosted/zh/getting-started/administration/settings/advanced-settings">進階設定</a> 頁面的 <a href="/26.3/self-hosted/zh/getting-started/administration/settings/performance-settings">效能設定</a> 部分的預設設定。</td>
        </tr>
        <tr>
          <td><strong>最大檔案數</strong></td>
          <td>分配給端口的每個執行緒傳送的最大檔案數。如果設定，則會覆蓋 <a href="/26.3/self-hosted/zh/getting-started/administration/settings/advanced-settings">進階設定</a> 頁面的 <a href="/26.3/self-hosted/zh/getting-started/administration/settings/performance-settings">效能設定</a> 部分的預設設定。</td>
        </tr>
      </tbody>
    </table>
  </>;

export const siteNameShort = "知行之橋";

export const siteName = "知行之橋";

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 方法。請求正文可以在端口配置中靜態設定，也可以根據端口處理的檔案動態生成。

### 操作

<CommonActionType resource="request" />

## 端口配置

### 設定索引標籤

*與端口核心配置相關的設定。*

#### 配置

<NameDescription />

#### 進階設定

| 設定         | 說明                                                          |
| ---------- | ----------------------------------------------------------- |
| **本地檔案方案** | 為端口輸出的訊息分配檔名的方案。可以在檔名中使用宏，動態包含識別碼和時間戳等資訊。有關更多資訊，請參見[宏](#宏)。 |

### REST 詳情索引標籤

*與端口請求詳細資訊相關的設定。*

<img src="https://mintcdn.com/qiao/3lMD3uYuGJqErRlJ/public/images/rest_details_tab.png?fit=max&auto=format&n=3lMD3uYuGJqErRlJ&q=85&s=8c9d302150be4eea5bca5ae64915d6f3" width="700" data-path="public/images/rest_details_tab.png" />

| 設定                        | 說明                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
| ------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **REST 詳情**               | 選擇端口應執行的操作。（有關三個選項的詳細資訊，請參見[操作](#操作)。）                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
| **從 Swagger 匯入**          | 單擊 <img src="https://mintcdn.com/qiao/3lMD3uYuGJqErRlJ/public/images/rest_import_from_swagger.png?fit=max&auto=format&n=3lMD3uYuGJqErRlJ&q=85&s=0a70547b1c5e25c83af86642c5871b77" alt="從 Swagger 匯入" style={{display: 'inline', verticalAlign: 'middle', margin: 0}} width="23" height="25" data-path="public/images/rest_import_from_swagger.png" /> 圖示可直接從 Swagger URL 匯入 API 詳細資訊。                                                                                                                      |
| **測試**                    | 測試當前配置，而不建立傳送到工作流程下游的訊息或交易。單擊**測試**會開啟一個包含其他索引標籤的視窗（更多資訊請參見[測試請求配置](#測試請求配置)）。                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| **請求 URL**                | REST 請求的 HTTP 方法和目標 HTTP URL。可用方法選項包括：GET、POST、PUT、PATCH 和 DELETE。                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
| **允許在 URL 中使用 ArcScript** | 勾選此項可在發出查詢前對 URL 中的 ArcScript 運算式求值。選擇此項後，會顯示 **ArcScript 編輯器**按鈕（<img src="https://mintcdn.com/qiao/3lMD3uYuGJqErRlJ/public/images/rest_arcscript_editor.png?fit=max&auto=format&n=3lMD3uYuGJqErRlJ&q=85&s=78f62e626c10d2e9e87a70479a45d21b" alt="ArcScript 編輯器按鈕" style={{display: 'inline', verticalAlign: 'middle', margin: 0}} width="26" height="22" data-path="public/images/rest_arcscript_editor.png" />），使你能夠使用 ArcScript 構建動態請求 URL。詳情請參見[使用 ArcScript 編輯器構建請求 URL 和標頭](#使用-sitenameshortscript-編輯器構建請求-url-和標頭)。 |
| **正文型別**                  | 隨 REST 請求提供的正文內容類型。當 HTTP 方法為 GET 時不可見。有關每個選項的說明，請參見[正文](#正文)。                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| **內容類型**                  | 原始資料傳輸使用的內容類型。僅當**正文型別**設定為 `raw` 時可見。                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |

#### 查詢參數

使用此索引標籤向請求 URL 新增查詢參數。以名稱-值對形式提供參數，並可選擇新增說明。單擊**儲存**以使用參數更新 URL。

<img src="https://mintcdn.com/qiao/3lMD3uYuGJqErRlJ/public/images/rest_query_params.png?fit=max&auto=format&n=3lMD3uYuGJqErRlJ&q=85&s=39db57a8eaf82e809aae02501a384c87" width="700" data-path="public/images/rest_query_params.png" />

上圖包含兩組查詢參數。儲存端口後，`api.example.com` 請求 URL 會變為：`https://api.example.com/orders?status=pending&limit=50`

單擊右側的省略號可設定另外兩個選項：**批次編輯檢視**和**隱藏說明列**。

#### 認證

使用此索引標籤配置 API 請求的身分驗證憑據。

| 設定            | 說明                                                                                                                                                                                       |
| ------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **憑據**        | 是否從先前配置的連線提供身分驗證憑據、建立新連線，或不帶身分驗證傳送請求。<br />**來自連線**：選擇此項，然後從下拉式清單中選擇你的**連線**。**注意**：單擊**連線**旁邊的加號可建立新連線。<br />**無憑據**：選擇此項可傳送不帶身分驗證的請求。此選項適用於公共 API，或透過[查詢參數](#查詢參數)或[標頭](#標頭)處理身分驗證的情況。 |
| **TLS 伺服器憑證** | 用於驗證 TLS 伺服器身份的公開金鑰憑證。你可以上傳憑證，留空以允許底層 OS/JVM 執行憑證驗證，或設定為 `Any Certificate` 以信任目標伺服器的身份。請謹慎使用 Any Certificate：憑證用於驗證你連線的是預期伺服器。                                                           |

#### 標頭

此索引標籤使你能夠新增要包含在傳出 REST 請求中的 HTTP 標頭清單。標頭也以名稱-值對指定。更多資訊請參見[靜態請求](#靜態請求)和[動態請求](#動態請求)。單擊右側的省略號可存取另外三個選項：**批次編輯檢視**、**允許在標頭中使用 ArcScript** 和**顯示自動生成的標頭**。有關使用 ArcScript 編輯器的詳細資訊，請參見[使用 ArcScript 編輯器構建請求 URL 和標頭](#使用-sitenameshortscript-編輯器構建請求-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。                                                                   |

### 進階選項卡

#### 認證

<TlsClientAuthentication />

#### 進階設定

\_不屬於前述類別的設定。

| 設定                      | 說明                                                                                                                                       |
| ----------------------- | ---------------------------------------------------------------------------------------------------------------------------------------- |
| **分塊編碼**                | 傳送請求時是否使用 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 端口](../flows/designing-a-flow#interacting-with-the-local-file-system)管理本地檔案系統，而不是使用此設定。 |

#### 代理設定

<CommonProxySettings />

#### 日誌

<Logging />

#### 其他設定

<MiscConnector />

### 自動化索引標籤

#### 自動化設定

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

| 設定         | 說明                                                                                                                                                                                                                                                                                                                          |
| ---------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **傳送**     | 指示端口在檔案準備就緒時自動傳送檔案的開關。                                                                                                                                                                                                                                                                                                      |
| **重試間隔**   | 端口在重試失敗傳送之前等待的間隔。                                                                                                                                                                                                                                                                                                           |
| **最大次數**   | 端口嘗試傳送訊息的次數。將此值設定為 *1* 會指示端口僅進行初始傳送嘗試而不重試。端口會在每次嘗試之間等待**重試間隔**指定的時長。                                                                                                                                                                                                                                                        |
| **接收**     | 指示端口按配置間隔自動發起 REST 請求的開關。                                                                                                                                                                                                                                                                                                   |
| **間隔**     | 端口發起配置的 REST 請求的間隔。下一個欄位取決於此處的選擇：<br />**每小時**：*小時後分鐘數*下拉功能表允許指定小時後多少分鐘處理接收檔案。<br />**每天**：顯示*時間*欄位，用於指定一天中的時間（UTC）來處理接收檔案。<br />**每週**：顯示兩個欄位。*日期*允許選擇處理的星期幾，*時間*允許指定處理接收檔案的時間（UTC）。<br />**每月**：顯示兩個欄位。*日期*允許選擇每月的日期，*時間*允許指定處理接收檔案的時間（UTC）。<br />**分鐘**：顯示*分鐘*欄位，用於指定處理間隔之間的分鐘數。<br />**高階**：五位 *Cron 運算式*欄位允許指定精確的處理間隔。 |
| **小時後分鐘數** | 小時計劃的分鐘偏移量。僅當**接收**設定為\_每小時\_時適用。例如，如果此值設定為 5，自動化服務會在 1:05、2:05、3:05 等時間傳送請求。                                                                                                                                                                                                                                               |

#### 效能

<Performance />

### 告警索引標籤

<AlertsTab />

### SLA 索引標籤

<SlasTab />

### 交易索引標籤

此索引標籤列出與端口關聯的所有訊息。使用搜尋欄查詢特定訊息，或單擊漏斗圖示應用篩選器。可以按時間、訊息方向和/或狀態進行篩選。

此索引標籤上的選項因端口的[操作型別](#操作)而異：

* 如果端口是 **Trigger**，請使用**接收檔案**按鈕啟動工作流程。
* 如果端口是 **Transform** 或 **Terminal**，請使用**上傳檔案**按鈕將檔案上傳到工作流程。

## 建立連線

與任何 REST 服務建立連線都需要有效的目標 URL。服務 URL 可以支援各種 HTTP 方法，你應根據特定 Web 服務操作或要檢索的資料集配置該方法。某些服務可能還需要身分驗證或一組自定義標頭才能使用該服務。

[認證](#認證)索引標籤的**憑據**部分使你能夠指定連線憑據。可從以下選項中選擇：

* **來自連線**：選擇先前配置的 {siteNameShort} 共享連線，或單擊**連線**欄位旁邊的加號以[建立連線](#建立連線)。
* **無憑據**適用於公共 API，或透過[查詢參數](#查詢參數)或[標頭](#標頭)處理身分驗證的情況。如果目標 URL 是 HTTPS URL，請將 **TLS 伺服器憑證**設定為標識伺服器的公開金鑰憑證。若要隱式信任目標端點，請將該欄位設定為 `Any Certificate`。

### 建立連線

若要建立新連線，請選擇**來自連線**，然後單擊**連線**欄位旁邊的加號。

* 輸入唯一的**連線名稱**。
* **型別**始終設定為 REST。
* 選擇你的**身分驗證方案**。詳情請參見[認證方式](#認證方式)。

### 認證方式

REST 端口支援多種身分驗證型別，每種型別都有自己的要求：

* Basic（純文字）、Digest（加密）和 NTLM 需要使用者名稱-密碼身分驗證。這些憑據會作為請求中的標頭提供給 REST 服務。

* OAuth 身分驗證需要在 REST 服務的 Web 門戶或開發控制檯中註冊應用。應用註冊中要包含的 **Callback URL** 會顯示在 {siteNameShort} UI 中。選擇適用於 REST 服務的 **Grant Type**，並根據 REST 服務 Web 門戶或開發控制檯中顯示的詳細資訊指定其餘設定。然後單擊**取得新的存取權杖**以取得與服務互動所需的權杖。檢索到初始權杖後，應用程式會在權杖即將過期時重新整理它們。

* Bearer Token 身分驗證需要來自服務 Web 門戶或開發控制檯的權杖。

* AWS Signature 身分驗證用於對 Amazon 進行身分驗證，需要配置 Amazon 提供的憑據：**Access Key**、**Secret Key** 等。

* API Key 身分驗證需要一個鍵值對，然後必須指定該鍵應作為[標頭](#標頭)還是作為[查詢參數](#查詢參數)新增。

## 測試請求配置

你可以隨時測試當前配置，而不建立傳送到工作流程下游的訊息或交易。單擊 **REST 詳情**索引標籤上的**測試**。下圖顯示了成功測試 Trigger 端口後的**回應正文**結果。

<img src="https://mintcdn.com/qiao/3lMD3uYuGJqErRlJ/public/images/rest_test_tab.png?fit=max&auto=format&n=3lMD3uYuGJqErRlJ&q=85&s=9ab18fafa328d0d96025a5289e012725" width="700" data-path="public/images/rest_test_tab.png" />

* **回應正文**：以伺服器傳回的格式顯示 REST 請求的輸出。
* **回應標頭**：顯示伺服器傳回回應中包含的回應標頭。
* **訊息標頭**：顯示測試輸出中包含的訊息標頭。
* **日誌**：顯示測試日誌。

Transform 和 Terminal 端口有一個**輸入**窗格，其中包含 **XML**、**標頭**和**日誌**索引標籤。

* 只有在請求正文中定義了 XML 欄位時，**XML** 索引標籤才會填充，如下圖所示。
* 如果勾選了**允許在 URL 中使用 ArcScript** 或**允許在標頭中使用 ArcScript**，請使用**標頭**索引標籤提供可能在指令碼上下文中使用的訊息標頭（有關這些選項的詳情，請參見[使用 ArcScript 編輯器構建請求 URL 和標頭](#使用-sitenameshortscript-編輯器構建請求-url-和標頭)）。如果你的請求配置了作為 `form-data` 或 `x-www-form-urlencoded` 正文元素的[標頭](#標頭)，標頭名稱會顯示在此處，你可以提供用於測試的值。
* **日誌**索引標籤包含上次測試的結果。

<img src="https://mintcdn.com/qiao/3lMD3uYuGJqErRlJ/public/images/rest_test_tab_transform.png?fit=max&auto=format&n=3lMD3uYuGJqErRlJ&q=85&s=9c20bd5f5c9b2c86f424b4c25699d9e1" width="700" data-path="public/images/rest_test_tab_transform.png" />

## 靜態請求

內容完全靜態的 REST 請求（例如使用 HTTP GET 方法的請求）不需要輸入檔案，因為請求內容完全在端口 UI 中配置。只需在**標頭**部分新增任何必要的名稱-值對作為自定義標頭，或在**正文**部分新增表單資料。

如果啟用**接收自動化**，可以按計劃自動傳送靜態請求。每個請求的回應會儲存在輸出資料夾中，或傳遞給工作流程中的下一個端口。

如果啟用**傳送自動化**，到達端口**交易**資料夾的檔案也會觸發靜態請求。輸入檔案的內容會被忽略，請求會根據 UI 中的配置傳送。

## 動態請求

REST 請求可以使用到達端口**交易**資料夾的檔案中的資料動態填充。

### 原始輸入資料

如果將請求的**正文型別**設定為 `raw`，輸入檔案的內容會作為 REST 請求正文傳送。

使用**內容類型**下拉式清單設定資料的特定內容類型。如果所需內容類型未列出，可以在**標頭**部分新增 *Content-Type* 標頭。

### 動態表單資料

如果將請求的**正文型別**設定為 `form-data` 或 `x-www-urlencoded`，端口會從輸入檔案中查詢特定值來填充請求。對於設定為 `XML` 的每個名稱-值對，端口會掃描輸入檔案，查詢與欄位名稱相同且使用特定 XML 結構的 XML 元素，如下所示：

```xml theme={null}
<Items>
  <FormData>
    <FieldName></FieldName>
  </FormData>
</Items>
```

為適配此結構，知行軟體強烈建議在工作流程中的 REST 端口前使用 XML Map 端口，如[下文](#使用-xml-map-構建動態範本)所述。

當端口找到與欄位名稱和所需 XML 結構匹配的元素時，該元素中的值會用作名稱-值對中的值。例如，如果正文中有名為 `CustomerID` 的動態欄位，並且輸入檔案包含如下所示的 XML，則 REST 端口會將 `CustomerID` 欄位的值設定為 12354。

```xml theme={null}
<Items>
  <FormData>
    <CustomerID>12354</CustomerID>
  </FormData>
</Items>
```

#### 使用 XML Map 構建動態範本

將 [XML Map](./xml-map/xml-map) 端口與 REST 端口結合使用，可以輕鬆從其他 XML 資料結構構建動態請求。XML Map 端口會將自定義 XML 結構轉換為 REST 端口期望的 XML 結構。

首先，為 REST 端口配置請求中應存在的一組動態（和靜態）**正文**欄位。接下來，在 {siteNameShort} 工作流程中將 XML Map 端口連線到 REST 端口，並儲存工作流程更改。這使 XML Map 端口能夠檢測 REST 端口期望在傳入輸入檔案中出現哪些欄位。

然後，在 XML Map 端口中，**目的檔案**下拉式清單會包含 REST 請求架構。選擇它作為目標，並將**來源檔案**設定為自定義 XML 結構。這會填充 XML Map 對映編輯器，你可以將需要包含在 REST 請求中的資料從源結構拖放到目標結構。對映完成後，XML Map 端口會自動將與來源檔案匹配的檔案轉換為有效的 REST 請求結構。

有關使用 XML Map 端口的更多資訊，請參見 [XML Map 端口文件](./xml-map/xml-map)。

#### 動態標頭

還可以對 ArcScript 中的運算式求值，以生成動態字串作為標頭值。有關詳情和範例，請參見[標頭](#標頭)。

## 使用 ArcScript 編輯器構建請求 URL 和標頭

可以使用如下所示的 ArcScript 編輯器構建請求 URL 和標頭。下圖顯示的是請求 URL 編輯器，但標頭值編輯器的工作方式相同。

<img src="https://mintcdn.com/qiao/3lMD3uYuGJqErRlJ/public/images/rest_arcscript_editor_pane.png?fit=max&auto=format&n=3lMD3uYuGJqErRlJ&q=85&s=db1a98aa07bec3af146b5ade823ba24a" width="600" data-path="public/images/rest_arcscript_editor_pane.png" />

在端口配置窗格的 [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]`

### 訊息標頭

訊息標頭幫助 {siteNameShort} 跟蹤資料在工作流程中的進度。所有已跟蹤標頭都會顯示在編輯器的**訊息標頭**索引標籤上，你可以在運算式中引用它們。

還可以使用編輯器中的**新增訊息標頭**欄位並提供現有標頭的名稱，在運算式中包含其他訊息標頭。這些標頭不必是已跟蹤標頭。

### 保管庫

使用 **Vault** 索引標籤可將[全域設定保管庫](../getting-started/administration/settings/global-settings-vault)中的專案新增到運算式。如果你在整個工作流程的不同位置重複使用某些值，這會很有用。你可以在保管庫中定義這些值，然後在運算式開頭引用它們。請注意，如果希望對映使用保管庫中專案的\_值\_，需要在方括號內引用它；否則編輯器會將專案\_名稱\_解釋為字面量。

### 格式化器

格式化器支援操作不同 xpath 傳回的值。在運算式中，格式化器用管道字元 (|) 分隔，並從左到右求值。例如：

`[xpath('City') | toupper | substring(0,3)]`

在此範例中，傳回 `City` xpath 的值之前，所有字串字元都會轉換為大寫字元，並在結果中傳回前三個字元的子字串。例如，如果源文件有以下值：

`<City>Durham</City>`

結果運算式傳回以下內容：

`DUR`

格式化器列在**格式化器**索引標籤上。單擊清單中的格式化器可將其新增到運算式。

## 回應事件

可以在 REST 端口中使用回應事件與從伺服器接收的回應（包括正文、標頭、Cookie 等）互動，並豐富端口生成的輸出訊息。可以在 `Response` 事件中使用以下特殊專案。

* [\_cookies](../scripting/introduction-to-arcscript#http-cookies-_cookies)
* [\_message](../scripting/introduction-to-arcscript#message-_message)
* [\_request](../scripting/introduction-to-arcscript#http-request-_request)
* [\_response](../scripting/introduction-to-arcscript#http-response-_response)

### 回應事件 Example

此指令碼讀取從 REST 呼叫接收的 JSON 回應，解析出 JSON 中包含的存取權杖，並將其作為標頭新增到 REST 端口建立的輸出訊息上：

```xml theme={null}
<arc:set attr="json.text" value="[_response.body]" />
<arc:set attr="json.map:access_token" value="/json/args/token" />
<arc:call op="jsonDOMGet" item="json">
  <arc:set attr="_message.header:access_token" value="[json.access_token | def('Token not found!')]"/>
</arc:call>
```

以下步驟詳細說明了發生的情況：

1 透過 `_response.body` 存取伺服器傳送回知行之橋中 REST 端口的回應正文，並將其設定為 jsonDOMGet 操作的 text 屬性。jsonDOMGet 的其他屬性也會被填充，例如 `map` 屬性，其中包含回應正文中所需權杖的 jsonpath。

2 呼叫 jsonDOMGet 操作。如果在回應 JSON 正文中找到權杖，則會透過 `_message.header:access_token` 語法將其作為訊息標頭新增到 REST 端口的輸出訊息。如果未找到權杖，則 `access_token` 標頭的值會設定為靜態字串：*Token not found!*。

在 {siteNameShort} 中檢視來自 REST 端口的訊息的輸出訊息詳細資訊時，結果如下所示：

<img src="https://mintcdn.com/qiao/3lMD3uYuGJqErRlJ/public/images/rest_response_event.png?fit=max&auto=format&n=3lMD3uYuGJqErRlJ&q=85&s=6998cd11f75e4d2ebe59acbe894f46ef" width="700" data-path="public/images/rest_response_event.png" />

當你需要從傳送請求後伺服器傳回的原始 JSON 回應正文中解析資料時，這類指令碼很有用。隨後可以在工作流程的後續端口中讀取和使用該標頭。

<Tip>如果伺服器使用 XML 回應，可以使用 xmlDOMget 實現相同結果。</Tip>

## 宏

<MacrosTable />

### 範例

<MacrosExamples />