Realizar Llamadas a la API desde una Acción SNIPPET

Puede realizar Llamadas a la API REST o SOAP desde una acción SNIPPET. Este es uno de los métodos admitidos para realizar Llamadas a la API en scripts de Studio.

Este no es el método recomendado para realizar llamadas REST, ya que tiene el potencial de ralentizar el manejo de contactos y causar graves problemas de rendimiento en la plataforma. Use en su lugar uno de estos métodos preferidos:

  • Integration Hub: Esta es la opción más segura y garantiza que sus credenciales de cliente no se almacenen en texto sin formato.
  • Acción API REST: Usar la REST API acción es la alternativa recomendada si no está usando Integration Hub.

Sin embargo, si se está conectando a un servicio web SOAP o si sus Llamadas a la API incluyen XML, realizar llamadas desde SNIPPET es el método que debe usar. Si debe usar SNIPPET, revise las recomendaciones sobre cómo realizar estas Llamadas a la API de manera más segura.

Además de ver códigos de estado HTTP en las respuestas, es posible que vea un código -1. Este es un código interno que indica que se ha producido un error con la respuesta.

Precaución

Building API calls within a snippet is not recommended. It may lead to serious performance issues that impact contact handling and negatively impact your tenant. For a more secure and reliable experience, use one of the following preferred methods.

There are two cases where making calls from SNIPPET is the method you must use: if you're connecting to a SOAP web service or if your API calls include XML. If you must use SNIPPET for API calls: 

  • Limit timeouts in your API calls. A general recommendation is that timeouts be no more than two seconds. The default timeouts may be longer, so always verify the timeouts to ensure that they do not exceed this maximum. If you find that longer timeouts are required, adjust your web service if possible to improve its response times.
  • Be extremely careful with loop logic. The combination of loops and long timeouts compound the potential impact on your system.

  • The maximum response size in NiCE CXone is 32 KB. The limit is strictly enforced to prevent cluster instability and outages. Studio enforces this limit when saving the script, but Desktop Studio does not. If you can, use the REST API actionaction or Integration Hub instead of the SNIPPET action to make API calls. They have the same limit, but can handle a heavier load. If you must use the SNIPPET action, follow these tips to reduce the size of the returned data: 

    • Filter the data in the API response: For example, if you're using the NiCE reporting API to get contacts, you can filter the results by the startDate and endDate of the contact. This API call also allows you to return and limit a top count of items. Refer to the API documentation that came with your script integration to determine what filtering you can use.

    • Update the API request to return only the data you need: For example, if you're using the NiCE reporting API to get contacts, you can use the contactId or agentId fields to return only relevant data. Refer to the API documentation that came with your script integration to determine what data limits you can use.

    • Build middleware: If you cannot do either of the previous options, build middleware that does filtering based on custom criteria you define. If you do this, ensure that your middleware does not add latency to the call.

Conectarse a Servicios web RESTful con una Acción SNIPPET

 

Puede usar scripts de Studio para conectarse con API RESTful mediante el proxy REST en una Acción Snippet acción. Puede acceder a este servicio con la función GetRestProxy(). El proxy REST permite que sus scripts interactúen con servidores web remotos. Proporciona algunas propiedades y funciones que puede usar para hacerlo. Las propiedades y funciones se describen más adelante en esta sección. La plataforma de NiCE CXone permite que las API REST devuelvan hasta 32 KB de datos. Esta limitación se impone a nivel de la plataforma y se aplica estrictamente.

El proxy REST requiere el uso de objetos de datos dinámicos. El tipo de datos dinámicos permite que sus scripts trabajen con respuestas formateadas en XML y JSON. Los objetos de Datos dinámicos pueden recibir datos en estos formatos y permitir que se lean. También puede crear objetos dinámicamente que se puedan convertir en XML o JSON. Estas capacidades son necesarias cuando se usan API RESTful.

Para usar el proxy REST, agregue una acción Snippet a su script y abra la ventana del editor Snippet. Llame a la función GetRESTProxy() con la siguiente sintaxis:

ASSIGN proxy = GetRESTProxy() 

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

Para <property | function>, elija entre las propiedades y funciones que se describen en las siguientes secciones.

Propiedades

Propiedad Detalles
Código de estado

Contiene el código de estado HTTP después de una llamada a MakeRestRequest(). Esta propiedad no se puede modificar. Si la función falla, ya no contiene el código de estado.

Descripción de la Situación Contiene la descripción del estado HTTP después de una llamada a MakeRestRequest(). Esta propiedad no se puede modificar.
tipo de contenido

