从 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 必须由 CXone 授权。 授权后的 DLL 将保存在 CXone系统 文件存储空间的根目录中。

使用 SOAP Web 服务需要 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")