從 SNIPPET 動作中進行 API 調用

您可以透過 SNIPPET 動作進行 REST 或 SOAP API 調用。這是在Studio指令碼中進行 API 調用的受支援的方法之一。如果您要連接到 SOAP Web 服務或您的 API 調用包含 XML，則您必須使用此方法。但是，進行 RESTful API 調用或進行包含 JSON 的調用的首選方法是使用 REST API 動作。

除了在回應中看到 HTTP 狀態代碼之外，您還可能會看到-1 代碼。這是一個內部代碼，用於指示回應發生錯誤。

使用 SNIPPET 動作連接至 RESTful Web 服務

您可以使用 Studio 指令碼透過 Snippet 動作中的 REST 代理連接 RESTful API。您可以使用GetRestProxy()功能存取該服務。REST 客服專員允許您的指令碼與遠端網路服務器互動。它提供了一些屬性和函數，您可以使用這些屬性和函數進行互動。本節稍後將介紹這些屬性和功能。CXone平台允許 REST API 傳回最多 32 KB 的資料。此限制是在平台層級施加，並且嚴格執行。

REST 客服專員需要使用動態資料物件。動態資料類型允許您的指令碼處理 XML 和 JSON 格式的回應。動態資料物件可以接收這些格式的資料並允許讀取。您還可以動態建立可轉換為 XML 或 JSON 的物件。使用 RESTful API 時，這些能力是必要的。

要使用 REST 客服專員，請在指令碼中新增Snippet動作並打開Snippet editor 視窗。使用以下語法調用GetRESTProxy()函數：

ASSIGN proxy = GetRESTProxy() 
 proxy.<property | function>([parameters])

對於<property | function>，請從以下各節所述的屬性和函數中進行選擇。

屬性

屬性 詳細資料
StatusCode

儲存調用 MakeRestRequest() 後的 HTTP 狀態代碼。此屬性不可修改。如果函數失敗，則不再保留狀態代碼。
StatusDescription 儲存調用 MakeRestRequest() 後的 HTTP 狀態描述。此屬性不可修改。
ContentType

允許您覆寫預設的內容類型標頭。預設為 application/x-www-form-urlencoded。

根據您正在進行的調用，您可能需要更改標頭。例如，如果您要傳送 JSON，則應將其變更為 application/json。您必須修改此屬性。
ProxyTimeoutSeconds 允許您更改請求逾時。預設為 10 秒。您必須修改此屬性。

函數

下表提供了連接 RESTful API 時可用的函數資訊。還有其他 REST 客服專員函數允許您對字串進行編碼和雜湊。

函數 詳細資料
MakeRestRequest(p1, p2, p3, p4)

向指定 URL 執行 HTTP 請求，其中：

  • P1：請求的 URL；字串
  • P2：API 調用的有效負載；字串
  • P3：接受標頭和回應剖析器選擇器；數字或字串：
    • 0：應用程式/json
    • 1：文字/xml
    • 2：應用程式/json（忽略回應正文）
    • 3：文字/xml（忽略回應正文）
      • 「JSON」 -應用程式/json
      • 「XML」 - 文字/xml
  • P4：REST API 動詞；字串
AddHeader 向 HTTP 請求新增自訂標頭。
ClearHeaders 清除使用 AddHeader 新增的任何自訂標題。

範例

ASSIGN proxy = GetRESTProxy()
ASSIGN proxy.ContentType = "application/json"
ASSIGN url = "https://catfact.ninja/fact"
ASSIGN verb = "GET"
ASSIGN result = proxy.MakeRestRequest(url,payload,'JSON',verb)

 

ASSIGN restProxy=GetRESTProxy()

restProxy.AddHeader("x-api-key", "qwer") //Assigning incorrect header for demonstration purposes
restProxy.ClearHeaders()
restProxy.AddHeader("x-api-key", "asdf")
ASSIGN restProxy.ProxyTimeoutSeconds = "2"
ASSIGN restProxy.ContentType = "application/json"

ASSIGN uri = "http://postman-echo.com/post"

DYNAMIC beowulfCharacteristics
ASSIGN beowulfCharacteristics.name = "Beowulf"
ASSIGN beowulfCharacteristics.occupation= "Hero" 
ASSIGN beowulfCharacteristics.foe = "Grendel"
ASSIGN payloadJSON = "{beowulfCharacteristics.asJSON()}

使用 SNIPPET 動作連接至 SOAP Web 服務

您可以透過 Studio 指令碼使用基於 SOAP 的 Web 服務。這需要將 WSDL 或代理 DLL 匯入Studio。匯入的 DLL 必須由 NICE CXone 授權。授權 DLL 後，它會儲存在 CXone系統 的檔案儲存根目錄中。

使用 SOAP Web 服務需要 NICE CXone 的幫助。詳細資訊，請聯絡您的 CXone 客戶代表。

要在 Studio 指令碼中使用基於 SOAP 的 Web 服務時，必須建立一個 Snippet。在指令碼中新增一個 Snippet 動作。在Snippet編輯器視窗中，新增一條 USES 語句，此語句用於命名代理 DLL 檔案，此檔案是您產生並儲存在業務單元的檔案儲存中。

