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.

Il s'agit d'une méthode non recommandée pour effectuer des appels REST, car elle a le potentiel de ralentir la gestion des contacts et de provoquer de graves problèmes de performance avec la plateforme. Utilisez plutôt une de ces méthodes privilégiées :

  • Integration Hub : Celle-ci 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 pour effectuer les appels est la méthode que vous devez utiliser. Si vous devez utiliser SNIPPET, consultez les recommandations pour savoir comment effectuer ces Appels API de manière plus sûre.

In addition to seeing HTTP status codes in réponses, you may see a -1 code. Il s’agit d’un code interne indiquant qu’une erreur est survenue dans la réponse.

Attention

Il n'est pas recommandé d'effectuer des Appels API au sein d'un extrait. Cela peut entraîner de graves problèmes de performances qui ont une incidence 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 les Appels API :

  • Limitez les délais d'expiration dans vos Appels API. Une recommandation générale est que les délais d'expiration ne dépassent pas deux secondes. Les délais d'expiration par défaut peuvent être plus longs, il convient donc de toujours vérifier les délais d'expiration pour s'assurer qu'ils ne dépassent pas ce maximum. Si vous constatez que des délais d'expiration plus longs sont nécessaires, ajustez votre service Web si possible afin d'améliorer ses temps de réponse.
  • Soyez extrêmement prudent avec la logique de boucle. La combinaison de boucles et de longs délais d'attente amplifie l'impact potentiel sur votre système.

  • 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: 

    • Filtrer les données dans la réponse API : Par exemple, si vous utilisez l'API Reporting 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 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 API pour renvoyer uniquement les données dont vous avez besoin : Par exemple, si vous utilisez l'API de création de rapports 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 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 effectuer aucune des deux options précédentes, créez un middleware qui effectue des filtres en fonction de critères personnalisés que vous définissez. Si vous procédez ainsi, assurez-vous que votre middleware n'ajoute pas de latence à l'appel.

Connexion à des services Web RESTful avec une Action Extrait

 

You can use Studio scripts to connect with RESTful APIs using the REST proxy in a Snippet action. You can access this service with the GetRestProxy() function. The REST proxy allows your scripts to interact with remote web servers. It provides some properties and functions that you can use to do this. The properties and functions are described later in this section. The NiCE CXoneplatform lets REST APIs return up to 32 KB of data. This limitation is imposed at the platform level and is strictly enforced.

Le proxy REST nécessite l'utilisation de 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. You pouvez également créer dynamiquement des objets pouvant être convertis en XML ou en JSON. Ces fonctionnalités sont nécessaires lors de l'utilisation des API RESTful.

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

É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 lors de la connexion à des 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 - text/xml
  • P4 : verbe d’API REST ; chaîne
AjouterEntête Ajoute un en-tête personnalisé à la requête HTTP.
ClearHeaders Efface tous les en-têtes personnalisés ajoutés 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 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 nécessite d'importer un WSDL ou un Proxy DLL dans Studio. La DLL importée doit être autorisée par NiCE CXone. Après avoir autorisé la DLL, elle est sauvegardée dans 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 voulez utiliser un service Web basé sur SOAP dans un script Studio, vous devez créer un snippet. ajouter un Snippet action à votre script. Dans la fenêtre de l'éditeur extrait, ajoutez un USES instruction 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 est conçu. 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 guillemets doubles lorsque vous l'utilisez dans un SNIPPET 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")