Rest Api

This help page is for Desktop Studio.This information is also available for CXone Studio.

Rest Api Action icon

同步處理 RESTful API 調用。此動作使系統可處理更高的負載。該動作同時返回 API 調用的主體和標頭。這可以方便測試指令碼以及對其偵錯。

您可以測試包含 REST API 動作的指令碼並查看回應資訊。為此，使用以追蹤開始選項運行指令碼。

您還可以在SNIPPET動作中使用 GetRestProxy() 函數進行同步 RESTful API 調用。此選項無法像 REST API 動作那樣處理高負載，因此不是首選方法。

此動作是在 Studio 指令碼中連接到 Web 服務的受支援方法之一。

相依性

業務單元Closed 用於管理 CXone 環境的技術支援、計費和全域設定的高級組織分組層級對此動作有使用限制。此限制是為了避免其中一個動作影響另一個動作。平台 中的限制是：

  • 回應格式：僅支援 JSON 回應格式。
  • 失敗時重試：若在返回回應之前收到失敗訊息，則動作處理程式將自動嘗試兩次。
  • 逾時：在請求中指定逾時值。該值不能超過 90 秒。
  • 最大回應大小：最大回應大小為 32KB。這與現有Snippet 功能一致。如果達到此限制，您必須減少返回資料的大小。
  • 節流限制：節流限制由兩個參數定義：
    • 最大併行請求：預設情況下最多允許 100 個併行請求。此限制對所有 CXone 客戶都相同。這表示100 個並行請求比從 Snippet 動作進行 API 調用產生更高的輸送量。如果您需要超過 100 個併行請求，請與您的 CXone 客戶代表 聯絡來增加您業務單元的限制。需要特別核准。
    • 佇列計數：當請求超過此限制時，額外的請求進入處理佇列。一旦請求下降到限制以下，佇列請求將被處理。
  • 斷路器：如果您指定的 URL 被關閉或無法存取，您的請求會出現太多失敗。當發生這種情況時，CXone 將在一段時間內減少REST API動作中所有 URL 的請求執行。這樣可以讓指定的 URL 從失敗中恢復。限制如下：
    • 緩解時間或中斷的持續時間：如果達到失敗率，REST API 動作將在 30 秒內不執行任何請求。
    • 最小輸送量：100 次請求/秒。若您的業務單元沒有執行最小數量的請求，即使請求失敗，亦會繼續執行您的請求。
    • 失敗率：若 50% 的請求在 30 秒內失敗，則在接下來的 30 秒內不會再執行請求。30 秒是一個捲動時窗。

此動作的其他依賴條件是：

  • JSON 是唯一受支援的回應格式。此動作要求所有 JSON 都位於一行中。在此動作中使用 JSON 時，您可以：

  • 回應以 jtoken 物件傳回。您可以像在指令碼中使用動態資料物件一樣使用它們。
  • 回應包含回應的標頭和正文。它們也可能包含 HTTP 狀態碼。並非所有回應都會包含狀態碼。如果沒有錯誤，並且如果 REST API動作無法產生有效回應，或傳回的錯誤無法解析為有效回應，則不包含任何狀態。
  • 您可以在指令碼中使用多個 REST API 動作，但這些動作不能同時引用相同的物件。

輸入屬性

這些屬性定義了動作執行時使用的資料。

屬性

描述

標題

輸入在指令碼中唯一標識此操作的短語。標題出現在指令碼畫布上的動作圖示下。The default is the action name.

Verb

支援 GET、PUT、POST、DELETE 和 PATCH 等基本的 REST 動作。
Parameters

允許您指定查詢參數或發布任何資料。許多類型的 JSON 都是可接受的，例如 Jobject、Jarray 或 Jtoken。
Headers

允許您新增自訂標頭以允許客戶驗證，例如不記名權杖。您可以在此欄位中使用 JSON。

重要提示若自訂 URL 端點需要不同的標頭，則必須在此屬性中指定。為了與現有的 Snippet 動作保持功能同位檢查，CXone 新增以下標頭：

{"Accept":"application/json", "Content-Type" :"application/x-www-form-urlencoded"}

Command

目前唯一的選項是MakeRestRequest。此功能與在 Snippet 動作中進行 REST API 調用時使用的 MakeRestRequest() 功能相同。

TimeOutInMilliSeconds

允許指定和遵守 REST 調用的逾時。必須小於 90 秒（90000 毫秒）。如果未指定超時，默認為 10 秒（10000 毫秒）。
Service Address

您希望動作調用的 REST API 的 URL。您可以使用具有此屬性的變數替換。

輸出屬性

這些屬性包含變數，用於儲存執行動作後返回的資料。當動作完成後，它們可供參考和使用。

屬性

描述

resultSet(out)

包含從服務位址中指定的 API 返回的任何資訊的變數。如果需要，您可以將此變數的內容原樣傳遞到標頭和參數中。回應會作為 Jtoken 物件傳回，但您可以將其聲明為動態物件並像使用指令碼中的其他動態物件一樣使用。

errorArgList(out)

動態資料物件，用於儲存有關發生的任何錯誤的資訊。發生錯誤時，該物件會儲存 HTTP 狀態代碼、狀態描述和訊息。當沒有錯誤時，該物件為空。

HTTP 狀態碼和描述僅在錯誤中傳回，才能正確解析為有效回應。這表示並非所有錯誤都會包含 HTTP 回應代碼。

結果分支條件

結果分支條件允許您在指令碼中建立分支，以處理執行動作時的不同結果。

條件

描述
Throttle

在短時間內執行過多請求時所採用的路徑。如需更多詳細資料，請參見下面的限制。
InvalidInput

發現無效輸入或發生逾時錯誤時所採用的路徑。儲存指令碼時會驗證每個參數。
Failure

在執行請求的 NICE CXone 應用程式 中發生任何錯誤或異常時所採用的路徑。
Error

遙距客戶端點返回 http 錯誤碼時所採用的路徑。
Default

在 90 秒內未收到回應時所採用的路徑。
Success

動作完成且無錯誤而且任何 API 調用或資料返回均成功時採用的路徑（2xx 回應代碼）。