Le permite anular el encabezado de tipo de contenido predeterminado. El valor predeterminado es application/x-www-form-urlencoded.

Según la llamada que esté realizando, es posible que deba cambiar el encabezado. Por ejemplo, si está enviando JSON, debe cambiarlo a application/json. Debe modificar esta propiedad.

ProxyTimeoutSeconds Permite cambiar el tiempo límite de solicitud. El valor predeterminado es 10 segundos. Debe modificar esta propiedad.

Funciones

La siguiente tabla proporciona información sobre las funciones disponibles para usar al conectarse a API RESTful. Hay funciones de proxy de REST adicionales que le permiten codificar y aplicar hash a cadenas.

Función Detalles
MakeRestRequest(p1, p2, p3, p4)

Realiza una solicitud HTTP a la URL designada, donde:

  • P1: URL de la solicitud, Cadena de caracteres
  • P2: Carga útil para la Llamada a la API; Cadena de caracteres
  • P3: Accept header and response parser selector; Numeric or String:
    • 0: aplicación / json
    • 1: texto/xml
    • 2: aplicación/json (ignorar cuerpo de la respuesta)
    • 3: text/xml (ignore response body)
      • "JSON" - aplicación/json
      • "XML - texto/xml
  • P4: verbo API REST; Cadena de caracteres
AddHeader Agrega un encabezado personalizado a la solicitud HTTP.
ClearHeaders Borra todos los encabezados personalizados agregados con AddHeader.
currentUnixTimestamp()

Returns the current time as a Unix timestamp. Only for use with getRESTProxy(). Obtenga más información sobre esta función en la página de ayuda Funciones integradas.

Ejemplos de

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()}"

Conectarse a Servicios web SOAP mediante una Acción SNIPPET

Puede usar servicios web basados en SOAP con los scripts de Studio. Esto requiere que importe un WSDL o una DLL de proxy en Studio. La DLL importada debe estar autorizada por NiCE CXone. Después de autorizar la DLL, se guarda en la raíz del almacenamiento de archivos de sistema de NiCE CXone.

El uso de servicios web SOAP requiere la ayuda de NiCE CXone. Comuníquese con su representante de cuenta para obtener más información.

Cuando desee utilizar un servicio web basado en SOAP en un script de Studio, debe crear un snippet. Agregue una Snippet acción a su script. En la ventana del editor de Snippet, agregue una USES declaración que nombre el archivo DLL de proxy que generó y almacenó en el almacenamiento de archivos de su unidad de negocio.

El siguiente snippet es un ejemplo del uso de un servicio web basado en SOAP con un script Studio:

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)

Haga una Llamada SOAP con un Envoltorio REST

Esta opción le permite utilizar metodologías de API REST para realizar llamadas a servicios web basados en SOAP. Cada servicio web responde de manera diferente según cómo esté creado. Es posible que deba modificar el código de ejemplo para que funcione con el servicio al que está llamando.

El XML que utilice no puede incluir comillas dobles cuando lo use en una SNIPPET acción. Puede utilizar cualquiera de las siguientes alternativas:

  • Reemplace cada comilla doble por {char(34)}, lo que inserta un caractere de comilla doble directamente en la cadena. Esta opción se ilustra en el primer ejemplo en el segundo paso de esta sección.
  • Reemplace cada comilla doble por una comilla simple ( ' ). Esto es aceptable en XML y en acciones SNIPPET. Esta opción se ilustra en el segundo ejemplo en el segundo paso de esta sección.

Solo necesita reemplazar las comillas dobles que aparecen en el XML. Las asignaciones de variables en el código del snippet deben contener comillas dobles.

  1. Haga un proxy REST, asigne el encabezado ContentType según lo demande el servicio web que esté conectando, y la URL del servicio web público.

    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. Cree su envoltorio SOAP, que tiene formato XML para codificar todos los parámetros requeridos. Puede hacerlo de dos maneras:

    • Separe cada línea. Esta opción es más fácil de leer.

    • Concatene todo en una línea simple.

    En este paso, se incluyen ejemplos de ambas opciones.

    Este ejemplo muestra el envoltorio separado en líneas. Además, este ejemplo muestra las comillas dobles reemplazadas por {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>"

    El siguiente ejemplo muestra el código del envoltorio concatenado en una línea. En este ejemplo, las comillas dobles se han reemplazado por comillas simples.

    //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. Ejecute la solicitud REST. El siguiente ejemplo se está ejecutando como un POST.

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