從 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")