Appels d’API à partir d’une action SNIPPET

Vous pouvez effectuer des appels d’API REST ou SOAP à partir d’une action SNIPPET. Il s’agit de l’une des méthodes prise en charge pour effectuer des appels d’API dans les scripts Studio. Si vous vous connectez à un service web SOAP ou si vos appels d’API incluent du XML, vous devez impérativement utiliser cette méthode. En revanche, pour effectuer des appels d’API RESTful ou des appels qui incluent du JSON, vous devez privilégier l’action REST API.

En plus des codes de statut HTTP dans les réponses, il est possible que vous voyiez un code -1. Il s’agit d’un code interne indiquant qu’une erreur est survenue dans la réponse.

Connexion à des services web RESTful avec une action SNIPPET

Vous pouvez utiliser des scripts Studio pour vous connecter aux API RESTful à l’aide du proxy REST dans une action Snippet. Vous pouvez accéder à ce service à l'aide de la fonction GetRestProxy(). Le proxy REST permet à vos scripts d'interagir avec des serveurs Web distants. Il fournit des propriétés et des fonctions que vous pouvez utiliser à cette fin. Les propriétés et fonctions sont décrites plus loin dans cette section. La plate-forme CXone permet aux API REST de renvoyer jusqu’à 32 Ko de données. Cette limite est imposée au niveau de plate-forme de manière stricte.

Le proxy REST nécessite l'utilisation d’objets de données dynamiques. Le type de données dynamiques permet à vos scripts de travailler avec des réponses formatées en XML et JSON. Les objets de données dynamiques peuvent recevoir des données dans ces formats et permettre leur lecture. Vous pouvez également créer de manière dynamique des objets pouvant être convertis en XML ou en JSON. Ces capacités sont nécessaires lors de l’utilisation des API RESTful.

Pour utiliser le proxy REST, ajoutez une action Snippet à votre script et ouvrez la fenêtre Snippet editor . Appelez la fonction GetRESTProxy() en utilisant la syntaxe suivante :

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

Pour <property | function>, choisissez parmi les propriétés et les fonctions décrites dans les sections suivantes.

Propriétés

Propriété Détails
StatusCode

Contient le code d'état HTTP suite à un appel à MakeRestRequest(). Cette propriété ne peut pas être modifiée. Si la fonction échoue, elle ne contient plus le code d’état.

StatusDescription Contient la description d’état HTTP suite à un appel à MakeRestRequest(). Cette propriété ne peut pas être modifiée.
ContentType

Permet de remplacer l’en-tête content-type par défaut. La valeur par défaut est application/x-www-form-urlencoded.

En fonction de l'appel que vous effectuez, il se peut que vous deviez modifier l'en-tête. Par exemple, si vous envoyez du JSON, vous devrez le remplacer par application/json. Vous devez modifier cette propriété.

ProxyTimeoutSeconds Permet de modifier le délai d'attente de la demande. La valeur par défaut est de 10 secondes. Vous devez modifier cette propriété.

Fonctions

Le tableau suivant fournit des informations sur les fonctions disponibles pour la connexion aux API RESTful. Il existe des fonctions proxy REST supplémentaires qui vous permettent de coder et de hacher des chaînes.

Fonction Détails
MakeRestRequest(p1, p2, p3, p4)

Effectue une demande HTTP vers l’URL désignée, avec :

  • P1 : URL de la demande ; chaîne
  • P2 : charge utile de l’appel d’API ; chaîne
  • P3: en-tête d’acceptation et sélecteur d’analyseur de réponse ; valeur numérique ou chaîne :
    • 0 :  application/json
    • 1 : texte/xml
    • 2 : application/json (ignorer le corps de la réponse)
    • 3 : texte/xml (ignorer le corps de la réponse)
      • "JSON" - application/json
      • "XML - texte/xml
  • P4 : verbe d’API REST API ; chaîne
AddHeader Ajoute un en-tête personnalisé à la requête HTTP.
ClearHeaders Efface tous les en-têtes personnalisés ajoutés avec AddHeader.

Exemples

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

Connexion à des services web SOAP avec une action SNIPPET

Vous pouvez utiliser des services web basés sur SOAP avec des scripts Studio. Pour ce faire, vous devez importer un WSDL ou une DLL proxy dans Studio. La DLL importée doit être autorisée par NICE CXone. Une fois que vous avez autorisé la DLL, celle-ci est enregistrée à la racine du stockage de fichiers de votre CXone système.

L'utilisation des services web SOAP nécessite l'assistance de NICE CXone. Contactez votre Représentant de compte CXone pour plus d'informations.

Lorsque vous voulez utiliser un service Web basé sur SOAP dans un script Studio, vous devez créer un snippet. Ajoutez une action Snippet au script. Dans l’éditeur Snippet, ajoutez une déclaration USES qui nomme le fichier DLL proxy que vous avez généré et stocké dans le stockage de fichiers de votre unité commerciale.

Le snippet suivant est un exemple d’utilisation d’un service web SOAP avec 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)
	

Appel SOAP avec un wrapper REST

Cette option permet d’utiliser les méthodologies d’API REST pour effectuer des appels à des services web SOAP. Chaque service web répond de manière différente, selon sa conception. Il peut être nécessaire de modifier l’exemple de code pour qu’il fonctionne avec le service que vous appelez.

Le code XML que vous utilisez ne peut pas inclure de doubles guillemets lorsque vous l’utilisez dans une action SNIPPET. Vous pouvez utiliser l’une des solutions suivantes :

  • Remplacez chaque guillemets doubles par {char(34)}, qui insère un caractère de guillemet double directement dans la chaîne. Cette solution est illustrée dans le premier exemple de la deuxième étape de cette section.
  • Remplacez chaque guillemet double par un guillemet simple ( ’ ). Ce caractère est acceptable en XML et dans les actions SNIPPET. Cette solution est illustrée dans le second exemple de la deuxième étape de cette section.

Vous devez uniquement remplacer les guillemets doubles qui figurent dans le XML. Les affectations de variables dans le code snippet doivent tout de même être placées entre guillemets doubles.

  1. Paramétrez un proxy REST, affectez l’en-tête ContentType comme le requiet le service web auquel vous vous connectez, ainsi que l’URL de service web public :

    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. Créez votre enveloppe SOAP, qui suit le format XML afin d’encoder tous les paramètres requis. Vous pouvez le faire de deux manières :

    • Séparez chaque ligne. Le résultat est plus facile à lire.

    • Imbriquez toutes les données sur une même ligne.

    Cette étape propose un exemple des deux solutions.

    Celui-ci présente l’enveloppe sur des lignes séparées. De plus, les guillemets doubles sont remplacés par {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>"

    L’exemple suivant montre le code d’enveloppe sur une seule ligne. Dans cet exemple, les guillemets doubles sont remplacés par des guillemets 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. Exécutez la demande REST. L’exemple suivant est exécuté en tant que POST.

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