以下 Snippet 是透過 Studio 指令碼使用基於 SOAP 的 Web 服務：

USES "sf.dll"
cStart="{now}"
sforce=new SforceService()
session=new SessionHeader()
loginResult=sforce.login("demo@nice.com",password6")
sforce.sessionheadervalue=session
session.sessionid=loginResult.sessionid
sforce.url=loginresult.serverUrl

t=new Task()
t.ActivityDate=#"8/20/2050"
t.Description="Call placed by {first }{Last}."
t.Subject="Call @{cStart}"
t.Status="Completed"
t.CallType="Outbound"
t.OwnerId=SF_Agent_ID
t.ReminderDateTime="{cStart}"

SWITCH Type
{
   CASE "CON" { t.WhoId=SF_Obj_ID }
   CASE "LEA" { t.WhoId=SF_Obj_ID }
   CASE "ACC" { t.WhatId=SF_Obj_ID }
   CASE "OPP" { t.WhatId=SF_Obj_ID }
   CASE "CAS" { t.WhatId=SF_Obj_ID }
}
SaveResult=sforce.create(t)

使用 REST 包裝器進行 SOAP 調用

此選項可讓您使用 REST API 方法來調用基於 SOAP 的 Web 服務。每個 Web 服務的回應方式都不同，具體取決於其建構方式。您可能需要修改範例程式碼才能與您正在調用的服務搭配使用。

在SNIPPET 動作中使用時，您使用的 XML 不能包含雙引號。您可以使用以下任一替代方案：

  • 將每個雙引號替換為{char(34)}，這會將雙引號字元直接插入字串中。此選項將在本節後面的第二步的第一個範例中進行說明。
  • 將每個雙引號替換為單引號 (')。這在 XML 和 SNIPPET 動作中是可以接受的。此選項將在本節後面的第二步中的第二個範例中進行說明。

您只需替換 XML 中顯示的雙引號即可。snippet 程式碼中的變數賦值仍必須用雙引號引起來。

  1. 建立 REST 代理，指派ContentType標頭（您要連接的 web 服務需要此標頭）以及公共網路服務 URL：

    ASSIGN RestProxy = GetRESTProxy() 
ASSIGN RestProxy.ContentType = "text/xml; charset=utf-8"
ASSIGN URL = "https://localhost:9031/ssodir/services/

    SSODirectoryService" //Assign the public Webservice UR

  2. 建立 SOAP 信封，該信封採用 XML 格式，用於對所有必需的參數進行編碼。您可以透過兩種方式操作：

    • 分開每一行。此選項更容易閱讀。

    • 將所有內容連接在一行中。

    此步驟中包含兩個選項的範例。

    此範例顯示將信封分成幾行。此外，此範例顯示雙引號替換為 {char(34)}。

    //Sample Payload:
ASSIGN Payload = ""
ASSIGN Payload = "{Payload}<?xml version={char(34)}1.0{char(34)} encoding={char(34)}UTF-8{char(34)}?>
ASSIGN Payload = "{Payload}<soapenv:Envelope"
ASSIGN Payload = "{Payload}	xmlns:soapenv={char(34)}http://schemas.xmlsoap.org/soap/envelope/{char(34)}"
ASSIGN Payload = "{Payload}	xmlns:xsd={char(34)}http://www.w3.org/2001/XMLSchema{char(34)}"
ASSIGN Payload = "{Payload}	xmlns:xsi={char(34)}http://www.w3.org/2001/XMLSchema-instance{char(34)}>"
ASSIGN Payload = "{Payload}<soapenv:Body>"
ASSIGN Payload = "{Payload}<ns1:getIDPList"
ASSIGN Payload = "{Payload}        soapenv:encodingStyle="
ASSIGN Payload = "{Payload}	           {char(34)}http://schemas.xmlsoap.org/soap/encoding/{char(34)} ""
ASSIGN Payload = "{Payload}xmlns:ns1="
ASSIGN Payload = "{Payload}            {char(34)}https://localhost:9031/ssodir/services/"
ASSIGN Payload = "{Payload}                 SSODirectoryService{char(34)}/>"
ASSIGN Payload = "{Payload}</soapenv:Body>"
ASSIGN Payload = "{Payload}</soapenv:Envelope>"

    以下範例顯示了連接在一行中的信封程式碼。在此範例中，雙引號已替換為單引號。

    //Sample Payload:
ASSIGN Payload = "<?xml version='1.0' encoding='UTF-8'?><soapenv:Envelope xmlns:soapenv='http://schemas.xmlsoap.org/soap/envelope/' xmlns:xsd='http://www.w3.org/2001/XMLSchema' xmlns:xsi='http://www.w3.org/2001/XMLSchema-instance'><soapenv:Body><ns1:getIDPList soapenv:encodingStyle='http://schemas.xmlsoap.org/soap/encoding/' xmlns:ns1='https://localhost:9031/ssodir/services/SSODirectoryService'/> </soapenv:Body></soapenv:Envelope>"

  3. 執行 REST 請求。以下範例作為 POST 執行。

    Result = RestProxy.MakeRestRequest(URL,Payload,1,"POST")