Effectuer des Appels API à partir d'une action SNIPPET

Vous pouvez effectuer des Appels API REST ou SOAP depuis une action SNIPPET. Il s'agit de l'une des méthodes prises en charge pour effectuer des Appels API dans les scripts Studio.

Ce n'est pas la méthode recommandée pour effectuer des appels REST, car elle a le potentiel de rendre lente la gestion des contacts et de provoquer de graves problèmes de performance sur la plateforme. Utilisez plutôt une de ces méthodes privilégiées :

Integration Hub : Ceci est l'option la plus sécurisée et garantit que vos identifiants client ne sont pas stockés en texte brut.

Action de l'API REST : l'utilisation de l'action REST API est l'alternative recommandée si vous n'utilisez pas Integration Hub.

Toutefois, si vous vous connectez à un service Web SOAP ou si vos Appels API incluent du xml, l'utilisation de SNIPPET est la méthode que vous devez utiliser. Si vous devez utiliser SNIPPET, consultez les recommandations sur la façon d'effectuer ces Appels API de manière plus sûre.

En plus des codes d'état HTTP dans les réponses, vous pouvez voir un code -1. Il s’agit d’un code interne indiquant qu’une erreur est survenue dans la réponse.

Attention

Il n'est pas recommandé de créer des Appels API au sein d'un extrait. Cela peut entraîner de graves problèmes de performances ayant un impact sur la gestion des contacts et un impact négatif sur votre locataire. Pour une expérience plus sûre et plus fiable, utilisez l'une des méthodes privilégiées suivantes.

Il existe deux cas où l'émission d'appels à partir de SNIPPET est la méthode que vous devez utiliser : si vous vous connectez à un service Web SOAP ou si vos Appels API incluent du XML. Si vous devez utiliser SNIPPET pour des Appels API :

  • Limitez les délais d'attente dans vos Appels API. La recommandation générale est que les délais d'attente ne dépassent pas deux secondes. Les délais d'attente par défaut peuvent être plus longs ; vérifiez donc toujours les délais d'attente pour vous assurer qu'ils ne dépassent pas ce maximum. Si vous constatez que des délais d'attente plus longs sont nécessaires, ajustez votre service Web si possible afin d'améliorer ses temps de réponse.
  • Soyez extrêmement vigilant avec la logique des boucles. La combinaison de boucles et de délais d'expiration longs accroît l'impact potentiel sur votre système.
  • La taille de réponse maximale dans NiCE CXone est de 32 Ko. Cette limite est strictement appliquée afin d'éviter l'instabilité du cluster et les interruptions de service. Studio applique cette limite lors de l'enregistrement du script, mais Desktop Studio ne le fait pas. Si possible, utilisez l'REST API actionaction ou Integration Hub plutôt que l'action SNIPPET pour effectuer des Appels API. Elles ont la même limite, mais peuvent supporter une charge plus importante. Si vous devez utiliser l'action SNIPPET, suivez ces conseils pour réduire la taille des données renvoyées :

    • Filtrez les données dans la réponse de l'API : par exemple, si vous utilisez l'API de création de rapports NiCE pour obtenir des contacts, vous pouvez filtrer les résultats par startDate et endDate du contact. Cet Appel API vous permet également de renvoyer et de limiter le nombre d'éléments les plus hauts. Reportez-vous à la documentation API fournie avec l'intégration de votre script pour déterminer les filtres que vous pouvez utiliser.

    • Mettre à jour la demande API pour renvoyer uniquement les données dont vous avez besoin : par exemple, si vous utilisez l'API Reporting NiCE pour récupérer des contacts, vous pouvez utiliser les champs contactId ou agentId pour renvoyer uniquement les données pertinentes. Reportez-vous à la documentation de l’API associée à votre intégration de script pour déterminer les limites de données que vous pouvez utiliser.

    • Créer un middleware : Si vous ne pouvez pas effectuer l'une des options précédentes, créez un middleware qui applique des filtres en fonction de critères personnalisés que vous définissez. Si vous faites cela, assurez-vous que votre middleware n'ajoute pas de latence à l'appel.

Connexion aux services Web RESTful avec une Action Extrait

 

Vous pouvez utiliser des scripts Studio pour vous connecter à des API RESTful à l'aide du proxy REST dans un Extrait action.Vous pouvez accéder à ce service avec 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 plateforme NiCE CXone permet aux API REST de renvoyer jusqu'à 32 Ko de données. Cette limitation est imposée au niveau de la plateforme et est strictement appliquée.

The REST proxy requires the use of dynamic data objects. The dynamic data type allows your scripts to work with responses formatted in XML and JSON. Dynamic data objects can receive data in these formats and allow it to be read. You can also dynamically create objects that can be converted into either XML or JSON. These abilities are necessary when using RESTful APIs.

Pour utiliser le proxy REST, ajoutez une action Snippet à votre script, puis ouvrez la fenêtre de l'éditeur Snippet. 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
Code d'état

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

ÉtatDescription Contient la description du statut HTTP suivant 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 devez remplacer ceci 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 10 secondes. Vous devez modifier cette propriété.

Les fonctions

Le tableau suivant fournit des informations sur les fonctions disponibles pour la connexion aux API Reposant sur REST. Il existe des fonctions proxy REST supplémentaires qui vous permettent d'encoder et 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 pour l'Appel API ; chaîne
  • P3: Accept header and response parser selector; Numeric or String:
    • 0 : application / json
    • 1 : text/xml
    • 2 : application/json (ignorer le corps de la réponse)
    • 3: text/xml (ignore response body)
      • "JSON" - application/JSON
      • "XML - texte/xml
  • P4 : verbe d’API REST ; chaîne
AjouterEntête Ajoute un en-tête personnalisé à la requête HTTP.
ClearHeaders Efface toutes les en-têtes personnalisées ajoutées avec AddHeader.
currentUnixTimestamp()

Renvoie l'heure actuelle sous forme d'estampille temporelle Unix. Uniquement pour l'utilisation avec getRESTProxy(). En savoir plus sur cette fonction sur la page d'aide Built-In Functions.

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

Se connecter à des services Web SOAP avec une Action Extrait

Vous pouvez utiliser des services web basés sur SOAP avec des scripts Studio. Cela requiert d'importer un fichier WSDL ou une DLL proxy dans Studio. La DLL importée doit être autorisée par NiCE CXone. Après avoir autorisé la DLL, celle-ci est sauvegardée à la racine du stockage fichier du système NiCE CXone.

L'utilisation des services web SOAP nécessite l'assistance de NiCE CXone. Contactez votre représentant de compte 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 un Snippet Action à votre script. Dans la fenêtre de l'éditeur Snippet, ajoutez un USES déclaration qui nomme le fichier DLL proxy que vous avez généré et stocké dans le stockage fichier 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 différemment en fonction de la façon dont il a été conçu. Il peut être nécessaire de modifier l’exemple de code pour qu’il fonctionne avec le service que vous appelez.

Le XML que vous utilisez ne peut pas inclure de guillemets doubles lorsque vous l'utilisez dans un Extrait action. 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 ( ’ ). Cela 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 Variable dans le code de l'extrait doivent toujours ê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")