Effectuer des appels API à partir d'une action SNIPPET

Vous pouvez effectuer des appels REST ou SOAP à partir d'une action SNIPPET. Il s'agit d'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 peut ralentir la gestion des contacts et causer de graves problèmes de performance avec la plateforme. Utilisez plutôt une de ces méthodes privilégiées :

  • Integration Hub : Ceci est l'option la plus sécuritaire et garantit que vos identifiants client ne sont pas stockés en texte brut.
  • Action de l'API REST : L'utilisation de l'REST API action est l'option alternative recommandée si vous n'utilisez pas Integration Hub.

Toutefois, si vous vous connectez à un service Web SOAP ou si vos appels API comprennent du XML, effectuer des appels à partir 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écuritaire.

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

Mise en garde

Il n'est pas recommandé de créer des appels API dans un extrait. Cela peut entraîner de graves problèmes de performance qui touchent la gestion des contacts et qui ont une incidence négative sur votre locataire. Pour une expérience plus sécuritaire et plus fiable, utilisez l'une des méthodes privilégiées suivantes.

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

  • Limitez les délais d'attente dans vos appels API. Une 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, alors vérifiez 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 requis, ajustez votre service Web si possible pour améliorer ses temps de réponse.
  • Soyez extrêmement prudent avec la logique de boucle. La combinaison des boucles et des délais d'attente longs amplifie l'incidence potentielle sur votre système.

  • La taille maximum de la réponse dans NiCE CXone est de 32 Ko. Cette limite est strictement appliquée afin d’éviter l’instabilité et les pannes du cluster. Studio applique cette limite lors de l’enregistrement du script, mais Desktop Studio ne l’applique pas. Si possible, utilisez REST API actionaction ou Integration Hub à la place de l’action SNIPPET pour effectuer des Appels api. Elles ont la même limite, mais peuvent gérer 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 Reporting NiCE pour obtenir des contacts, vous pouvez filtrer les résultats selon startDate et endDate du contact. Cet Appel api vous permet également de renvoyer et de limiter un nombre haut d’éléments. Reportez-vous à la documentation de l’API fournie avec votre intégration de script pour déterminer les Filtres que vous pouvez utiliser.

    • Mettez à jour la demande d’API pour renvoyer uniquement les données dont vous avez besoin : Par exemple, si vous utilisez l’API Reporting NiCE pour obtenir des contacts, vous pouvez utiliser les champs contactId ou agentId pour renvoyer uniquement les données pertinentes. Reportez-vous à la documentation de l’API fournie avec votre intégration de script pour déterminer les limites de données que vous pouvez utiliser.

    • Créez un intergiciel : Si vous ne pouvez faire ni l’une ni l’autre des Options précédentes, créez un intergiciel qui effectue le filtres en fonction de critères personnalisés que vous définissez. Si vous procédez ainsi, assurez-vous que votre intergiciel n’ajoute pas de latence à l’Appel.

Se connecter à des services Web RESTful avec une action SNIPPET

 

Vous pouvez utiliser des scripts Studio pour vous connecter à des API RESTful à l'aide du proxy REST dans une Snippet action. 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 certaines propriétés et 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 retourner jusqu'à 32 Ko de données. Cette limitation est imposée au niveau de la plateforme et est strictement appliquée.

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

Pour utiliser le proxy REST, ajoutez une action Snippet à votre script et ouvrez la fenêtre de l'éditeur Snippet. Appelez la fonction GetRESTProxy() à l'aide de la syntaxe suivante :

ASSIGN proxy = GetRESTProxy() 

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

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

Properties (propriétés)

Propriété Détails
StatusCode

Contient le code d'état HTTP suivant 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 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.

Selon l'appel que vous effectuez, vous devrez peut-être modifier l'en-tête. Par exemple, si vous envoyez du JSON, vous devriez le remplacer par application/json. Vous devez modifier cette propriété.

ProxyTimeoutSeconds Vous permet de modifier le dépassement de délai de la requête. La valeur par défaut est 10 secondes. Vous devez modifier cette propriété.

Fonctions

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

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

Exécute une demande HTTP vers l’URL désignée, où :

  • 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 » - text/xml
  • P4 : Verbe API REST; chaîne
AddHeader Ajoute un en-tête personnalisé à la demande 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 une utilisation avec getRESTProxy(). En savoir plus sur cette fonction sur la page d'aide Fonctions intégrées.

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 aux services Web SOAP avec une Action SNIPPET

Vous pouvez utiliser des services Web basés sur SOAP avec des scripts Studio. Cela nécessite que vous importiez un fichier WSDL ou un Proxy DLL dans Studio. Le fichier DLL importé doit être autorisé par NiCE CXone. Une fois le fichier DLL autorisé, il est enregistré à la racine du stockage fichier de votre NiCE CXone système.

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 souhaitez utiliser un service Web basé sur SOAP dans un script Studio, vous devez créer un extrait. Ajoutez une Snippet action à votre script. Dans la fenêtre de l'éditeur Snippet, ajoutez une instruction USES qui nomme le fichier proxy DLL que vous avez généré et stocké dans le stockage fichier de votre unité commerciale.

L’extrait de code 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)

Effectuer un appel SOAP avec un enveloppeur REST

Cette option vous permet d'utiliser des méthodologies API REST pour appeler des services Web basés sur SOAP. Chaque service Web répond différemment selon la façon dont il est conçu. Vous devrez peut-être modifier le code d'exemple 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 une SNIPPET action. Vous pouvez utiliser l’une des alternatives suivantes :

  • Remplacer chaque guillemet double par {char(34)}, qui insère un caractère guillemet double directement dans la chaîne. Cette option est illustrée dans le premier exemple de l’étape 2, plus loin dans cette section.
  • Remplacer chaque guillemet double par un guillemet simple ( ' ). Ceci est acceptable en XML et dans les actions SNIPPET. Cette option est illustrée dans le deuxième exemple de l’étape 2, plus loin dans cette section.

Vous n'avez besoin de remplacer que les guillemets doubles qui apparaissent dans le XML. Les assignations de variables dans le code de l’extrait doivent toujours être placées entre guillemets.

  1. Créez un mandataire REST, attribuez l’en-tête ContentType, comme exigé par le service Web auquel vous vous connectez, et l’URL du 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 est formatée en XML pour encoder tous les paramètres requis. Vous pouvez procéder de deux façons :

    • Séparer chaque ligne. Cette option est plus facile à lire.

    • Concaténer le tout en une seule ligne.

    Des exemples de ces deux options sont inclus dans cette étape.

    Cet exemple montre l'enveloppe séparée en lignes. De plus, cet exemple montre les guillemets doubles 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 de l'enveloppe concaténé sur une seule ligne. Dans cet exemple, les guillemets doubles ont été 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")