API et scripts

Dans vos scripts Studio, vous pouvez vous connecter à des services Web qui utilisent les normes d’API SOAP ou RESTful.

Options prises en charge

Studio prend en charge les méthodes suivantes pour la connexion aux services Web :

Option	Détails
Action Studio de l’API REST	L’action REST API Studio vous permet d’effectuer des appels d’API RESTful à partir de vos scripts. Cette méthode : Peut gérer des charges plus importantes que les appels RESTful dans une action SNIPPET, en particulier à grande échelle. Est la méthode préférée pour effectuer des appels d’API dans les scripts. Est l’option à utiliser si vos appels incluent du JSON.
Actions Studio de l’API CXone	Studio a de nombreuses actions d’API qui vous permettent de faire des appels d’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 au lieu d’une autre méthode. Vous trouverez les actions d’API dans la section API de l’onglet Cadre dans Desktop Studio et dans la palette d’actions API dans CXone Studio.
Actions EXTRAIT DE CODE (SNIPPET)	Vous pouvez écrire du code dans une action SNIPPET pour vous connecter à des services Web RESTful ou SOAP à partir de votre script. Cette méthode n’est pas recommandée pour les appels REST, car elle peut ralentir la gestion des contacts. Toutefois, vous devez utiliser cette méthode si : Vos appels incluent du XML. Vous vous connectez à un service SOAP.

Option

Détails

Action Studio de l’API REST

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

Peut gérer des charges plus importantes que les appels RESTful dans une action SNIPPET, en particulier à grande échelle.
Est la méthode préférée pour effectuer des appels d’API dans les scripts.
Est l’option à utiliser si vos appels incluent du JSON.

Actions Studio de l’API CXone

Studio a de nombreuses actions d’API qui vous permettent de faire des appels d’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 au lieu d’une autre méthode. Vous trouverez les actions d’API dans la section API de l’onglet Cadre dans Desktop Studio et dans la palette d’actions API dans CXone Studio.

Actions EXTRAIT DE CODE (SNIPPET)

Vous pouvez écrire du code dans une action SNIPPET pour vous connecter à des services Web RESTful ou SOAP à partir de votre script. Cette méthode n’est pas recommandée pour les appels REST, car elle peut ralentir la gestion des contacts. Toutefois, vous devez utiliser cette méthode si :

Vos appels incluent du XML.
Vous vous connectez à un service SOAP.

Limitation de la taille des données renvoyées

La plateforme CXone permet aux API REST de renvoyer jusqu’à 32 ko de données. Cette limite permet d’éviter l’instabilité et les pannes de cluster. Elle est strictement appliquée.

Cette limite s’applique à toute méthode de connexion aux services Web, y compris l’action REST API et , en faisant des appels avec l’action EXTRAIT DE CODE. Si vous le pouvez, utilisez l’action REST API au lieu de l’action SNIPPET pour vos API REST. REST API a une limite de retour de 32 ko, mais elle peut gérer une charge plus importante que la méthode SNIPPET.

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 rapports NICE pour obtenir des contacts, vous pouvez filtrer les résultats en fonction de la startDate et de la endDate du contact. Cet appel API vous permet également de renvoyer et de limiter le nombre d’éléments en tête de liste. Reportez-vous à la documentation de l’API que vous appelez pour déterminer le filtrage que vous pouvez utiliser.
Mettez à jour la demande d’API pour qu’elle ne renvoie que les données dont vous avez besoin. Par exemple, si vous utilisez l’API de rapports NICE pour obtenir des contacts, vous pouvez utiliser les champs contactId ou agentId pour ne renvoyer que les données pertinentes. Reportez-vous à la documentation de l’API que vous appelez pour déterminer les limites de données que vous pouvez utiliser.

Si vous ne pouvez pas utiliser l’une des options précédentes, créez un intergiciel.

Code d’erreur -1

Le code d’erreur -1 est un code interne utilisé pour indiquer qu’une erreur a été rencontrée lors d’un appel à l’API. Plus précisément, ce code indique qu’il s’agit d’une situation dans laquelle un code d’état HTTP n’est pas renvoyé, ou qu’il est renvoyé, mais ne peut pas être transmis au script.

La description de l’état qui accompagne le code d’erreur -1 peut vous aider à déterminer le problème. Les descriptions d’état qui peuvent accompagner ce code sont les suivantes :

La demande a été interrompue : L’opération a expiré. La demande peut avoir été traitée ou non. La validation doit avoir lieu avant de créer une boucle en réponse à un code d’état -1. Il se peut que vous deviez modifier le paramètre de dépassement de délai dans l’appel à l’aide de la propriété ProxyTimeoutSeconds.
JSON Primitive non valide. L’analyseur JSON était confus par la réponse. La réponse contenait peut-être des caractères non valides ou n’était pas au format JSON. Cette erreur se produisait souvent lorsque la réponse était envoyée au format HTML. Vous pouvez tester la réponse dans le débogueur d’extraits de code. L’article de la base de connaissances La réponse de l’API REST n’est pas dans un format JSON ou XML valide peut vous aider.
Les données au niveau racine ne sont pas valides. L’analyseur XML était confus par la réponse. La réponse contenait peut-être des caractères non valides ou n’était pas au format XML. Cette erreur se produisait souvent lorsque la réponse était envoyée au format HTML. L’article de la base de connaissances La réponse de l’API REST n’est pas dans un format JSON ou XML valide peut vous aider.
’doctype’ est un jeton inattendu. Le jeton attendu est ’DOCTYPE’. Consultez Les données au niveau racine ne sont pas valides dans cette liste.
La balise de début ’br’ à la ligne x position x ne correspond pas à la balise de fin ’body’. Consultez 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 de l’envoi. Souvent, cela signifie qu’il y a un problème avec l’établissement de liaison TLS. Cela peut également être dû à une adresse IP ou un port non ouvert(e) sur un pare-feu, à l’utilisation d’une version ancienne et non prise en charge de TLS, à des certificats non valides ou expirés, à l’utilisation d’une adresse IP en combinaison avec HTTPS, ou à d’autres problèmes similaires. Dépannez cette réponse à l’aide des journaux du pare-feu du côté du serveur de réception.
La connexion sous-jacente a été fermée : Impossible d’établir une relation de confiance pour le canal sécurisé SSL/TLS. Consultez La connexion sous-jacente a été fermée : Une erreur inattendue s’est produite lors de l’envoi dans cette liste.
La demande a été interrompue : Impossible de créer un canal sécurisé SSL/TLS. Consultez La connexion sous-jacente a été fermée : Une erreur inattendue s’est produite lors de l’envoi dans cette liste.
Réponse trop grande (> 32 ko). La réponse contient plus de 32 ko de données. Dans ce cas, la réponse est rejetée, car le système n’a pas la possibilité de stocker plus de 32 ko dans une variable. La réponse doit être modifiée ou filtrée pour réduire la quantité de données renvoyées.