从 SNIPPET 操作进行 API 调用

您可以从 SNIPPET 操作进行 REST 或 SOAP API 调用。这是在 Studio 脚本中进行 API 调用的支持的方法之一。如果您正在连接到 SOAP Web 服务或者您的 API 调用包含 XML，则必须使用此方法。但是，进行 RESTful API 调用或包含 JSON 的调用的首选方法是使用 REST API 操作。

除了在响应中看到 HTTP 状态代码之外，您还可能会看到 -1 代码。这是一个指示响应已发生错误的内部代码。

使用 SNIPPET 操作连接到 RESTful Web 服务

您可以在 Snippet 操作中使用 Studio 脚本通过 REST 代理与 RESTful API 连接。您可以使用 GetRestProxy() 函数访问该服务。REST 代理允许脚本与远程 Web 服务器交互。它提供了一些可用于执行此操作的属性和函数。本节稍后部分将介绍这些属性和功能。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：application/json
    • 1：text/xmll
    • 2：application/json (忽略应答正文)
    • 3：text/xml（忽略应答正文）
      • "JSON" - application/json
      • "XML - text/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 编辑器窗口中，添加一条 USES 语句，命名生成并存储在您业务单位文件存储空间中的代理 DLL 文件。

以下代码片段是通过 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 时，您使用的 XML 不能包含双引号。您可以使用以下任一替代方案：

  • 将每个双引号替换为 {char(34)}，这会将双引号字符直接插入到字符串中。在本节后面第二步的第一个示例中将说明此选项。
  • 将每个双引号替换为单引号 (')。这在 XML 和 SNIPPET 操作中是可以接受的。在本节后面第二步的第二个示例中将说明此选项。

您只需替换 XML 中出现的双引号即可。代码片段中的变量赋值仍必须用双引号引起来。

  1. 创建 REST 代理，分配 ContentType 标头（因为您正在连接的 Web 服务需要它）以及公共 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")