API et scripts

Dans vos scripts Studio, vous pouvez établir une connexion à des services web qui utilisent les normes d’API SOAP et RESTful.

Options prises en charge

Studio prend en charge les méthodes suivantes de connexion aux services web :

Option	Détails
Action StudioREST API	L’action Studio REST API permet d’effectuer des appels d’API REST à partir de vos scripts. Cette méthode : peut traiter des charges plus élevées qu’avec des appels RESTfull dans une action SNIPPET, en particulier à grande échelle ; est la méthode à privilégier pour effectuer des appels d’API dans les scripts ; est l’option à utiliser si vos appels contiennent un JSON.
Actions Studiod’API CXone	Studio contient de nombreuses actions d’API qui vous permettent d’effectuer des appels aux API CXone à partir de vos scripts. Toutes les API CXone ne sont pas disponibles sous forme d’action, mais lorsqu’elles le sont, vous devez les utiliser plutôt que de passer par une autre méthode. Vous trouverez les actions API dans la section API de l’onglet Framework dans Desktop Studio et dans la palette Actions d’API dans CXone Studio.
Actions SNIPPET	Il est possible d’écrire du code dans une action SNIPPET pour établir une connexion aux services web RESTful et SOAP à partir de votre script. Cette méthode n’est pas recommandée pour effectuer des appels REST, car elle ralentit le traitement du contact. En revanche, vous devez l’utiliser dans les cas suivants : Vos appels incluent des données XML. Vous vous connectez à un service SOAP.

Option

Détails

Action StudioREST API

L’action Studio REST API permet d’effectuer des appels d’API REST à partir de vos scripts. Cette méthode :

peut traiter des charges plus élevées qu’avec des appels RESTfull dans une action SNIPPET, en particulier à grande échelle ;
est la méthode à privilégier pour effectuer des appels d’API dans les scripts ;
est l’option à utiliser si vos appels contiennent un JSON.

Actions Studiod’API CXone

Studio contient de nombreuses actions d’API qui vous permettent d’effectuer des appels aux API CXone à partir de vos scripts. Toutes les API CXone ne sont pas disponibles sous forme d’action, mais lorsqu’elles le sont, vous devez les utiliser plutôt que de passer par une autre méthode. Vous trouverez les actions API dans la section API de l’onglet Framework dans Desktop Studio et dans la palette Actions d’API dans CXone Studio.

Actions SNIPPET

Il est possible d’écrire du code dans une action SNIPPET pour établir une connexion aux services web RESTful et SOAP à partir de votre script. Cette méthode n’est pas recommandée pour effectuer des appels REST, car elle ralentit le traitement du contact. En revanche, vous devez l’utiliser dans les cas suivants :

Vos appels incluent des données XML.
Vous vous connectez à un service SOAP.

Limitations concernant la taille de données renvoyées

La plate-forme CXone permet aux API REST de renvoyer jusqu’à 32 Ko de données. Cette limite évite les pannes et de rendre les clusters instables. Elle s’applique de manière stricte.

Cette limite concerne toute méthode de connexion aux services web, y compris l’action REST API et les appels effectués avec l’action SNIPPET. Si possible, utilisez l’action REST API à la place de l’action SNIPPET pour vos API REST. L’action REST API est assortie d’une limite de 32 Ko de données renvoyées, mais elle peut traiter une charge plus élevée que la méthode SNIPPET.

Pour réduire la taille des données qui vous sont renvoyées :

Filtrez les données dans la réponse de l’API. Par exemple, si vous utilisez l’API de génération de rapports NICE pour obtenir des contacts, vous pouvez filtrer les résultats en fonction des champs startDate et endDate du contact. Cet appel d’API vous permet également de renvoyer un nombre maximal d’éléments. Reportez-vous à la documentation de l’API appelée pour déterminer les filtres que vous pouvez utiliser.
Mettez à jour la requête d’API pour renvoyer uniquement les données dont vous avez besoin. Par exemple, si vous utilisez l’API de génération 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 appelée pour déterminer les limites que vous pouvez utiliser.

Si vous ne pouvez exécuter aucune des options précédentes, créez un middleware.

Code d’erreur -1

Le code d’erreur -1 est un code interne qui sert à identifier une erreur rencontrée avec un appel d’API. En particulier, ce code indique qu’il s’agit d’une situation où un code de statut HTTP ne sera pas renvoyé, ou que le code est renvoyé, mais qu’il ne peut pas être transmis au script.

La description du statut qui accompagne le code d’erreur -1 peut vous aider à déterminer le problème. Voici les descriptions de statut qui peuvent accompagner ce code :

La demande a été abandonnée : l’opération a dépassé le délai d’attente. La demande a pu être traitée ou non. La validation devrait avoir lieu avant de configurer une boucle en réponse au code de statut -1. Il peut être nécessaire de modifier le paramètre de délai d’attente dans l’appel en utilisant la propriété ProxyTimeoutSeconds.
Primitive JSON non valide. L’analyseur JSON n’a pas compris la réponse. Il se peut que la réponse contienne des caractères non valides ou qu’elle ne soit pas au format JSON. Cette erreur se produit souvent lorsque la réponse est envoyée dans un fichier HTML. Vous pouvez tester la réponse dans le débogueur de snippet. L’article de la base de connaissance La réponse d’API REST n’est pas un fichier JSON ou XML valide peut vous aider.
Les données au niveau racine ne sont pas valides. L’analyseur XML n’a pas compris la réponse. Il se peut que la réponse contienne des caractères non valides ou qu’elle ne soit pas au format XML. Cette erreur se produit souvent lorsque la réponse est envoyée dans un fichier HTML. L’article de la base de connaissance La réponse d’API REST n’est pas un fichier JSON ou XML valide peut vous aider.
“doctype” est un jeton inattendu. Le jeton attendu est “DOCTYPE”. Voir Les données au niveau racine ne sont pas valides dans cette liste.
La balise ouvrante “br” à la ligne x position x ne correspond pas à la balise de fin “body”. Voir Les données au niveau racine ne sont pas valides dans cette liste.
La connexion sous-jacente a été fermée : une erreur inattendue s’est produite lors d’un envoi. Souvent, cela signifie qu’il y a un problème avec la négociation TLS. Ce message peut aussi être provoqué par une adresse IP ou un port qui n’est pas ouvert sur un pare-feu ; l’utilisation d’une version ancienne de TLS non prise en charge ; des certificats non valides ou arrivés à expiration ; l’utilisation d’une adresse IP avec HTTP, ou autres problèmes de ce type. Pour résoudre ce problème, consultez les journaux de pare-feu sur le serveur de réception.
La connexion sous-jacente est fermée : impossible d’établir une relation de confiance pour le canal sécurisé SSL/TLS. Voir La connexion sous-jacente a été fermée : une erreur inattendue s’est produite lors d’un envoi dans cette liste.
La demande a été abandonnée : impossible de créer un canal sécurisé SSL/TLS. Voir La connexion sous-jacente a été fermée : une erreur inattendue s’est produite lors d’un envoi dans cette liste.
Réponse trop volumineuse. (> 32 Ko). La réponse contient plus de 32 Ko de données. Dans ce cas, la réponse est ignorée, car le système ne peut pas stocker plus de 32 Ko dans une seule variable. La réponse doit être modifiée ou filtrée pour réduire la quantité de données renvoyée.